metafold package

Submodules

Module contents

class metafold.MetafoldClient(access_token: str | None = None, project_id: str | None = None, client_id: str | None = None, client_secret: str | None = None, auth_domain: str = 'metafold3d.us.auth0.com', base_url: str = 'https://api.metafold3d.com/')

Bases: Client

Metafold REST API client.

projects

Sub-client for projects endpoint.

Type:: metafold.projects.ProjectsEndpoint

assets

Sub-client for assets endpoint.

Type:: metafold.assets.AssetsEndpoint

jobs

Sub-client for jobs endpoint.

Type:: metafold.jobs.JobsEndpoint

metafold.projects module

class metafold.projects.Access(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Project access scope.

PRIVATE: Project is private to owner.

PUBLIC: Project may be accessed by unauthenticated users.

Bases: object

Project resource.

id

Project ID.

Type:: str

user

Project user ID.

Type:: str

name

Project name.

Type:: str

access

Project access.

Type:: metafold.projects.Access

created

Project creation datetime.

Type:: datetime.datetime

modified

Project last modified datetime.

Type:: datetime.datetime

thumbnail

URL to project thumbnail.

Type:: str | None

project

Arbitrary project data.

Type:: dict[str, Any] | None

graph

Project graph data.

Type:: metafold.func_types.Graph | None

class metafold.projects.ProjectsEndpoint(client: Client)

Bases: object

Metafold projects endpoint.

create(name: str, access: Access | str = Access.PRIVATE, data: dict[str, Any] | None = None) → Project

Create a project.

Parameters:

name – Project name.
access – Project access. By default projects are private.
data – Optional project data. This parameter accepts arbitrary JSON-serializable data. Helpful for tracking application state.

Returns:

Project resource.

delete(id: str) → None

Delete an project.

Parameters:: id – Override ID of project to update. Defaults to client project ID.

duplicate(id: str, name: str, access: Access | str = Access.PRIVATE) → Project

Duplicate a project.

Parameters:

id – Project to duplicate.
name – New project name.
access – New project access. By default projects are private.

Returns:

Project resource.

get(id: str | None = None) → Project

Get an project.

Parameters:: id – Override ID of project to get. Defaults to client project ID.
Returns:: Project resource.

list(sort: str | None = None, q: str | None = None) → list[Project]

List projects.

Parameters:

sort – Sort string. For details on syntax see the Metafold API docs. Supported sorting fields are: “id”, “user”, “name”, “created”, and “modified”.
q – Query string. For details on syntax see the Metafold API docs. Supported search fields are: “id”, “user”, and “name”.

Returns:

List of project resources.

Update a project.

Parameters:

id – Override ID of project to update. Defaults to client project ID.
name – Optional project name.
access – Optional project access.
data – Optional project data. This parameter accepts arbitrary JSON-serializable data. Helpful for tracking application state.
graph – Optional shape JSON.

Returns:

Updated project resource.

metafold.assets module

class metafold.assets.Asset(*, id: str, filename: str, size: int, checksum: str, created: str | datetime, modified: str | datetime)

Bases: object

Asset resource.

id

Asset ID.

Type:: str

filename

Asset filename.

Type:: str

size

File size in bytes.

Type:: int

checksum

File checksum.

Type:: str

created

Asset creation datetime.

Type:: datetime.datetime

modified

Asset last modified datetime.

Type:: datetime.datetime

class metafold.assets.AssetsEndpoint(client: Client)

Bases: object

Metafold assets endpoint.

create(f: str | bytes | PathLike | IO[bytes], project_id: str | None = None) → Asset

Upload an asset.

Parameters:

f – File-like object (opened in binary mode) or path to file on disk.
project_id – Asset project ID.

Returns:

Asset resource.

delete(asset_id: str, project_id: str | None = None) → None

Delete an asset.

Parameters:

asset_id – ID of asset to delete.
project_id – Asset project ID.

download_file(asset_id: str, path: str | PathLike, project_id: str | None = None)

Download an asset.

Parameters:

asset_id – ID of asset to download.
path – Path to downloaded file.
project_id – Asset project ID.

get(asset_id: str, project_id: str | None = None) → Asset

Get an asset.

Parameters:

asset_id – ID of asset to get.
project_id – Asset project ID.

Returns:

Asset resource.

list(sort: str | None = None, q: str | None = None, project_id: str | None = None) → list[Asset]

List assets.

Parameters:

sort – Sort string. For details on syntax see the Metafold API docs. Supported sorting fields are: “id”, “filename”, “size”, “created”, or “modified”.
q – Query string. For details on syntax see the Metafold API docs. Supported search fields are: “id” and “filename”.
project_id – Asset project ID.

Returns:

List of asset resources.

update(asset_id: str, f: str | bytes | PathLike | IO[bytes], project_id: str | None = None) → Asset

Update an asset.

Parameters:

asset_id – ID of asset to update.
f – File-like object (opened in binary mode) or path to file on disk.
project_id – Asset project ID.

Returns:

Updated asset resource.

metafold.jobs module

class metafold.jobs.Job(*, id: str, name: str | None = None, type: str, parameters: dict[str, Any], created: str | datetime, finished=None, state: str, assets: list[dict[str, Any] | Asset], meta: dict[str, Any])

Bases: object

Job resource.

id

Job ID.

Type:: str

name

Job name.

Type:: str | None

type

Job type.

Type:: str

parameters

Job parameters.

Type:: dict[str, Any]

created

Job creation datetime.

Type:: datetime.datetime

finished

Job finished datetime.

Type:: datetime.datetime | None

state

Job state. May be one of: pending, started, success, or failure.

Type:: str

assets

List of generated asset resources.

Type:: list[metafold.assets.Asset]

meta

Additional metadata generated by the job.

Type:: dict[str, Any]

class metafold.jobs.JobsEndpoint(client: Client)

Bases: object

Metafold jobs endpoint.

get(job_id: str, project_id: str | None = None) → Job

Get a job.

Parameters:

job_id – ID of job to get.
project_id – Job project ID.

Returns:

Job resource.

list(sort: str | None = None, q: str | None = None, project_id: str | None = None) → list[Job]

List jobs.

Parameters:

sort – Sort string. For details on syntax see the Metafold API docs. Supported sorting fields are: “id”, “name”, or “created”.
q – Query string. For details on syntax see the Metafold API docs. Supported search fields are: “id”, “name”, “type”, and “state”.
project_id – Job project ID.

Returns:

List of job resources.

poll(url: str, timeout: int | float = 120, every: int | float = 1) → Response

Poll the given URL in regular intervals.

Helpful for waiting on job results given a status URL.

Parameters:

timeout – Time in seconds to wait for a result.
every – Frequency in seconds.

Returns:

HTTP response.

run(type: str, params: dict[str, Any], name: str | None = None, timeout: int | float = 120, project_id: str | None = None) → Job

Dispatch a new job and wait for a result.

See Metafold API docs for the full list of jobs.

Parameters:

type – Job type.
params – Job parameters.
name – Optional job name.
timeout – Time in seconds to wait for a result.
project_id – Job project ID.

Returns:

Completed job resource.

run_status(type: str, params: dict[str, Any], name: str | None = None, project_id: str | None = None) → str

Dispatch a new job and return immediately without waiting for result.

See Metafold API docs for the full list of jobs.

Parameters:

type – Job type.
params – Job parameters.
name – Optional job name.
project_id – Job project ID.

Returns:

Job status url.

update(job_id: str, name: str | None = None, project_id: str | None = None) → Job

Update a job.

Parameters:

job_id – ID of job to update.
name – New job name. The existing name remains unchanged if None.
project_id – Job project ID.

Returns:

Updated job resource.

metafold.client module

class metafold.client.Client(base_url: str, access_token: str | None = None, project_id: str | None = None, auth: AuthProvider | None = None)

Bases: object

Base client.

metafold.func module

metafold.func.BoxFramePrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

metafold.func.BoxPrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

class metafold.func.CSG(a: TypedFunc[Literal[FuncType.FLOAT]], b: TypedFunc[Literal[FuncType.FLOAT]], parameters: CSG_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

metafold.func.CSGIntersect(a: TypedFunc[Literal[FuncType.FLOAT]], b: TypedFunc[Literal[FuncType.FLOAT]], smoothing: float | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

metafold.func.CSGSubtract(a: TypedFunc[Literal[FuncType.FLOAT]], b: TypedFunc[Literal[FuncType.FLOAT]], smoothing: float | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

metafold.func.CSGUnion(a: TypedFunc[Literal[FuncType.FLOAT]], b: TypedFunc[Literal[FuncType.FLOAT]], smoothing: float | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

class metafold.func.CSG_Parameters

Bases: TypedDict

operation: Literal['Intersect', 'Subtract', 'Union']

smoothing: float

metafold.func.CappedConePrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

metafold.func.CapsulePrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

class metafold.func.ComputeNormals(points: TypedFunc[Literal[FuncType.VEC3F]], volume: Func, parameters: ComputeNormals_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.ComputeNormals_Parameters

Bases: TypedDict

volume_offset: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

volume_size: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

metafold.func.CylinderPrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

metafold.func.EllipsoidPrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

class metafold.func.GenerateSamplePoints(parameters: GenerateSamplePoints_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.GenerateSamplePoints_Parameters

Bases: TypedDict

offset: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

resolution: Annotated[list[int], 3] | ndarray[Literal[3], dtype[int64]]

size: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.GradeCellSize(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: GradeCellSize_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.GradeCellSize_Parameters

Bases: TypedDict

num_steps: int

offset: float

shape_size: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

shape_type: Literal['Box', 'Cylinder', 'Ellipsoid', 'Plane']

shape_xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

step_size: float

width: float

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.InterpolateBoundaryCoords(points: TypedFunc[Literal[FuncType.VEC3F]], boundary_data: ParametrizationAsset, mesh_data: TriangleMeshAsset, parameters: InterpolateBoundaryCoords_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.InterpolateBoundaryCoords_Parameters

Bases: TypedDict

tolerance: float

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.LinearFilter(inputa: TypedFunc[Literal[FuncType.FLOAT]], inputb: TypedFunc[Literal[FuncType.FLOAT]], parameters: LinearFilter_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.LinearFilter_Parameters

Bases: TypedDict

scale_a: float

scale_b: float

metafold.func.LinkPrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

class metafold.func.LoadSamplePoints(parameters: LoadSamplePoints_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.LoadSamplePoints_Parameters

Bases: TypedDict

points: list[Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]] | ndarray

class metafold.func.LoadVolume(volume_data: VolumeAsset, parameters: LoadVolume_Parameters | None = None): Bases: Func

class metafold.func.LoadVolume_Parameters

Bases: TypedDict

component_type: Literal['Byte', 'Float', 'Integer', 'None', 'Vec2f', 'Vec2i', 'Vec3f', 'Vec3i', 'Vec4f', 'Vec4i']

resolution: Annotated[list[int], 3] | ndarray[Literal[3], dtype[int64]]

class metafold.func.MapTexturePrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], image: TypedFunc[Literal[FuncType.FLOAT]], parameters: MapTexturePrimitive_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.MapTexturePrimitive_Parameters

Bases: TypedDict

box_width: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

scale: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

shape_type: Literal['Box', 'Cylinder', 'Ellipsoid', 'Plane']

shape_xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

metafold.func.PlanePrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

metafold.func.PointSource(eval_: Evaluator) → TypedResult[Literal[FuncType.VEC3F]]

class metafold.func.Redistance(samples: TypedFunc[Literal[FuncType.FLOAT]], parameters: Redistance_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.Redistance_Parameters

Bases: TypedDict

post_offset: float

pre_offset: float

class metafold.func.SampleBeam(points: TypedFunc[Literal[FuncType.VEC3F]], bvh_data: LineNetworkBvhAsset, network_data: LineNetworkAsset, parameters: SampleBeam_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.SampleBeam_Parameters

Bases: TypedDict

node_radius: float

node_type: Literal['None', 'Sphere']

section_radius: float

section_type: Literal['Box', 'Circle', 'Cross']

smoothing: float

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.SampleBox(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.SampleBox_Parameters

Bases: TypedDict

free_param: float

shape_type: Literal['Box', 'BoxFrame', 'CappedCone', 'Capsule', 'Cylinder', 'Ellipsoid', 'Link', 'Plane', 'Torus']

size: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.SampleCustomShape(points: TypedFunc[Literal[FuncType.VEC3F]], shader_data: CustomShapeAsset, parameters: SampleCustomShape_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.SampleCustomShape_Parameters

Bases: TypedDict

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.SampleLattice(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleLattice_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.SampleLattice_Parameters

Bases: TypedDict

lattice_data: UnitCell

node_radius: float

node_type: Literal['None', 'Sphere']

scale: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

scale_grading_range: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

scale_grading_scale: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

section_radius: float

section_radius_grading_range: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

section_radius_grading_scale: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

section_type: Literal['Box', 'Circle', 'Cross']

smoothing: float

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.SampleSpinodoid(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleSpinodoid_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.SampleSpinodoid_Parameters

Bases: TypedDict

angles: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

density: float

wave_count: int

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.SampleSurfaceLattice(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleSurfaceLattice_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.SampleSurfaceLattice_Parameters

Bases: TypedDict

lattice_type: Literal['CD', 'CI2Y', 'CP', 'CPM_Y', 'CS', 'CY', 'C_Y', 'D', 'F', 'FRD', 'Gyroid', 'I2Y', 'IWP', 'None', 'P', 'PM_Y', 'S', 'SD1', 'Schwarz', 'SchwarzD', 'SchwarzN', 'SchwarzPW', 'SchwarzW', 'W', 'Y']

scale: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

scale_grading_range: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

scale_grading_scale: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

threshold: float

threshold_grading_offset: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

threshold_grading_range: Annotated[list[float], 2] | ndarray[Literal[2], dtype[float64]]

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.SampleTriangleMesh(points: TypedFunc[Literal[FuncType.VEC3F]], mesh_data: TriangleMeshAsset, parameters: SampleTriangleMesh_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.SampleTriangleMeshBvh(points: TypedFunc[Literal[FuncType.VEC3F]], bvh_data: MeshBvhAsset, mesh_data: TriangleMeshAsset, parameters: SampleTriangleMeshBvh_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.SampleTriangleMeshBvh_Parameters

Bases: TypedDict

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.SampleTriangleMesh_Parameters

Bases: TypedDict

cw_winding: int

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.SampleVolume(points: TypedFunc[Literal[FuncType.VEC3F]], volume: Func, parameters: SampleVolume_Parameters | None = None): Bases: Func

class metafold.func.SampleVolume_Parameters

Bases: TypedDict

volume_offset: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

volume_size: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.Shell(samples: TypedFunc[Literal[FuncType.FLOAT]], parameters: Shell_Parameters | None = None): Bases: TypedFunc[Literal[FLOAT]]

class metafold.func.Shell_Parameters

Bases: TypedDict

offset: float

thickness: float

class metafold.func.Threshold(samples: TypedFunc[Literal[FuncType.FLOAT]], parameters: Threshold_Parameters | None = None): Bases: TypedFunc[Literal[BYTE]]

class metafold.func.Threshold_Parameters

Bases: TypedDict

width: float

metafold.func.TorusPrimitive(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: SampleBox_Parameters | None = None) → TypedFunc[Literal[FuncType.FLOAT]]

class metafold.func.TransformCylindricalCoords(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: TransformCylindricalCoords_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.TransformCylindricalCoords_Parameters

Bases: TypedDict

radial_scale: float

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.TransformMirrorCoords(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: TransformMirrorCoords_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.TransformMirrorCoords_Parameters

Bases: TypedDict

mirror_normal: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

mirror_point: Annotated[list[float], 3] | ndarray[Literal[3], dtype[float64]]

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.TransformSphericalCoords(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: TransformSphericalCoords_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.TransformSphericalCoords_Parameters

Bases: TypedDict

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

class metafold.func.TransformTwistCoords(points: TypedFunc[Literal[FuncType.VEC3F]], parameters: TransformTwistCoords_Parameters | None = None): Bases: TypedFunc[Literal[VEC3F]]

class metafold.func.TransformTwistCoords_Parameters

Bases: TypedDict

axis: Literal['X', 'Y', 'Z']

frequency: float

xform: Annotated[list[float], 16] | ndarray[tuple[Literal[4], Literal[4]], dtype[float64]]

metafold.exceptions module

exception metafold.exceptions.PollTimeout

Bases: Exception

Raised when a dispatched job failed to complete within expected time.