GenerateSamplePoints is a fundamental operator within the Metafold SDK that creates a regular grid of sample points in 3D space. It serves as the starting point for many geometric operations and shape definitions in Metafold.

Users need to use GenerateSamplePoints for several important reasons:

1. Defining the computational domain: It sets up the 3D space where subsequent operations will take place.
2. Controlling resolution: Users can specify the density of sample points, which affects the accuracy and detail of the resulting shapes for rendering and exporting.
3. Providing input for other operators: Many other Metafold operators, such as SampleLattice or various primitives, require a set of sample points as input.

By using GenerateSamplePoints, users create the foundation upon which they can build complex geometric structures, perform analyses, and generate 3D models within the Metafold environment.

from metafold.func import GenerateSamplePoints
import numpy as np

source = GenerateSamplePoints(
    {
        "offset": np.full(3, -10.0)
        "size": np.full(3, 20)
        "resolution": np.full(3, 128) 
    }
)

LoadSamplePoints is a flexible operator that allows users to manually define their own set of points for function evaluations. Users can use this to define irregular grids that sample certain regions in space more densely.

from metafold.func import LoadSamplePoints
import numpy as np

source = LoadSamplePoints(
    {
        "points": np.random.uniform(-10, 20, (1000, 3))
    }
)

LoadVolume is a handy operator for importing 2D and 3D arrays of data. The data is expected to be stored as 32-bit floats and can consist of 1-, 2-, 3-, or 4- dimensional vector. It is imperative that the resolution accurately matches the size of the data.

LoadVolume does not sample the volume, but allocates and fills memory with the given data to be used by subsequent operators in the graph. SampleVolume is such an operator.

It is recommended to cache an implicit representation of a mesh using SampleTriangleMesh on a grid. You can than use this operator to load in the mesh each time for faster evaluation.

from metafold.func import LoadVolume
from metafold.func_types import Volume_Asset
import numpy as np

volume_path = "path/to/binary/volume.bin"
volume_asset = VolumeAsset()
volume_asset["path"] = volume_path

volume = LoadVolume(
    volume_asset,  
    {
        "component_type"
        "resolution": [128, 128, 128]
    }
)

Compute the gradient of a volume at the given sample points.

Metafold represents shapes as the 0-level set of implicit scalar-field defined on a grid. This means that the normal is defined throughout the domain for all shapes. This function allows you to quickly compute the normals at specific locations in space. The locations do not need to be the original grid created via GenerateSamplePoints. They can be from a secondary grid or another set of points generated via LoadSamplePoints .

Apply a cylindrical mapping to the input points. This operator transforms points into a cylindrical coordinate system. When used as input to a sample function for shape creation, it introduces controlled curvature to the shape. This technique is particularly powerful for manipulating lattice structures.

‣

Parameters

Parameter	Type	Description
xform	Mat4	Affine transformation matrix applied to points before the mapping occurs. Defaults to identity matrix.
radial_scale	Float	Used to control the amount of amount of repetition in the radial direction. Defaults to 1.0.

Radial Divisions

2

2

3

3

4

4

5

5

6

6

💡

Advanced Tip In order to divide the “cylindrically-mapped” shape into a fixed number of radial divisions, the proceeding sampling operator should repeat $n$ times in the domain $[0, 2\pi]$ (i.e. 360°) along the Y axis. This is particularly suited to lattice operators as they tile a given unit cell infinitely along each axis.

from metafold.func import GenerateSamplePoints, TransformCylindricalCoords
import numpy as np


source = GenerateSamplePoints(
    {
        "offset": np.full(3, -10.0),
        "size": np.full(3, 20),
        "resolution": np.full(3, 128) 
    }
)

transformed_pts = TransformCylindricalCoords(source, {"radial_scale": 4})

Apply a mirror transformation to the input points. This operator mirrors points across a specified plane in 3D space. When used as input to a sample function for shape creation, it enables the creation of symmetrical shapes across a plane. This technique is useful for creating mirrored versions of existing structures.

‣

Parameters

Parameter	Type	Description
xform	Mat4f	Affine transformation matrix applied to points before the mapping occurs. Defaults to identity matrix.
mirror_normal	Vec3f	Normal vector of mirror plane in world coordinates. Defaults to [0.0, 0.0, 1.0].
mirror_point	Vec3f	Position of the mirror plane in 3D space. Defaults to origin [0.0, 0.0, 0.0].

Off

Off

On

On

from metafold.func import GenerateSamplePoints, TransformMirrorCoords
import numpy as np


source = GenerateSamplePoints(
    {
        "offset": np.full(3, -10.0)
        "size": np.full(3, 20)
        "resolution": np.full(3, 128) 
    }
)

transformed_pts = TransformMirrorCoords(source, {"reflection": 0})

Apply a spherical mapping to the input points. This operator transforms points into a spherical coordinate system. When used as input to a sample function for shape creation, it introduces controlled curvature to the shape in all directions. This technique is particularly powerful for creating spherical or radially symmetric structures and manipulating objects in a spherical space.

‣

Parameters

Parameter	Type	Description
xform	Mat4	Affine transformation matrix applied to points before the mapping occurs. Defaults to identity matrix.

Divisions

2

2

3

3

4

4

5

5

6

6

💡

Advanced Tip In order to divide the “spherically-mapped” shape into a fixed number of divisions, the proceeding sampling operator should repeat $n$ times in the domain $[0, \pi]$ (180°) along the Y axis and in the domain $[0, 2\pi]$ (360°) along the Z axis. This is particularly suited to lattice operators as they tile a given unit cell infinitely along each axis.

from metafold.func import GenerateSamplePoints, TransformSphericalCoords
import numpy as np


source = GenerateSamplePoints(
    {
        "offset": np.full(3, -10.0)
        "size": np.full(3, 20)
        "resolution": np.full(3, 128) 
    }
)

transformed_pts = TransformSphericalCoords(source)

Apply a twisting transformation to the input points. This operator rotates points around a specified axis. When used as input to a sample function for shape creation, it introduces a controlled spiral or helical deformation to the shape. This technique is particularly powerful for creating twisted structures or adding rotational effects to existing geometries.

‣

Parameters

Parameter	Type	Description
axis	String	String representing the main axis of rotation. "X" , "Y" , "Z" . Defaults to "X".
frequency	Float	Approximate number of rotations. Defaults to 1.0

Frequency

-20

-20

-13.333

-13.333

-6.667

-6.667

0

0

6.667

6.667

13.333

13.333

20

20

from metafold.func import GenerateSamplePoints, TransformTwistCoords
import numpy as np


source = GenerateSamplePoints(
    {
        "offset": np.full(3, -10.0)
        "size": np.full(3, 20)
        "resolution": np.full(3, 128) 
    }
)

transformed_pts = TransformTwistCoords(source, {"frequency": 3.0})

Generates a perturbation to distort the 0-level sets of shapes. By remapping input points into u, v image space according to a primitive mapping type the new coordinates are used to sample a grayscale texture. The result is a scalar field defined at all points on the grid. When combined with LinearFilter, it creates a texture-mapped surface effect. The mapping allows for precise control over how the image is applied to the primitive shape, enabling complex surface details and patterns. For a comprehensive guide on implementing this technique, refer to our detailed tutorial on texture mapping.

Sample a primitive shape at the given sample points.

This operator allows users to create common 3D shapes (what we call primitives) for their design needs. Each call allows users to create a single shape that is defined by it’s 0-level of it’s implicit scalar function definition. The primitives here serve as the bedrock for more complicated projects within the Metafold environment. When combined with CSG operations users can define complex geometries for their needs through combining primitives with other sample operators.

A list of all the current available primitives can be found here.

‣

Parameters

Parameter	Type	Description
xform	Mat4	Affine transformation matrix. Defaults to identity matrix.
size	Vec3	Primitive box size. Defaults to [0, 0, 0].
shape_type	String	The type of shape. Defaults to Box. All options: "Box", "BoxFrame", "CappedCone", "Capsule" "Cylinder", "Ellipsoid", "Link", "Plane", "Torus"

Shape Types

Box

Box

BoxFrame

BoxFrame

CappedCone

CappedCone

Capsule

Capsule

Cylinder

Cylinder

Ellipsoid

Ellipsoid

Link

Link

Plane

Plane

Torus

Torus

Sample a complete description of a line network. A line network consists of nodes and edges that define a graph, which can be connected or disconnected. This operator enables sampling and manipulation of line networks, offering customization options similar to those in the SampleLattice operator. Users can adjust various parameters to modify the network's properties and appearance.

This powerful tool allows input of complete beam structures built externally, rather than relying on a unit cell-based definition as in SampleLattice. To optimize line network evaluation, we use a BVH structure. This structure must be created before using this operator by running a create_bvh_from_network_file() job.

The .json file containing the line network must have two fields: "nodes" and "edges". The following example demonstrates how to define a BCC lattice using this format.

{
    "nodes": [
        [0., 0., 0.],
        [1., 0., 0.],
        [0., 1., 0.],
        [1., 1., 0.],
        [1., 0., 1.],
        [0., 1., 1.],
        [1., 1., 1.],
        [.5, .5, .5] 
    ], 
    "edges": [
        [0, 8],
        [1, 8],
        [2, 8],
        [3, 8],
        [4, 8],
        [5, 8],
        [6, 8],
        [7, 9]
    ]
}

SampleCustomShape allows power users to create novel shapes using GLSL shader code. By attaching a SPIRV compiled binary describing a 3D shape, this operator samples it and adds it to your project. This functionality is particularly useful for advanced users who want to:

1. Create complex, mathematically-defined shapes that are not easily achievable with standard primitives.
2. Optimize performance for specific shape calculations.
3. Experiment with procedural shape generation within the Metafold ecosystem.

In order to make use of this tool a user only needs to write GLSL shader code. The job compile_custom_shape() takes this code and converts it to a SPIRV compiled binary digestible by our backend.

Triangle meshes are a widely used representation for 3D geometry. This powerful tool enables you to seamlessly convert triangle mesh geometry into a Metafold implicit representation. By doing so, you can leverage Metafold's advanced capabilities for manipulating and analyzing complex 3D shapes within the implicit framework.

Lattices are formed by infinitely repeating unit cells in all directions. This operator samples beam lattices on a grid specified by GenerateSamplePoints, creating a lattice block that matches the size of the aforementioned operator.

Unit cells are defined via the UnitCell class. They consist of an array of nodes and edges. See below for an example of a BCC unit cell.

Two powerful sets of parameters for lattices are scale_grading_* and section_grading_*. Scale and Section Grading are techniques used to vary the properties of a lattice structure across its volume:

• Scale Grading varies the unit cell scale of the lattice across the structure.
• Section Grading varies the cross-sectional properties of lattice beams.

These grading techniques enable the creation of lattice structures with varying properties, which can optimize performance, weight distribution, or other design objectives.

‣

Parameters

Parameter	Type	Description
lattice_data (Required)	UnitCell	Dictionary with the following keys: nodes: Positions of lattice nodes. edges: Connectivity of lattice nodes. No default.
node_type	String	Shape of lattice nodes. Defaults to "None". All types: "None", "Sphere"
node_radius	Float	Radius of lattice nodes relative to unit cell. Defaults to 0.1.
scale	Vec3f	Unit cell scale. Defaults to [1.0, 1.0, 1.0].
scale_grading_range	Vec2f	Distances of ScaleGrading scalar field to grade between. Defaults to zero vector.
scale_grading_scale	Vec2f	Scaling to apply to upper/lower grading limits. Defaults to zero vector.
section_radius	Float	Radius of lattice beam cross sections relative to unit cell. Defaults to 0.05.
section_type	String	Shape of lattice beam cross sections. Defaults to "Circle". All types: "Box", "Circle", "Cross”
section_radius_grading_range	Vec2f	Distances of SectionRadiusGrading scalar field to grade between. Defaults to zero vector.
section_radius_grading_scale	Vec2f	Scaling to apply to upper/lower grading limits. Defaults to zero vector.
smoothing	Float	Width to smooth joints between nodes and beams by. Defaults to 0.
xform	Mat4f	Affine transformation matrix for the lattice. Defaults to identity matrix.

Lattice Types

bcu-x

bcu-x

bix

bix

body-centered cubic

body-centered cubic

dpe

dpe

epn

epn

epp

epp

face-centered cubic

face-centered cubic

fcb

fcb

iac-d

iac-d

nbo-a

nbo-a

ocu

ocu

pdb

pdb

rhr

rhr

sqc2595

sqc2595

sqc3050

sqc3050

sqc7060

sqc7060

sqc8562

sqc8562

sqc9030

sqc9030

sqc9046

sqc9046

sqc10906

sqc10906

sqc10948

sqc10948

sqc11615

sqc11615

sqc12124

sqc12124

sqc13545

sqc13545

sst-a

sst-a

tbo

tbo

uri

uri

xaf

xaf

xbl

xbl

xbr

xbr

xbr

xbr

Section Types

Box

Box

Circle

Circle

Cross

Cross

Section Radius

0.025

0.025

0.094

0.094

0.162

0.162

0.231

0.231

0.3

0.3

Node Radius

0.1

0.1

0.175

0.175

0.25

0.25

0.325

0.325

0.4

0.4

Scale

0.2

0.2

0.65

0.65

1.1

1.1

1.55

1.55

2.0

2.0

Spinodoid structures enhance additive manufacturing by offering customizable, non-periodic designs with tunable anisotropic properties, improving material resilience and functional grading. This operator samples a spinodoid using the given parameters on a grid specified by GenerateSamplePoints, creating a spinodoid block.

Spinodoids are created via computing a Gaussian random field. The parameters of this operator adjust the sampling using to build the field. For deterministic results set seedto a specific value.

Lattices are formed by infinitely repeating unit cells in all directions. This operator samples surface lattices on a grid specified by GenerateSamplePoints, creating a lattice block that matches the size of the aforementioned operator. See a list of predefined surface lattices here.

Two powerful sets of parameters for lattices are scale_grading_* and section_grading_*. Scale and Section Grading are techniques used to vary the properties of a lattice structure across its volume:

• Scale Grading varies the unit cell scale of the lattice across the structure.
• Section Grading varies the cross-sectional properties of lattice beams.

These grading techniques enable the creation of lattice structures with varying properties, which can optimize performance, weight distribution, or other design objectives.

‣

Parameters

Parameter	Type	Description
lattice_type	String	Type of surface lattice. Defaults to "Gyroid" . Other options are listed here.
scale	Vec3f	Unit cell scale. Defaults to [1.0, 1.0, 1.0].
scale_grading_range	Vec2f	Distances of ScaleGrading scalar field to grade between. Defaults to zero vector.
scale_grading_scale	Vec2f	Scaling to apply to upper/lower grading limits. Defaults to zero vector.
threshold	Float	Value of the zero level set. Defaults to 0.
threshold_grading_range	Vec2f	Distances of ThresholdGrading scalar field to grade between. Defaults to zero vector.
threshold_grading_scale	Vec2f	Offset to apply to upper/lower grading limits. Defaults to zero vector.
xform	Mat4f	Affine transformation matrix. Defaults to identity matrix.

Lattice Types

C_Y

C_Y

CD

CD

CI2Y

CI2Y

CP

CP

CPM_Y

CPM_Y

CS

CS

D

D

F

F

FRD

FRD

Gyroid

Gyroid

I2Y

I2Y

IWP

IWP

P

P

PM_Y

PM_Y

S

S

Schwarz

Schwarz

SchwarzD

SchwarzD

SchwarzN

SchwarzN

SchwarzPW

SchwarzPW

SchwarzW

SchwarzW

SD1

SD1

W

W

Y

Y

Threshold

-1.0

-1.0

-0.5

-0.5

0.0

0.0

0.5

0.5

1.0

1.0

Scale

0.2

0.2

0.65

0.65

1.1

1.1

1.55

1.55

2.0

2.0

from metafold.func import GenerateSamplePoints, SampleSurfaceLattice


source = GenerateSamplePoints(
    {
        "offset": [10.0, 10.0, 10.0],
        "size": [20.0, 20.0, 20.0],
        "resolution": [128, 128, 128], 
    }
)

schwarz_volume = SampleSurfaceLattice(
    source,
    {
        "lattice_type": "Schwarz",
        "scale": [5, 5, 5]
    }
)

Given a volume of whether this operator samples that volume at specific points. This is very useful when combined with the LoadVolume operator. LoadVolume connects a volume asset to the backend but does not make it usable as is. To bring the volume into the Metafold computation space it must be sampled on the grid of points you are using for your project (see GenerateSamplePoints).

This operator can be used to sample 1D, 2D, and 3D dimensional arrays from LoadVolume .

Constructive Solid Geometry (CSG) operations are powerful tools in 3D modeling and computer-aided design. They allow for complex shapes to be created by combining simpler primitive shapes using boolean operations. The three main types of CSG operations are:

• "Union": Combines two shapes into a single object
• "Intersect": Creates a new shape from the overlapping portions of two objects
• "Subtract": Removes one shape from another

The power and usefulness of CSG operations lie in their ability to:

• Create complex geometries quickly and efficiently
• Simplify the design process for intricate parts

‣

Parameters

Name	Type	Description
operation	String	Type of CSG operation to apply. Defaults to "Union". Other operations: "Intersect", "Subtract" , "Union" When using "Subtract", input A is subtracted from input B.
smoothing	Float	Width of smooth CSG function by. Defaults to 0.0.

Operation

Union

Union

Subtract

Subtract

Intersect

Intersect

This operator creates a shell of a given thickness around the center of a level set given. The location of the level set is controlled by the offset parameter.

There are many creative and powerful ways to employ the Shell operator within the Metafold environment. The most common use is to make volumes hollow.

‣

Parameters

Parameter	Type	Description
offset	Float	Value at which the shell is centered.
thickness	Float	Thickness of the shell.

Thickness

0.05

0.05

0.212

0.212

0.375

0.375

0.537

0.537

0.7

0.7

Offset

0.1

0.1

0.0

0.0

-0.1

-0.1

from metafold.func import GenerateSamplePoints, BoxPrimitive, Shell
import numpy as np


source = GenerateSamplePoints(
    {
        "offset": np.full(3, -100.0)
        "size": np.full(3, 200)
        "resolution": np.full(3, 512) 
    }
)

shelled_box = Shell(
    BoxPrimitive(source, {"size": [50, 50, 50]}),
    {"thickness": 2.0}
)

Metafold shapes are implicitly defined on a grid of points, such that their surface is the 0-level set of the implicit function. The LinearFilter allows you to combine two fields from different shapes to distort their 0-level set in a controlled manner by addition and scalar multiplication. The common use case is for mapping a texture to a surface. See Mapping Textures to Shapes here for a step by step guide.

This operator computes an exact signed distance field from a given pseudo distance field. We recommend applying this filter to shapes prior to CSG operations to ensure accurate booleans. It is also typically appended to the end of shape functions so that we can be sure the shape function is generating an exact SDF. For more details, see Redistancing: What is it and why is it important?

Within the Metafold backend shapes live as implicit-fields, that are pseudo signed distance fields. Their surfaces are defined via their 0-level set. Some operators like SampleBox and SampleTriangleMesh provide the true signed distances to the object at the time of evaluation. But once they are combined with other operators this guarantee no longer holds. In order to ensure we are working with true signed distance fields only, this operator should be appended to the end of all graphs that are evaluated. See <> for more details.

To export a graph, this operator must be appended to the end. It compresses the graph's final output by remapping all sample values from the underlying implicit scalar field to the range [-1, 1]. Sample values with an absolute value exceeding the specified width are clamped to -1 or 1, depending on whether they are inside or outside the volume. The remapped values are then packed, with each float being represented as a single byte. Export functions, such as export_triangle_mesh(), require binary files in this format."