Mesh3d¶

Mesh3D -- mvp.mesh3d

Cluster: Physical AI | Type: component | MCP Tools: 32

Overview¶

Optional dependency boundary

mesh3d can load/store mesh arrays, analyze basic geometry, create box primitives, slice simple meshes, generate simple toolpaths, and validate G-code syntax without optional libraries. Production 3D workflows require optional dependencies: trimesh for boolean ops, non-box primitives, robust repair, and most mesh processing; open3d for point-cloud registration; and cadquery for parametric CAD. Install the optional packages directly in the target environment when those workflows are needed.

No machine control

Generated toolpaths and G-code are software artifacts only. The validator checks basic line structure and does not prove that commands are safe for a real CNC machine or printer.

File I/O and degradation

mesh3d does not import STL/OBJ/PLY/glTF files from disk. export_mesh writes a file only when file_path is explicit and trimesh is available; otherwise callers must inspect file_written, degraded, degradation_reason, completion_state, warning_card, and evidence.

3D mesh processing pipeline for mesh analysis, simple primitive creation, point-cloud conversion, basic slicing, simple toolpath generation, and G-code syntax validation. The MCP extension adds SQLite persistence for meshes, toolpaths, and G-code artefacts.

When to use:

Processing in-memory mesh vertices/faces for analysis or simple repair
Slicing a 3D model for rough layer inspection or generating a simple zigzag toolpath
Persisting and searching mesh libraries across agent sessions via the MCP store

When not to use:

Actual CNC, printer, robot, motor, spindle, or machine actuation; route those requests to motor_control or a machine-certified path
Real machine safety certification, fixture validation, collision checking, or production feeds-and-speeds validation
Disk-based mesh import or assuming file export happened without file_written: true

Example:

from mvp.mesh3d import Mesh3DBlock, Mesh3DInput

block = Mesh3DBlock(name="mesh3d")
result = block.infer(Mesh3DInput(
    op="create_primitive",
    primitive_type="box",
    dimensions={"size": [10.0, 20.0, 5.0]},
))
# result.value.is_watertight → bool; result.value.volume → float
result2 = block.infer(Mesh3DInput(op="slice_for_printing", layer_height=0.15))
# result2.value.layers → list of layer dicts

Works well with: motor_control, integration, physics_prediction

Public API¶

`Mesh3DBlock(AIBlock[Mesh3DInput, Mesh3DOutput, dict])`¶

3D mesh processing, slicing, toolpath, and G-code validation block (14 ops).

Field	Type	Default
`name`	`str`	'mesh3d'
`state`	`dict`	field(default_factory=dict)
`resource_bounds`	`ResourceBounds`	field(default_factory=ResourceBounds)
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)

Methods:

`infer(data: Mesh3DInput) -> Result[Mesh3DOutput]`¶

`Mesh3DInput(BaseModel)`¶

Input to Mesh3DBlock.

Field	Type	Default
`op`	`Literal['ops', 'help', 'load_mesh', 'analyze_mesh', 'create_primitive', 'boolean_op', 'repair_mesh', 'export_mesh', 'point_cloud_to_mesh', 'register_clouds', 'slice_for_printing', 'generate_toolpath', 'validate_gcode', 'create_part', 'get_info', 'reset']`	'load_mesh'
`vertices`	`list[list[float]]`	Field(default_factory=list)
`faces`	`list[list[int]]`	Field(default_factory=list)
`file_path`	`str`	''
`format`	`str`	'stl'
`primitive_type`	`str`	''
`dimensions`	`dict`	Field(default_factory=dict)
`boolean_type`	`str`	''
`mesh_b_vertices`	`list[list[float]]`	Field(default_factory=list)
`mesh_b_faces`	`list[list[int]]`	Field(default_factory=list)
`points`	`list[list[float]]`	Field(default_factory=list)
`layer_height`	`float`	0.2
`tool_diameter`	`float`	6.0
`step_over`	`float`	0.4
`gcode`	`str`	''
`cad_params`	`dict`	Field(default_factory=dict)
`name`	`str`	''

`Mesh3DOutput(BaseModel)`¶

Output from Mesh3DBlock.

Field	Type	Default
`op`	`str`	required
`vertices`	`list[list[float]]`	Field(default_factory=list)
`faces`	`list[list[int]]`	Field(default_factory=list)
`vertex_count`	`int`	0
`face_count`	`int`	0
`is_watertight`	`bool`	False
`volume`	`float`	0.0
`surface_area`	`float`	0.0
`layers`	`list[dict]`	Field(default_factory=list)
`toolpath`	`list[list[float]]`	Field(default_factory=list)
`gcode_valid`	`bool`	False
`gcode_errors`	`list[str]`	Field(default_factory=list)
`gcode_findings`	`list[dict]`	Field(default_factory=list)
`bounding_box`	`dict`	Field(default_factory=dict)
`backend`	`str`	'trimesh'
`metadata`	`dict`	Field(default_factory=dict)
`degraded`	`bool`	False
`degradation_reason`	`str \\| None`	None
`completion_state`	`CompletionState`	'qualified-draft'
`safety_classification`	`SafetyClassification`	'inspection_only'

`Mesh3DMCPBlock(AIBlock[MCPMesh3DInput, MCPMesh3DOutput, dict])`¶

26-op mesh3d MCP block with SQLite persistence.

Field	Type	Default
`name`	`str`	'mesh3d_mcp'
`state`	`dict`	field(default_factory=dict)
`db_path`	`str`	field(default_factory=lambda: os.environ.get('MESH3D_DB_PATH', _DEFAULT_DB))
`resource_bounds`	`ResourceBounds`	field(default_factory=ResourceBounds)
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)

Methods:

`infer(data: MCPMesh3DInput) -> Result[MCPMesh3DOutput]`¶

`MCPMesh3DInput(BaseModel)`¶

Input to Mesh3DMCPBlock -- 26 ops.

Field	Type	Default
`op`	`Literal['ops', 'help', 'load_mesh', 'analyze_mesh', 'create_primitive', 'boolean_op', 'repair_mesh', 'export_mesh', 'point_cloud_to_mesh', 'register_clouds', 'slice_for_printing', 'generate_toolpath', 'validate_gcode', 'create_part', 'get_info', 'reset', 'store_mesh', 'load_stored_mesh', 'list_meshes', 'delete_mesh', 'store_toolpath', 'list_toolpaths', 'store_gcode', 'validate_stored_gcode', 'search_meshes', 'mesh_stats', 'compare_meshes', 'list_patterns']`	required
`vertices`	`list[list[float]]`	Field(default_factory=list)
`faces`	`list[list[int]]`	Field(default_factory=list)
`file_path`	`str`	''
`format`	`str`	'stl'
`primitive_type`	`str`	''
`dimensions`	`dict`	Field(default_factory=dict)
`boolean_type`	`str`	''
`mesh_b_vertices`	`list[list[float]]`	Field(default_factory=list)
`mesh_b_faces`	`list[list[int]]`	Field(default_factory=list)
`points`	`list[list[float]]`	Field(default_factory=list)
`layer_height`	`float`	0.2
`tool_diameter`	`float`	6.0
`step_over`	`float`	0.4
`gcode`	`str`	''
`cad_params`	`dict`	Field(default_factory=dict)
`name`	`str`	''
`mesh_id`	`str`	''
`gcode_id`	`str`	''
`query`	`str`	''
`top_k`	`int`	10
`mesh_name`	`str`	''
`tags`	`str`	''

`MCPMesh3DOutput(BaseModel)`¶

Output from Mesh3DMCPBlock.

Field	Type	Default
`op`	`str`	required
`vertices`	`list[list[float]]`	Field(default_factory=list)
`faces`	`list[list[int]]`	Field(default_factory=list)
`vertex_count`	`int`	0
`face_count`	`int`	0
`is_watertight`	`bool`	False
`volume`	`float`	0.0
`surface_area`	`float`	0.0
`layers`	`list[dict]`	Field(default_factory=list)
`toolpath`	`list[list[float]]`	Field(default_factory=list)
`gcode_valid`	`bool`	False
`gcode_errors`	`list[str]`	Field(default_factory=list)
`backend`	`str`	'trimesh'
`metadata`	`dict`	Field(default_factory=dict)
`message`	`str`	''
`count`	`int`	0
`retrieved`	`list[dict]`	Field(default_factory=list)
`degraded`	`bool`	False
`degradation_reason`	`str \\| None`	None
`completion_state`	`Literal['qualified-draft', 'blocked-escalated']`	'qualified-draft'
`safety_classification`	`Literal['inspection_only', 'simulation_only', 'syntax_validated', 'machine_certified_false']`	'inspection_only'

`Mesh3DStore`¶

SQLite-backed store for the mesh3d MCP sub-package.

Constructor:

Parameter	Type	Default
`db_path`	`str`	':memory:'

Methods:

`store_mesh(name: str, vertices: list, faces: list, tags: str = '', metadata: dict | None = None) -> str`¶

`load_mesh(mesh_id: str = '', name: str = '') -> dict | None`¶

`list_meshes(limit: int = 50) -> list[dict]`¶

`delete_mesh(mesh_id: str) -> bool`¶

`search_meshes(query: str, limit: int = 10) -> list[dict]`¶

`store_toolpath(mesh_id: str, toolpath: list, tool_diameter: float = 6.0, step_over: float = 0.4, metadata: dict | None = None) -> str`¶

`list_toolpaths(limit: int = 50) -> list[dict]`¶

`store_gcode(mesh_id: str, gcode_text: str, is_valid: bool = False, errors: list | None = None, metadata: dict | None = None) -> str`¶

`load_gcode(gcode_id: str) -> dict | None`¶

`store_part(name: str, params: dict, mesh_id: str = '') -> str`¶

`log_operation(op: str, params: dict | None = None, result: dict | None = None) -> None`¶

`log_error(op: str, error_message: str, params: dict | None = None) -> None`¶

`count_all() -> dict[str, int]`¶

MCP Tools¶

Operation	Source
`ops`	mesh3d_mcp
`help`	mesh3d_mcp
`load_mesh`	mesh3d_mcp
`analyze_mesh`	mesh3d_mcp
`create_primitive`	mesh3d_mcp
`boolean_op`	mesh3d_mcp
`repair_mesh`	mesh3d_mcp
`export_mesh`	mesh3d_mcp
`point_cloud_to_mesh`	mesh3d_mcp
`register_clouds`	mesh3d_mcp
`slice_for_printing`	mesh3d_mcp
`generate_toolpath`	mesh3d_mcp
`validate_gcode`	mesh3d_mcp
`create_part`	mesh3d_mcp
`get_info`	mesh3d_mcp
`reset`	mesh3d_mcp
`store_mesh`	mesh3d_mcp
`load_stored_mesh`	mesh3d_mcp
`list_meshes`	mesh3d_mcp
`delete_mesh`	mesh3d_mcp
`store_toolpath`	mesh3d_mcp
`list_toolpaths`	mesh3d_mcp
`store_gcode`	mesh3d_mcp
`validate_stored_gcode`	mesh3d_mcp
`search_meshes`	mesh3d_mcp
`mesh_stats`	mesh3d_mcp
`compare_meshes`	mesh3d_mcp
`list_patterns`	mesh3d_mcp
`inspection_only`	mesh3d_mcp
`simulation_only`	mesh3d_mcp
`syntax_validated`	mesh3d_mcp
`machine_certified_false`	mesh3d_mcp

Mesh3d¶

Overview¶

Public API¶

Mesh3DBlock(AIBlock[Mesh3DInput, Mesh3DOutput, dict])¶

infer(data: Mesh3DInput) -> Result[Mesh3DOutput]¶

Mesh3DInput(BaseModel)¶

Mesh3DOutput(BaseModel)¶

Mesh3DMCPBlock(AIBlock[MCPMesh3DInput, MCPMesh3DOutput, dict])¶

infer(data: MCPMesh3DInput) -> Result[MCPMesh3DOutput]¶

MCPMesh3DInput(BaseModel)¶

MCPMesh3DOutput(BaseModel)¶

Mesh3DStore¶

store_mesh(name: str, vertices: list, faces: list, tags: str = '', metadata: dict | None = None) -> str¶

load_mesh(mesh_id: str = '', name: str = '') -> dict | None¶

list_meshes(limit: int = 50) -> list[dict]¶

delete_mesh(mesh_id: str) -> bool¶

search_meshes(query: str, limit: int = 10) -> list[dict]¶

store_toolpath(mesh_id: str, toolpath: list, tool_diameter: float = 6.0, step_over: float = 0.4, metadata: dict | None = None) -> str¶

list_toolpaths(limit: int = 50) -> list[dict]¶

store_gcode(mesh_id: str, gcode_text: str, is_valid: bool = False, errors: list | None = None, metadata: dict | None = None) -> str¶

load_gcode(gcode_id: str) -> dict | None¶

store_part(name: str, params: dict, mesh_id: str = '') -> str¶

log_operation(op: str, params: dict | None = None, result: dict | None = None) -> None¶

log_error(op: str, error_message: str, params: dict | None = None) -> None¶

count_all() -> dict[str, int]¶

MCP Tools¶

`Mesh3DBlock(AIBlock[Mesh3DInput, Mesh3DOutput, dict])`¶

`infer(data: Mesh3DInput) -> Result[Mesh3DOutput]`¶

`Mesh3DInput(BaseModel)`¶

`Mesh3DOutput(BaseModel)`¶

`Mesh3DMCPBlock(AIBlock[MCPMesh3DInput, MCPMesh3DOutput, dict])`¶

`infer(data: MCPMesh3DInput) -> Result[MCPMesh3DOutput]`¶

`MCPMesh3DInput(BaseModel)`¶

`MCPMesh3DOutput(BaseModel)`¶

`Mesh3DStore`¶

`store_mesh(name: str, vertices: list, faces: list, tags: str = '', metadata: dict | None = None) -> str`¶

`load_mesh(mesh_id: str = '', name: str = '') -> dict | None`¶

`list_meshes(limit: int = 50) -> list[dict]`¶

`delete_mesh(mesh_id: str) -> bool`¶

`search_meshes(query: str, limit: int = 10) -> list[dict]`¶

`store_toolpath(mesh_id: str, toolpath: list, tool_diameter: float = 6.0, step_over: float = 0.4, metadata: dict | None = None) -> str`¶

`list_toolpaths(limit: int = 50) -> list[dict]`¶

`store_gcode(mesh_id: str, gcode_text: str, is_valid: bool = False, errors: list | None = None, metadata: dict | None = None) -> str`¶

`load_gcode(gcode_id: str) -> dict | None`¶

`store_part(name: str, params: dict, mesh_id: str = '') -> str`¶

`log_operation(op: str, params: dict | None = None, result: dict | None = None) -> None`¶

`log_error(op: str, error_message: str, params: dict | None = None) -> None`¶

`count_all() -> dict[str, int]`¶