SurfaceOperations
Provides tools for creating, editing, and analyzing 3D surface objects. Supports import/export, primitive and projected-text generation, mesh repair, transformation, boolean operations, remeshing, and conversion between surface and volume representations.
Import
import ScriptingApi as api
# Access via Application
app = api.Application()
ops = app.get_surface_operations()
Methods
Properties
get_render_properties_operations
Returns an api.SurfaceRenderPropertiesOperations object.
Signature:
get_render_properties_operations() -> SurfaceRenderPropertiesOperations
Returns: SurfaceRenderPropertiesOperations — The api.SurfaceRenderPropertiesOperations object.
get_basic_surface_mesh_info
Retrieves basic mesh information for a specified surface.
Signature:
get_basic_surface_mesh_info(surfaceName: str) -> BasicSurfaceMeshInfo
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface to retrieve information for. |
Returns: BasicSurfaceMeshInfo — The api.BasicSurfaceMeshInfo object containing the surface mesh information.
get_geometry_data
Returns the surface geometry as vertices, triangle cells, and optional RGB color arrays. Triangle cells are returned as vertex index triplets. If the surface contains non-triangle faces, they are converted to triangles before the data is returned.
Signature:
get_geometry_data(surfaceName: str) -> SurfaceGeometryData
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface to read. |
Returns: SurfaceGeometryData — The api.SurfaceGeometryData object containing the mesh geometry and any available vertex or cell colors.
set_geometry_data
Replaces the surface geometry using vertices, triangle cells, and optional RGB color arrays. The input must contain at least one triangle cell. Triangle indices are validated before any change is applied. Color arrays are optional. When provided, vertex colors must match the vertex count and cell colors must match the triangle count.
Signature:
set_geometry_data(surfaceName: str, geometryData: SurfaceGeometryData) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface to update. |
geometryData | SurfaceGeometryData | Surface geometry to apply. Create using api.SurfaceGeometryData(). |
point_matching_registration
Performs point-based registration (ICP) to align source surfaces to a target.
Signature:
point_matching_registration(movableSurfaceNames: list, fixedObjectName: str, targetObjectType: RegistrationTargetObject, registrationMode: RegistrationMode = api.RegistrationMode.RigidBody, startByMatchingCentroids: bool = True, maximumLandmarks: int = 1000) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
movableSurfaceNames | list | List of source/movable surface names to register. |
fixedObjectName | str | Name of the fixed target surface or mask. |
targetObjectType | RegistrationTargetObject | Type of target object. Use api.RegistrationTargetObject.Surface or api.RegistrationTargetObject.Mask. |
registrationMode | RegistrationMode | Registration mode. Use api.RegistrationMode.RigidBody, api.RegistrationMode.Similarity, or api.RegistrationMode.Affine. |
startByMatchingCentroids | bool | If true, starts by aligning centroids before registration. |
maximumLandmarks | int | Maximum number of landmarks to use for registration. |
Returns: list — A list of api.GlobalRegistrationResultRow() with RMSE values for each surface pair. Example usage: surface_operations = app.get_surface_operations() registration_result_rows = surface_operations.point_matching_registration(['movable'], 'fixed', api.RegistrationTargetObject.Surface, api.RegistrationMode.RigidBody) for row in registration_result_rows: registration_result_row : api.GlobalRegistrationResultRow = row print(registration_result_row.movable_surface) print(registration_result_row.fixed_target) print(registration_result_row.rmse_millimeters)
feature_matching_registration
Performs feature-based registration using curvature matching to align surfaces.
Signature:
feature_matching_registration(movableSurfaceNames: list, fixedObjectName: str, targetObjectType: RegistrationTargetObject, globalIterations: int = 3, overlapRadius: float = 10.0, curvatureThreshold: float = 0.001) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
movableSurfaceNames | list | List of source/movable surface names to register. |
fixedObjectName | str | Name of the fixed target surface or mask. |
targetObjectType | RegistrationTargetObject | Type of target object. Use api.RegistrationTargetObject.Surface or api.RegistrationTargetObject.Mask. |
globalIterations | int | Number of global registration iterations. |
overlapRadius | float | Radius around a point for optimization (must exceed minimum patch distance). |
curvatureThreshold | float | Curvature threshold value (lower = higher accuracy). |
Returns: list — A list of api.GlobalRegistrationResultRow() with RMSE values for each surface pair. Example usage: surface_operations = app.get_surface_operations() registration_result_rows = surface_operations.feature_matching_registration(['movable'], 'fixed', api.RegistrationTargetObject.Surface) for row in registration_result_rows: registration_result_row : api.GlobalRegistrationResultRow = row print(registration_result_row.movable_surface) print(registration_result_row.fixed_target) print(registration_result_row.rmse_millimeters)
point_plus_feature_matching_registration
Performs combined point and feature-based registration for improved alignment.
Signature:
point_plus_feature_matching_registration(movableSurfaceNames: list, fixedObjectName: str, targetObjectType: RegistrationTargetObject, registrationMode: RegistrationMode = api.RegistrationMode.RigidBody, startByMatchingCentroids: bool = True, maximumLandmarks: int = 1000, globalIterations: int = 3, overlapRadius: float = 10.0, curvatureThreshold: float = 0.001) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
movableSurfaceNames | list | List of source/movable surface names to register. |
fixedObjectName | str | Name of the fixed target surface or mask. |
targetObjectType | RegistrationTargetObject | Type of target object. Use api.RegistrationTargetObject.Surface or api.RegistrationTargetObject.Mask. |
registrationMode | RegistrationMode | Registration mode. Use api.RegistrationMode.RigidBody, api.RegistrationMode.Similarity, or api.RegistrationMode.Affine. |
startByMatchingCentroids | bool | If true, starts by aligning centroids before registration. |
maximumLandmarks | int | Maximum number of landmarks to use for point matching. |
globalIterations | int | Number of global feature matching iterations. |
overlapRadius | float | Radius around a point for feature optimization. |
curvatureThreshold | float | Curvature threshold for feature matching. |
Returns: list — A list of api.GlobalRegistrationResultRow() with RMSE values for each surface pair. Usage example: surface_operations = app.get_surface_operations() registration_result_rows = surface_operations.point_plus_feature_matching_registration(['movable'], 'fixed', api.RegistrationTargetObject.Surface) for row in registration_result_rows: registration_result_row : api.GlobalRegistrationResultRow = row print(registration_result_row.movable_surface) print(registration_result_row.fixed_target) print(registration_result_row.rmse_millimeters)
poisson_remesh_screened
Remeshes surfaces or point clouds by reconstructing a new watertight triangle mesh using screened Poisson surface reconstruction. The screened method incorporates the input points as soft positional constraints, which fits the reconstructed surface faithfully to the input data and preserves details and the overall shape while keeping the surface smooth. Recommended for most applications.
Signature:
poisson_remesh_screened(surfaceNames: list, params: SurfaceScreenedPoissonRemeshParams = SurfaceScreenedPoissonRemeshParams()) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to remesh. |
params | SurfaceScreenedPoissonRemeshParams | Screened Poisson reconstruction parameters. Create using params = api.SurfaceScreenedPoissonRemeshParams(). |
poisson_remesh_unscreened
Remeshes surfaces or point clouds by reconstructing a new watertight triangle mesh using unscreened Poisson surface reconstruction. The unscreened method produces very smooth surfaces that robustly approximate noisy data, but it may over-smooth and shrink detailed regions compared to the screened method.
Signature:
poisson_remesh_unscreened(surfaceNames: list, params: SurfaceUnscreenedPoissonRemeshParams = SurfaceUnscreenedPoissonRemeshParams()) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to remesh. |
params | SurfaceUnscreenedPoissonRemeshParams | Unscreened Poisson reconstruction parameters. Create using params = api.SurfaceUnscreenedPoissonRemeshParams(). |
set_volume_mesh_parameters
Sets volume meshing parameters for a surface. Configures meshing quality and algorithm-specific options that will be used when converting the surface to a volume mesh. These parameters are stored in the surface object and persist until changed.
Signature:
set_volume_mesh_parameters(surfaceName: str, params: VolumeMeshParams) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | Name of the surface to configure. |
params | VolumeMeshParams | Volume meshing parameters including method, resolution, and algorithm-specific settings. Create using params = api.VolumeMeshParams(). |
get_volume_mesh_parameters
Gets volume meshing parameters from a surface. Retrieves the currently configured meshing parameters stored in the surface object.
Signature:
get_volume_mesh_parameters(surfaceName: str) -> VolumeMeshParams
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | Name of the surface to query. |
Returns: VolumeMeshParams — Volume meshing parameters currently stored in the surface object.
File System
import_surfaces_from_disk
Imports surface files from disk.
Signature:
import_surfaces_from_disk(fileNames: list) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
fileNames | list | A list containing the full paths of the surface files to import. Supported file extensions are: stl, ply, obj, wrl, vrml, gltf, glb, amf, step, stp, iges, igs, vtp, and xyz. Only mesh data is imported; as a result, some file formats are only partially supported. |
Returns: list — A list of strings containing the names of the imported surface objects. An empty list is returned if no files were imported successfully.
import_surface_from_disk
Imports a surface file from disk.
Signature:
import_surface_from_disk(fileName: str) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
fileName | str | The full path of the surface file to import. Supported file extensions are: stl, ply, obj, wrl, vrml, gltf, glb, amf, step, stp, iges, igs, vtp, and xyz. Only mesh data is imported; as a result, some file formats are only partially supported. |
Returns: str — Returns the name of the imported surface object if successful; otherwise, returns an empty string.
export_surfaces_to_disk
Exports surfaces specified by their names to disk files in a given directory with a specified file extension.
Signature:
export_surfaces_to_disk(surfaceNames: list, directoryPath: str, fileExtension: str = "stl", isASCII: bool = False) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | A list containing the names of the surfaces to export. |
directoryPath | str | The path to the directory where the surface files will be saved. |
fileExtension | str | The file extension to use for the exported surface files. Supported file extensions are: stl, ply, obj, wrl, vrml, u3d, 3mf, amf, gltf, step, stp, iges, igs, vtp, vtk, byu, x3d, iv, and xyz. Only mesh data is exported; therefore, some file formats are only partially supported. |
isASCII | bool | If true, exports the files in ASCII format; otherwise, exports in binary format. Defaults to false. isASCII is only applicable for stl and ply file formats. |
Returns: bool — Returns true if all surfaces were successfully exported; otherwise, returns false.
export_surface_to_disk
Exports a surface to a file on disk.
Signature:
export_surface_to_disk(surfaceName: str, fileName: str, isASCII: bool = False) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface to export. |
fileName | str | The path and name of the file to write the surface data to. Supported file extensions are: stl, ply, obj, wrl, vrml, u3d, 3mf, amf, gltf, step, stp, iges, igs, vtp, vtk, byu, x3d, iv, and xyz. Only mesh data is exported; therefore, some file formats are only partially supported. File name should include the file extension, e.g., 'C:/temp/surface.stl'. |
isASCII | bool | If true, exports the surface in ASCII format; otherwise, exports in binary format. Defaults to false. isASCII is only applicable for stl and ply file formats. |
Returns: bool — True if the export was successful; false otherwise.
Creation
create_box
Creates a box primitive surface.
Signature:
create_box(name: str, width: float, height: float, depth: float, center: list = [0, 0, 0], resolution: int = 10) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
width | float | The width of the box. |
height | float | The height of the box. |
depth | float | The depth of the box. |
center | list | The center position of the box [x, y, z]. |
resolution | int | The resolution for subdivisions (default: 10). |
Returns: str — The name of the created surface.
create_cube
Creates a cube primitive surface.
Signature:
create_cube(name: str, edgeLength: float, center: list = [0, 0, 0], resolution: int = 10) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name of the cube. |
edgeLength | float | The length of each edge of the cube. |
center | list | The center position of the cube [x, y, z]. |
resolution | int | The resolution for subdivisions (default: 10). |
Returns: str — A string representing the created cube, such as its identifier or a description.
create_sphere
Creates a sphere primitive surface.
Signature:
create_sphere(name: str, radius: float, center: list = [0, 0, 0], rings: int = 36, sectors: int = 36) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
radius | float | The radius of the sphere. |
center | list | The center position of the sphere [x, y, z]. |
rings | int | Number of rings (latitude resolution, default: 36). |
sectors | int | Number of sectors (longitude resolution, default: 36). |
Returns: str — The name of the created surface.
create_capped_sphere
Creates a capped sphere primitive surface.
Signature:
create_capped_sphere(name: str, radius: float, cutAngleDeg: float, center: list = [0, 0, 0], rings: int = 36, sectors: int = 36) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
radius | float | The radius of the sphere. |
cutAngleDeg | float | The cut angle in degrees (0-180) to define the cap. |
center | list | The center position of the sphere [x, y, z]. |
rings | int | Number of rings (latitude resolution, default: 36). |
sectors | int | Number of sectors (longitude resolution, default: 36). |
Returns: str — The name of the created surface.
create_ellipsoid
Creates an ellipsoid primitive surface.
Signature:
create_ellipsoid(name: str, radiusX: float, radiusY: float, radiusZ: float, center: list = [0, 0, 0], rings: int = 36, sectors: int = 36) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
radiusX | float | Radius along X-axis. |
radiusY | float | Radius along Y-axis. |
radiusZ | float | Radius along Z-axis. |
center | list | The center position of the ellipsoid [x, y, z]. |
rings | int | Number of rings (default: 36). |
sectors | int | Number of sectors (default: 36). |
Returns: str — The name of the created surface.
create_cylinder
Creates a cylinder primitive surface.
Signature:
create_cylinder(name: str, radius: float, height: float, center: list = [0, 0, 0], resolution: int = 36, capping: bool = True, direction: int = 2) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
radius | float | The radius of the cylinder. |
height | float | The height of the cylinder. |
center | list | The center position of the cylinder [x, y, z]. |
resolution | int | The circumferential resolution (default: 36). |
capping | bool | Whether to cap the cylinder ends (default: true). |
direction | int | The direction axis (0=X, 1=Y, 2=Z, default: 2). |
Returns: str — The name of the created surface.
create_capsule
Creates a capsule primitive surface.
Signature:
create_capsule(name: str, radius: float, height: float, center: list = [0, 0, 0], resolution: int = 36, direction: int = 2) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
radius | float | The radius of the capsule. |
height | float | The height of the cylindrical part. |
center | list | The center position of the capsule [x, y, z]. |
resolution | int | The circumferential resolution (default: 36). |
direction | int | The direction axis (0=X, 1=Y, 2=Z, default: 2). |
Returns: str — The name of the created surface.
create_tube
Creates a tube primitive surface.
Signature:
create_tube(name: str, outerRadius: float, thickness: float, height: float, center: list = [0, 0, 0], resolution: int = 36, direction: int = 2) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
outerRadius | float | Outer radius of the tube. |
thickness | float | Wall thickness of the tube. |
height | float | The height of the tube. |
center | list | The center position of the tube [x, y, z]. |
resolution | int | The circumferential resolution (default: 36). |
direction | int | The direction axis (0=X, 1=Y, 2=Z, default: 2). |
Returns: str — The name of the created surface.
create_cone
Creates a cone primitive surface.
Signature:
create_cone(name: str, radius: float, height: float, center: list = [0, 0, 0], resolution: int = 36, capping: bool = True, direction: int = 2) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
radius | float | Base radius of the cone. |
height | float | The height of the cone. |
center | list | The center position of the cone [x, y, z]. |
resolution | int | The circumferential resolution (default: 36). |
capping | bool | Whether to cap the cone base (default: true). |
direction | int | The direction axis (0=X, 1=Y, 2=Z, default: 2). |
Returns: str — The name of the created surface.
create_arrow
Creates an arrow primitive surface.
Signature:
create_arrow(name: str, totalLength: float, shaftRadius: float, tipLength: float, tipRadius: float, center: list = [0, 0, 0], resolution: int = 32, direction: int = 2) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
totalLength | float | Total length of the arrow. |
shaftRadius | float | Radius of the arrow shaft. |
tipLength | float | Length of the arrow tip. |
tipRadius | float | Radius of the arrow tip. |
center | list | The center position of the arrow [x, y, z]. |
resolution | int | The circumferential resolution (default: 32). |
direction | int | The direction axis (0=X, 1=Y, 2=Z, default: 2). |
Returns: str — The name of the created surface.
create_torus
Creates a torus primitive surface.
Signature:
create_torus(name: str, innerRadius: float, outerRadius: float, center: list = [0, 0, 0], resolution: int = 36, direction: int = 2) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
innerRadius | float | Inner radius (ring radius). |
outerRadius | float | Outer radius (total radius). |
center | list | The center position of the torus [x, y, z]. |
resolution | int | The resolution for both U and V directions (default: 36). |
direction | int | The direction axis (0=X, 1=Y, 2=Z, default: 2). |
Returns: str — The name of the created surface.
create_platonic_solid
Creates a platonic solid primitive surface.
Signature:
create_platonic_solid(name: str, solidType: PlatonicSolidType, radius: float, center: list = [0, 0, 0]) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
solidType | PlatonicSolidType | Type of platonic solid. Use api.PlatonicSolidType.Tetrahedron, api.PlatonicSolidType.Octahedron, api.PlatonicSolidType.Icosahedron, or api.PlatonicSolidType.Dodecahedron. |
radius | float | The radius of the solid. |
center | list | The center position of the solid [x, y, z]. |
Returns: str — The name of the created surface.
create_disk
Creates a disk primitive surface.
Signature:
create_disk(name: str, innerRadius: float, outerRadius: float, center: list = [0, 0, 0], radialResolution: int = 18, circumferentialResolution: int = 36, direction: int = 2) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
innerRadius | float | Inner radius of the disk. |
outerRadius | float | Outer radius of the disk. |
center | list | The center position of the disk [x, y, z]. |
radialResolution | int | The radial resolution (default: 18). |
circumferentialResolution | int | The circumferential resolution (default: 36). |
direction | int | The direction axis (0=X, 1=Y, 2=Z, default: 2). |
Returns: str — The name of the created surface.
create_plane
Creates a plane primitive surface.
Signature:
create_plane(name: str, width: float, height: float, center: list = [0, 0, 0], resolution: int = 1, direction: int = 2) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name for the created surface (if empty, auto-generated). |
width | float | The width of the plane. |
height | float | The height of the plane. |
center | list | The center position of the plane [x, y, z]. |
resolution | int | The resolution for subdivisions (default: 1). |
direction | int | The direction axis (0=X, 1=Y, 2=Z, default: 2). |
Returns: str — The name of the created surface.
create_projected_text
Creates text projected onto a target surface as a separate surface object. The target surface is not modified and no Boolean operation is performed. The text is centered at the requested world-space position before projection rays are cast parallel to params.surfaceNormal. The returned surface includes the requested overlap so it can be used independently or combined later by the caller.
Signature:
create_projected_text(targetSurfaceName: str, text: str, params: ProjectedTextParams = ProjectedTextParams(), resultSurfaceName: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
targetSurfaceName | str | Name of the surface onto which the text is projected. |
text | str | UTF-8 text to convert into surface geometry. |
params | ProjectedTextParams | Font, placement, scale, projection, and extrusion settings. Create using params = api.ProjectedTextParams(). |
resultSurfaceName | str | Name for the created surface. An empty name selects a descriptive default. |
Returns: str — The actual name of the created surface.
Modification
rotate
Rotates surfaces around a specified axis and center point.
Signature:
rotate(surfaceNames: list, angleDegrees: float, axis: list, center: list = [0.0, 0.0, 0.0], aroundObjectCentroid: bool = True) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to rotate. |
angleDegrees | float | Rotation angle in degrees. |
axis | list | Rotation axis [x, y, z]. |
center | list | Rotation center point [x, y, z] (ignored if aroundObjectCentroid=True). |
aroundObjectCentroid | bool | If true, rotates around object's bounding box centroid. |
translate
Translates surfaces by a specified vector.
Signature:
translate(surfaceNames: list, translation: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to translate. |
translation | list | Translation vector [x, y, z] in model units. |
scale
Scales surfaces by specified factors along each axis.
Signature:
scale(surfaceNames: list, scaleFactors: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to scale. |
scaleFactors | list | Scale factors [x, y, z]. |
transform
Applies a transformation matrix to the specified surfaces.
Signature:
transform(surfaceNames: list, matrix: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to transform. |
matrix | list | Transformation matrix [16 elements]. |
clip_with_primitive
Clips surfaces with a primitive object used as the region of interest. The primitive defines an analytic region, which is the same region the Clip tool uses: a plane primitive clips with its plane, a sphere primitive with its sphere, a cylinder primitive with an infinite cylinder along its axis (the cylinder caps are ignored), and a cube or cuboid primitive with its six faces. Point, line, circle, ellipsoid, capsule, tube, cone, arrow and spline primitives have no analytic region; use cutWithPrimitives() for those. Surfaces that the region leaves without any geometry are reported and left unchanged. The options supported by each region are the same as those offered by the Clip tool. Plane primitives support closed and invert. They also support retainClippedRegion when closed is false. Cube and cuboid primitives support closed. They support invert and retainClippedRegion only when closed is false. Sphere and cylinder primitives support invert, but do not support closed or retainClippedRegion. Passing an option that a primitive does not support raises an exception rather than being ignored silently.
Signature:
clip_with_primitive(surfaceNames: list, primitiveName: str, closed: bool = False, invert: bool = False, retainClippedRegion: bool = False) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | A list containing the names of the surfaces to clip. |
primitiveName | str | The name of the primitive object that defines the region of interest. |
closed | bool | If true, caps the clipped mesh so that the result stays a closed surface. Requires surfaces that are already closed and manifold. Surfaces that are not closed and manifold are reported and left unchanged. |
invert | bool | If true, keeps the region on the other side of the primitive. Closed cube and cuboid clipping always keeps what is inside the box, so it has no side left to invert. |
retainClippedRegion | bool | If true, the removed region is added to the scene as a new surface object. |
cut_with_primitives
Cuts surfaces with one or more primitive objects. The mesh of every primitive is subtracted from every input surface, which works with any primitive type. Unlike clipWithPrimitive(), the cut follows the mesh of the primitive rather than an analytic region, so a cylinder primitive cuts as a capped cylinder.
Signature:
cut_with_primitives(surfaceNames: list, primitiveNames: list, retainCutRegion: bool = False) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | A list containing the names of the surfaces to cut. |
primitiveNames | list | A list containing the names of the primitive objects to cut with. |
retainCutRegion | bool | If true, the removed region is added to the scene as a new surface object. |
hollow
Creates a hollow version of surfaces with specified wall thickness.
Signature:
hollow(surfaceNames: list, method: SurfaceHollowMethod, direction: SurfaceHollowDirection, thickness: float, resolution: SurfaceHollowResolution = api.SurfaceHollowResolution.Medium, createNewSurface: bool = False) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to hollow. |
method | SurfaceHollowMethod | Hollowing method. Use api.SurfaceHollowMethod.Fast (normal-based extrusion) or api.SurfaceHollowMethod.Robust (voxel-based). |
direction | SurfaceHollowDirection | Hollow direction. Use api.SurfaceHollowDirection.Inward or api.SurfaceHollowDirection.Outward. |
thickness | float | Wall thickness for the hollowed surfaces. |
resolution | SurfaceHollowResolution | Resolution preset for Robust method. Use api.SurfaceHollowResolution.Low, api.SurfaceHollowResolution.Medium, api.SurfaceHollowResolution.High, or api.SurfaceHollowResolution.Maximum. |
createNewSurface | bool | Create new surfaces instead of modifying inputs. |
Returns: list — A list of names for the hollowed surfaces in case of createNewSurface=True; otherwise, returns an empty list.
smooth_laplacian
Applies Laplacian smoothing to the specified surfaces. This method iteratively moves each vertex toward the average position of its neighbors, resulting in a more uniform and flatter mesh. The process may cause the mesh to shrink slightly. You can control the number of iterations, smoothing strength, and whether to preserve sharp features.
Signature:
smooth_laplacian(surfaceNames: list, iterations: int = 3, smoothFactor: float = 0.6, featureEdges: bool = True, featureAngle: float = 85) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to smooth. |
iterations | int | Number of times the smoothing algorithm should run (minimum: 2; default: 3). Higher values increase smoothing. |
smoothFactor | float | Smoothing strength (relaxation factor). Higher values produce more smoothing (range: 0.001–1.0; default: 0.6). |
featureEdges | bool | If true, sharp interior edges are identified and preserved based on the feature angle. If false, all features are smoothed. |
featureAngle | float | Angle threshold (in degrees, range: 0–180; default: 85) for identifying sharp edges to preserve. Smaller values preserve more features; higher values result in more smoothing. |
smooth_smart
Applies Smart smoothing to the specified surfaces. This method reduces noise and smooths the mesh while better preserving the overall shape, with less shrinkage or distortion compared to basic smoothing. You can control the number of iterations, smoothing strength, and whether to preserve sharp features.
Signature:
smooth_smart(surfaceNames: list, iterations: int = 20, smoothFactor: float = 0.01, featureEdges: bool = True, featureAngle: float = 85) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to smooth. |
iterations | int | Number of times the smoothing algorithm should run (minimum: 2; default: 20). Higher values increase smoothing. |
smoothFactor | float | Smoothing strength (pass band value). Lower values produce more smoothing (range: 0.0001–1.0; default: 0.01). |
featureEdges | bool | If true, sharp interior edges are identified and preserved based on the feature angle. If false, all features are smoothed. |
featureAngle | float | Angle threshold (in degrees, range: 0–180; default: 85) for identifying sharp edges to preserve. Smaller values preserve more features; higher values result in more smoothing. |
subdivide
Subdivides surfaces to increase triangle count.
Signature:
subdivide(surfaceNames: list, method: SurfaceSubdivisionMethod, subdivisions: int = 1, maxEdgeLength: float = 1.0) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to subdivide. |
method | SurfaceSubdivisionMethod | Subdivision method. Use api.SurfaceSubdivisionMethod.Linear, api.SurfaceSubdivisionMethod.Loop, api.SurfaceSubdivisionMethod.Butterfly, or api.SurfaceSubdivisionMethod.Adaptive. |
subdivisions | int | Number of subdivision iterations (ignored for Adaptive method). |
maxEdgeLength | float | Maximum edge length for Adaptive subdivision (ignored for other methods). |
General
reorient
Applies a six-parameter rigid reorientation to surfaces.
Signature:
reorient(surfaceNames: list, translation: list, rotationAnglesDegrees: list, center: list = [0.0, 0.0, 0.0], aroundObjectCentroid: bool = True) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to transform. |
translation | list | Translation vector [x, y, z] in model units. |
rotationAnglesDegrees | list | XYZ Euler rotation angles in degrees. |
center | list | Rotation center [x, y, z] (ignored if aroundObjectCentroid=True). |
aroundObjectCentroid | bool | If true, rotates around object's bounding box centroid. |
mirror
Mirrors surfaces across specified axes.
Signature:
mirror(surfaceNames: list, mirrorX: bool = False, mirrorY: bool = False, mirrorZ: bool = False) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to mirror. |
mirrorX | bool | Mirror across X axis. |
mirrorY | bool | Mirror across Y axis. |
mirrorZ | bool | Mirror across Z axis. |
move_to_active_volume_center
Moves surfaces to the center of the active volume image.
Signature:
move_to_active_volume_center(surfaceNames: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to move. |
diagnose_surface
Performs diagnostic checks on a surface and returns the results.
Signature:
diagnose_surface(surfaceName: str, checks: SurfaceDiagnosticsChecks = SurfaceDiagnosticsChecks()) -> SurfaceDiagnosticsResult
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface to diagnose. |
checks | SurfaceDiagnosticsChecks | The set of diagnostic checks to perform on the surface. Create using checks = api.SurfaceDiagnosticsChecks(). |
Returns: SurfaceDiagnosticsResult — A SurfaceDiagnosticsResult object containing the results of the diagnostic checks.
fix_surface
Applies specified fix operations to a surface identified by name.
Signature:
fix_surface(surfaceName: str, checks: SurfaceDiagnosticsChecks = SurfaceDiagnosticsChecks()) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface to be fixed. |
checks | SurfaceDiagnosticsChecks | The checks indicating which fixes to apply. Create using checks = api.SurfaceDiagnosticsChecks(). |
merge
Merges multiple surfaces into a single surface.
Signature:
merge(surfaceNames: list, targetSurfaceName: str, mergePoints: bool = True, removeInputSurfaces: bool = False, createNewSurface: bool = True) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to merge (must have at least 2 surfaces). |
targetSurfaceName | str | Name of an existing surface to receive the merged result when createNewSurface=False. Ignored when createNewSurface=True (the new surface is auto-named). |
mergePoints | bool | Merge duplicate (coincident) points after combining surfaces. Defaults to true. |
removeInputSurfaces | bool | Remove input surfaces after merging. Defaults to false. |
createNewSurface | bool | Create a new surface instead of overwriting targetSurfaceName. Defaults to true. |
Returns: str — The name of the merged surface when createNewSurface=True; otherwise, returns an empty string.
split
Separates a surface into multiple surfaces based on disconnected regions.
Signature:
split(surfaceName: str, numLargestShells: int = 0, removeInputSurface: bool = False) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | Name of the surface to separate. |
numLargestShells | int | Number of largest shells to extract (0 = all shells). |
removeInputSurface | bool | Remove the input surface after separation. |
Returns: list — A list of names for the newly created surfaces.
filter_shells
Filters shells from a surface based on specified criteria.
Signature:
filter_shells(surfaceName: str, method: SurfaceFilterShellsMethod, params: SurfaceFilterShellsParams) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | Name of the surface to filter. |
method | SurfaceFilterShellsMethod | Filter method. Use api.SurfaceFilterShellsMethod.LargestShells, etc. |
params | SurfaceFilterShellsParams | Filter parameters including thresholds and retention settings. Create using params = api.SurfaceFilterShellsParams(). |
boolean_operation
Performs boolean operations between surfaces. Input B surfaces are processed in list order. During a union, an Input B surface that has no contact with the accumulated result cannot be geometrically unioned. It is appended to the result as a separate disconnected shell at that processing step, and a warning identifies every surface handled this way. Later inputs are processed against the combined result and may intersect an appended shell. Intersection and difference operations report no contact as a failure and do not produce a result.
Signature:
boolean_operation(surfaceNameInputA: str, surfaceNamesInputB: list, surfaceNameResult: str, operation: SurfaceBooleanOperation, createNewSurface: bool = True) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNameInputA | str | Name of the first input surface. |
surfaceNamesInputB | list | List of names for the second input surfaces. |
surfaceNameResult | str | Name for the resulting surface (only used if createNewSurface=False). |
operation | SurfaceBooleanOperation | Boolean operation type. Use api.SurfaceBooleanOperation.Union, api.SurfaceBooleanOperation.Intersection, or api.SurfaceBooleanOperation.Difference. |
createNewSurface | bool | Create a new surface instead of modifying input1. |
Returns: str — The name of the resulting surface in case of createNewSurface=True; otherwise, returns an empty string.
voxel_boolean_operation
Performs voxel-based boolean operations between surfaces.
Signature:
voxel_boolean_operation(surfaceNameInputA: str, surfaceNamesInputB: list, surfaceNameResult: str, operation: SurfaceBooleanOperation, voxelizationMethod: SurfaceVoxelizeMethod = api.SurfaceVoxelizeMethod.Fast, voxelSpacing: list = [1, 1, 1], smoothArtifacts: bool = True, createNewSurface: bool = True) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNameInputA | str | Name of the first input surface. |
surfaceNamesInputB | list | List of names for the second input surfaces. |
surfaceNameResult | str | Name for the resulting surface (only used if createNewSurface=False). |
operation | SurfaceBooleanOperation | Boolean operation type. Use api.SurfaceBooleanOperation.Union, api.SurfaceBooleanOperation.Intersection, or api.SurfaceBooleanOperation.Difference. |
voxelizationMethod | SurfaceVoxelizeMethod | Voxelization method. Use api.SurfaceVoxelizeMethod.Accurate or api.SurfaceVoxelizeMethod.Fast. |
voxelSpacing | list | Voxel spacing [x, y, z] for the operation (smaller values = higher quality). |
smoothArtifacts | bool | Smooth artifacts in the resulting mesh (only applies to Voxelize method). |
createNewSurface | bool | Create a new surface instead of modifying input1. |
Returns: str — The name of the resulting surface in case of createNewSurface=True; otherwise, returns an empty string.
fill_holes
Fills holes in the specified surface up to the given maximum hole size.
Signature:
fill_holes(surfaceName: str, maxHoleSize: float = -1.0, method: SurfaceHoleFillingMethod = api.SurfaceHoleFillingMethod.Angle) -> int
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface on which to perform hole filling. |
maxHoleSize | float | The maximum hole radius (in surface/model units) that will be filled. Holes larger than this are left open. A value of 0 or less fills all holes regardless of size. |
method | SurfaceHoleFillingMethod | The hole-filling method (api.SurfaceHoleFillingMethod.Angle, api.SurfaceHoleFillingMethod.Area, or api.SurfaceHoleFillingMethod.EarCut). The default is api.SurfaceHoleFillingMethod.Angle. |
Returns: int — The number of holes filled in the surface.
remesh
Remeshes surfaces to improve triangle quality and distribution.
Signature:
remesh(surfaceNames: list, method: SurfaceRemeshMethod = api.SurfaceRemeshMethod.Adaptive, quality: SurfaceRemeshQuality = api.SurfaceRemeshQuality.Medium, density: int = 100, preserveEdges: bool = True) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to remesh. |
method | SurfaceRemeshMethod | Remesh method. Use api.SurfaceRemeshMethod.Adaptive or api.SurfaceRemeshMethod.Regular. |
quality | SurfaceRemeshQuality | Quality preset. Use api.SurfaceRemeshQuality.Medium, api.SurfaceRemeshQuality.High, or api.SurfaceRemeshQuality.Maximum. |
density | int | Target density as percentage of original vertex count (11 - 100). |
preserveEdges | bool | If true, preserves the surface's open boundaries (holes) and its sharp feature edges (such as creases and ridges) so they are not smoothed away during remeshing. This may produce less uniformly shaped triangles in the areas immediately surrounding the preserved edges. |
voxel_remesh
Remeshes surfaces using voxel-based method.
Signature:
voxel_remesh(surfaceNames: list, voxelizationMethod: SurfaceVoxelizeMethod = api.SurfaceVoxelizeMethod.Fast, voxelSpacing: list = [1, 1, 1], smoothArtifacts: bool = True) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to remesh. |
voxelizationMethod | SurfaceVoxelizeMethod | Voxelization method. Use api.SurfaceVoxelizeMethod.Accurate or api.SurfaceVoxelizeMethod.Fast. |
voxelSpacing | list | Voxel spacing [x, y, z] for the operation (smaller values = higher quality). |
smoothArtifacts | bool | Smooth artifacts in the resulting mesh (only applies to Voxelize method). |
invert_triangles
Reverses the winding order of the given triangles of a surface, flipping the direction they face. Use this to correct individual triangles whose normals point the wrong way. Normals are recomputed afterwards. Triangle indices refer to the triangle order returned by get_geometry_data.
Signature:
invert_triangles(surfaceName: str, triangleIds: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface to modify. |
triangleIds | list | A list of triangle indices to invert. Indices outside the mesh are ignored. |
invert_all_triangles
Reverses the winding order of every triangle of the given surfaces, flipping the direction they face. Use this when a whole surface faces inwards. Normals are recomputed afterwards. To reverse only some triangles, use invert_triangles instead.
Signature:
invert_all_triangles(surfaceNames: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to invert. |
delete_shells
Removes the given shells of a surface and keeps the rest of it. A shell is one connected region of the mesh. Shells are numbered from 0 in the order the connectivity of the surface produces them, which is the number the Shells tab of the Diagnostics and Fixes tool keeps for each row, not the position of the row in the table. An index that matches no shell is ignored, and a list that names every shell leaves the surface unchanged.
Signature:
delete_shells(surfaceName: str, shellIds: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceName | str | The name of the surface to modify. |
shellIds | list | A list of shell indices to remove, counted from 0. |
reduce
Reduces (decimates) the number of triangles while preserving overall shape. Use this method for general-purpose surface simplification/decimation. You can reduce by percentage or by desired final triangle count. The final triangle count is approximate and may differ from the requested value depending on the mesh.
Signature:
reduce(surfaceNames: list, desiredPercentage: float = 50.0, useDesiredPercentage: bool = True, desiredTriangles: int = 3000) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to reduce. |
desiredPercentage | float | Percentage of triangles to remove (0.0-100.0) when useDesiredPercentage is true. |
useDesiredPercentage | bool | If true, uses desiredPercentage; otherwise uses desiredTriangles. |
desiredTriangles | int | Desired final triangle count when useDesiredPercentage is false. |
reduce_by_features
Reduces (decimates) triangles while prioritizing preservation of sharp features. Use featureAngle to control how aggressively sharp edges and corners are preserved during reduction. You can decimate by percentage or by desired final triangle count. Depending on geometry and feature constraints, actual reduction may be lower than requested.
Signature:
reduce_by_features(surfaceNames: list, featureAngle: float = 85.0, desiredPercentage: float = 50.0, useDesiredPercentage: bool = True, desiredTriangles: int = 3000) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to reduce. |
featureAngle | float | Feature angle in degrees used to preserve sharp features. |
desiredPercentage | float | Percentage of triangles to remove (0.0-100.0) when useDesiredPercentage is true. |
useDesiredPercentage | bool | If true, uses desiredPercentage; otherwise uses desiredTriangles. |
desiredTriangles | int | Desired final triangle count when useDesiredPercentage is false. |
reduce_by_nearby_points
Reduces mesh complexity (decimation) by joining nearby points. Points that are closer than nearbyPointDistance may be merged, which can reduce both vertex and triangle counts. In some cases, running this operation multiple times can produce additional decimation.
Signature:
reduce_by_nearby_points(surfaceNames: list, nearbyPointDistance: float = 1.0) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to reduce. |
nearbyPointDistance | float | Distance threshold used to join nearby points. |
project_to_plane
Projects surfaces onto a specified plane.
Signature:
project_to_plane(surfaceNames: list, planeOrigin: list, planeNormal: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to project. |
planeOrigin | list | Plane origin point [x, y, z]. |
planeNormal | list | Plane normal vector [x, y, z]. |
mirror_to_plane
Mirrors (reflects) surfaces across a specified plane. Each surface point P is reflected as P' = P - 2 * dot(P - O, N) * N, where O is the plane origin and N is the unit normal vector. After reflection, cell winding is reversed and normals are recomputed.
Signature:
mirror_to_plane(surfaceNames: list, planeOrigin: list, planeNormal: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to mirror. |
planeOrigin | list | Plane origin point [x, y, z]. |
planeNormal | list | Plane normal vector [x, y, z]. |
convert_to_mask
Converts surfaces to mask objects using voxelization. Voxelizes the selected surfaces and creates new mask objects. The active volume must be present before calling this function.
Signature:
convert_to_mask(surfaceNames: list, voxelizationMethod: SurfaceVoxelConversionMethod = api.SurfaceVoxelConversionMethod.Filled, smoothArtifacts: bool = True) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | A list containing the names of the surfaces to convert. |
voxelizationMethod | SurfaceVoxelConversionMethod | Voxelization method. Use api.SurfaceVoxelConversionMethod.Filled, api.SurfaceVoxelConversionMethod.ThickContour, api.SurfaceVoxelConversionMethod.ThinContour, or api.SurfaceVoxelConversionMethod.LineContour. |
smoothArtifacts | bool | Apply smoothing to reduce voxelization artifacts. |
Returns: list — A list of names for the created mask objects.
convert_to_volume_mesh
Converts surfaces to tetrahedral volume meshes. Generates tetrahedral volume meshes from closed manifold surfaces using either Auto3D or Grid3D algorithms. Parameters must be set first using set_volume_mesh_parameters() to configure meshing quality and method-specific options.
Signature:
convert_to_volume_mesh(surfaceNames: list, method: VolumeMeshMethod = api.VolumeMeshMethod.Auto3D, elementType: VolumeMeshElementType = api.VolumeMeshElementType.SurfaceSetting, maintainConformity: bool = False) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | A list containing the names of the surfaces to convert. |
method | VolumeMeshMethod | Volume mesh generation method. Use api.VolumeMeshMethod.Auto3D or api.VolumeMeshMethod.Grid3D. |
elementType | VolumeMeshElementType | Element type of the generated meshes. Use api.VolumeMeshElementType.SurfaceSetting, api.VolumeMeshElementType.Linear4Node, or api.VolumeMeshElementType.Quadratic10Node. The default uses the element type stored on the first surface. |
maintainConformity | bool | True to keep the meshes of touching surfaces conforming at their shared interfaces. Used only by api.VolumeMeshMethod.Grid3D. The default is False. |
Returns: list — A list of names for the created volume mesh objects.
Analysis
recompute_normals
Rebuilds the normals of the given surfaces from their current geometry. Use this after an edit that left the normals of a surface stale or missing. At least one of the two normal kinds has to be requested.
Signature:
recompute_normals(surfaceNames: list, faceNormals: bool = True, pointNormals: bool = True) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
surfaceNames | list | List of surface names to recompute the normals of. |
faceNormals | bool | True to rebuild the normal of every triangle. Default: True. |
pointNormals | bool | True to rebuild the normal of every point. Default: True. |