Get full scene information including object tree, hierarchy, counts, frame range, fps, and render engine.

Returns a dict with scene name, object list with hierarchy, object type counts, frame range (start, end, current), fps, and active render engine.

Set a scene property such as frame_start, frame_end, frame_current, fps, unit_system, or render_engine.

Args: property: The scene property to set. Must be one of: frame_start, frame_end, frame_current, frame_step, fps, unit_system, render_engine, use_gravity, gravity. value: The value to set the property to. Type depends on the property.

Returns: Confirmation dict with the property name and new value.

List all scenes in the current Blender file.

Returns a list of dicts, each containing the scene name and object count.

Create a new scene.

Args: name: Name for the new scene.

Returns: Confirmation dict with the created scene name.

Delete a scene by name.

Args: scene_name: Name of the scene to delete. Cannot delete the last remaining scene.

Returns: Confirmation dict.

Suggest helpful Blender extensions for a planned task.

Analyzes the task description and recommends free Blender extensions that could improve the workflow. Already-installed extensions are excluded.

Args: task_description: Description of the planned task. If empty, returns all extensions not currently installed.

Returns: Dict with 'suggestions' list of recommended extensions and 'installed' list of already-installed extension IDs.

Create a primitive object in the scene.

Args: type: Primitive type. One of: CUBE, SPHERE, UV_SPHERE, ICO_SPHERE, CYLINDER, CONE, TORUS, PLANE, CIRCLE, MONKEY, EMPTY. name: Optional name for the object. Auto-generated if empty. location: XYZ position as a 3-element list/tuple. Defaults to origin. rotation: XYZ Euler rotation in radians as a 3-element list/tuple. scale: XYZ scale as a 3-element list/tuple. Defaults to (1,1,1).

Returns: Dict with the created object's name, type, and location.

Create an N-sided regular prism (polygon-based cylinder).

Useful for hex sockets, octagonal columns, triangular prisms, or any straight-sided geometry where a 32-sided round cylinder is the wrong primitive. For a hex socket cutter on an M3 button-head screw, use sides=6.

Args: sides: Number of sides for the polygon base. Range: 3-64. radius: Circumscribed radius (center to vertex). Must be > 0. depth: Height of the prism along its Z axis. Must be > 0. name: Optional name for the object. Auto-generated if empty. location: XYZ position as a 3-element list/tuple. Defaults to origin. rotation: XYZ Euler rotation in radians as a 3-element list/tuple. scale: XYZ scale as a 3-element list/tuple. Defaults to (1,1,1).

Returns: Dict with the created object's name, type, location, and sides.

Create a cylindrical shaft with helical external threads.

Produces a single mesh object — a threaded rod at the given diameter and length, with helical thread ridges following the specified pitch. Suitable for boolean-union onto a screw-head or direct use as a threaded fastener.

Thread geometry: a 60-degree V profile swept along a Z-axis helix via the Screw modifier.

Args: diameter: Major diameter of the shaft (outer thread peaks). Must be > 0. length: Axial length of the shaft (under-head length, like real fastener spec). Must be > 0. pitch: Distance between thread peaks along the axis. Must be > 0 and <= length. thread_depth: Radial depth of the thread (major radius - minor radius). If 0 (default), auto-computed as pitch * 0.54. segments: Rotational resolution of the helix (steps per revolution). Range: 3-256. Higher = smoother helix, more geometry. thread_runout: Smooth (unthreaded) region at the top of the shaft. Defaults to 0 (full-length threads) — gives the strongest print because threads under the head form a continuous stress path. Leaving a smooth runout creates a thin-walled neck at minor_r that snaps under torque in FDM prints. Pass a positive value only if a head's deep hex socket would otherwise reach thread peaks. name: Optional name for the object. Auto-generated if empty. location: XYZ position of the shaft base as a 3-element list/tuple.

Returns: Dict with the created object's name, diameter, length, pitch, and the number of thread iterations actually generated.

Delete an object from the scene by name.

Args: object_name: Name of the object to delete.

Returns: Confirmation dict.

Duplicate an object.

Args: object_name: Name of the object to duplicate. linked: If True, create a linked duplicate (shares mesh data). Defaults to False.

Returns: Dict with the new object's name.

Rename an object.

Args: old_name: Current name of the object. new_name: New name for the object.

Returns: Dict with old and new names.

Select objects by name.

Args: names: List of object names to select. deselect_others: If True, deselect all other objects first. Defaults to True.

Returns: Dict with list of selected object names.

Get detailed information about an object.

Args: object_name: Name of the object.

Returns: Dict with type, location, rotation, scale, modifiers, materials, parent, children, and visibility info.

List all objects in the scene, optionally filtered by type.

Args: type_filter: Filter by object type (e.g., MESH, LIGHT, CAMERA, EMPTY). Empty string returns all objects.

Returns: List of dicts with object name, type, and location.

Set object visibility in viewport and/or render.

Args: object_name: Name of the object. visible: Whether the object should be visible. viewport: Apply visibility change to viewport. Defaults to True. render: Apply visibility change to render. Defaults to True.

Returns: Confirmation dict with visibility state.

Set parent-child relationship between two objects.

Args: child: Name of the child object. parent: Name of the parent object.

Returns: Confirmation dict.

Join multiple mesh objects into one (keeps all geometry as-is).

This merges objects into a single datablock without modifying geometry. The meshes remain separate inside the object (no boolean merge).

TIP: If you want to truly fuse overlapping meshes into one solid shape, use booltool_auto_union instead — it performs a boolean union that merges the geometry and removes internal faces.

Args: names: List of object names to join. The first name becomes the active object.

Returns: Dict with the resulting joined object name.

Convert an object to a different type.

Args: object_name: Name of the object to convert. target: Target type. One of: MESH, CURVE, SURFACE, META, FONT, CURVES, POINTCLOUD, GPENCIL.

Returns: Confirmation dict.

Apply angle-based auto-smooth shading to an object.

Smooths faces only where the angle between adjacent face normals is below the given threshold, giving clean results on hard-surface models.

Args: object_name: Name of the mesh object. angle: Auto-smooth angle threshold in radians (0.0 to pi). Defaults to ~30 degrees (0.523599 rad).

Returns: Confirmation dict.

Make an object's data single-user (unlink shared datablocks).

Args: object_name: Name of the object. object: Make the object single-user. Defaults to True. data: Make the object data (e.g., mesh) single-user. Defaults to True.

Returns: Confirmation dict.

Set the position of an object.

Args: object_name: Name of the object. location: XYZ position as a 3-element list/tuple.

Returns: Dict with the object name and new location.

Set the rotation of an object.

Args: object_name: Name of the object. rotation: Rotation values. For EULER mode, XYZ angles in radians (3 elements). For QUATERNION mode, WXYZ values (4 elements). mode: Rotation mode, either EULER or QUATERNION. Defaults to EULER.

Returns: Dict with the object name and new rotation.

Set the scale of an object.

Args: object_name: Name of the object. scale: XYZ scale as a 3-element list/tuple.

Returns: Dict with the object name and new scale.

Apply (freeze) transforms on an object, making current transforms the new basis.

Args: object_name: Name of the object. location: Apply location transform. Defaults to True. rotation: Apply rotation transform. Defaults to True. scale: Apply scale transform. Defaults to True.

Returns: Confirmation dict.

Set the origin point of an object.

Args: object_name: Name of the object. type: Origin type. One of: GEOMETRY (origin to geometry center), CURSOR (origin to 3D cursor), CENTER_OF_MASS (origin to center of mass), CENTER_OF_VOLUME (origin to center of volume). Defaults to GEOMETRY.

Returns: Confirmation dict with new origin location.

Snap an object's location to the nearest grid point.

Args: object_name: Name of the object. grid_size: Size of the grid cells. Defaults to 1.0.

Returns: Dict with the object name and snapped location.

Add a modifier to a mesh object (non-destructive workflow).

TIP: For BOOLEAN type, consider using booltool_auto_union/difference/intersect/slice instead — they apply the boolean immediately and handle cutter cleanup automatically. Only use add_modifier with BOOLEAN when you want a non-destructive modifier stack.

Args: object_name: Name of the object to add the modifier to. modifier_type: Type of modifier. Must be one of: SUBSURF, MIRROR, ARRAY, BEVEL, BOOLEAN, SOLIDIFY, DECIMATE, REMESH, WIREFRAME, SHRINKWRAP, SMOOTH, EDGE_SPLIT, TRIANGULATE, WEIGHTED_NORMAL, SIMPLE_DEFORM, LATTICE, CURVE, CAST, WAVE, DISPLACE, SCREW, SKIN, MASK, WELD, CORRECTIVE_SMOOTH, LAPLACIAN_SMOOTH, SURFACE_DEFORM, MESH_DEFORM, HOOK. name: Optional custom name for the modifier.

Returns: Confirmation dict with modifier details.

Remove a modifier from an object.

Args: object_name: Name of the object. modifier_name: Name of the modifier to remove.

Returns: Confirmation dict.

Apply a modifier to an object, making its effect permanent.

Args: object_name: Name of the object. modifier_name: Name of the modifier to apply.

Returns: Confirmation dict.

Set a property on a modifier (e.g., levels, count, offset, angle).

Args: object_name: Name of the object. modifier_name: Name of the modifier. property: The modifier property to set (e.g., 'levels', 'count', 'width', 'segments', 'angle', 'offset', 'ratio', 'iterations'). value: The value to set.

Returns: Confirmation dict with updated property.

Perform a boolean operation between two objects using a modifier.

NOTE: For destructive booleans, prefer the booltool_auto_* tools instead (booltool_auto_union, booltool_auto_difference, booltool_auto_intersect, booltool_auto_slice). They handle selection and cutter cleanup automatically. Use this tool only when you need a non-destructive boolean modifier workflow.

Args: object_name: Name of the object to apply the boolean to. target_name: Name of the target/cutter object. operation: Boolean operation type. One of: UNION, DIFFERENCE, INTERSECT.

Returns: Confirmation dict with operation details.

Subdivide a mesh.

Args: object_name: Name of the mesh object to subdivide. cuts: Number of cuts per edge. Range: 1-100.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Extrude all faces of a mesh along their normals.

Args: object_name: Name of the mesh object. offset: Extrusion distance along face normals.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Bevel all edges of a mesh.

Args: object_name: Name of the mesh object. width: Bevel width. segments: Number of bevel segments. Range: 1-100.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Add loop cuts to a mesh object.

Args: object_name: Name of the mesh object. cuts: Number of loop cuts. Range: 1-100.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Set smooth or flat shading on an object.

TIP: For production use, prefer shade_auto_smooth which provides angle-based auto-smooth shading — it gives better results on hard-surface models by only smoothing faces within the angle threshold.

Args: object_name: Name of the mesh object. smooth: True for smooth shading, False for flat shading.

Returns: Confirmation dict.

Merge vertices by distance.

Args: object_name: Name of the mesh object. threshold: Maximum distance between vertices to merge. Range: 0.0-10.0.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict with number of removed vertices.

Separate a mesh into parts.

Args: object_name: Name of the mesh object. type: Separation method. One of: SELECTED, MATERIAL, LOOSE.

Returns: Confirmation dict.

Bridge two edge loops to create connecting geometry.

Select two edge loops on a mesh before calling this. The operation creates faces connecting the two loops, useful for connecting separate mesh parts, creating holes between surfaces, or building tube-like geometry.

Args: object_name: Name of the mesh object with selected edge loops. segments: Number of segments in the bridge. Range: 1-1000. profile_shape_factor: Shape of the bridge profile. Range: -1.0 to 1.0. 0.0 is straight, positive values bulge outward, negative inward.

Returns: Confirmation dict with bridge details.

Create a new material with a Principled BSDF shader node.

Args: name: Name for the new material.

Returns: Confirmation dict with the created material name.

Assign a material to an object.

Args: object_name: Name of the target object. material_name: Name of the material to assign.

Returns: Confirmation dict.

Set the base color of a material's Principled BSDF node.

Args: material_name: Name of the material. color: RGBA color as a list of 4 floats (0.0-1.0). e.g. [1.0, 0.0, 0.0, 1.0] for red.

Returns: Confirmation dict.

Set a property on a material's Principled BSDF node.

Args: material_name: Name of the material. property: Property to set. One of: metallic, roughness, specular_ior_level, emission_strength, alpha, transmission_weight, ior, coat_weight, coat_roughness, sheen_weight, sheen_roughness, anisotropic, anisotropic_rotation, subsurface_weight, emission_color. value: The value to set. Float for most properties, list for color properties.

Returns: Confirmation dict.

Create a fully configured Principled BSDF material in one call.

Args: name: Name for the new material. color: Base color as RGBA list, default [0.8, 0.8, 0.8, 1.0]. metallic: Metallic value 0.0-1.0, default 0.0. roughness: Roughness value 0.0-1.0, default 0.5. specular: Specular IOR level 0.0-1.0, default 0.5. emission_strength: Emission strength, default 0.0. emission_color: Emission color as RGBA list, default [1.0, 1.0, 1.0, 1.0]. alpha: Alpha value 0.0-1.0, default 1.0. transmission: Transmission weight 0.0-1.0, default 0.0. ior: Index of refraction, default 1.45.

Returns: Confirmation dict with material name and all set properties.

Add an image texture node to a material and connect it to the Principled BSDF Base Color.

Args: material_name: Name of the material. image_path: Absolute path to the image file. Must exist on disk. label: Label for the texture node, default "Image Texture".

Returns: Confirmation dict.

Set the blend mode of a material (EEVEE).

Args: material_name: Name of the material. mode: Blend mode. One of: OPAQUE, CLIP, HASHED, BLEND.

Returns: Confirmation dict.

List all materials in the current Blender file.

Returns: List of dicts with material name and user count.

Delete a material by name.

Args: material_name: Name of the material to delete.

Returns: Confirmation dict.

Duplicate a material with a new name.

Args: material_name: Name of the material to duplicate. new_name: Name for the duplicated material.

Returns: Confirmation dict with the new material name.

Add a shader node to a material's node tree.

Args: material_name: Name of the material. node_type: Blender shader node type (e.g. ShaderNodeBsdfPrincipled). location: Node location as [x, y], default [0, 0].

Returns: Dict with material, node_name, and node_type.

Connect two shader nodes in a material's node tree.

Args: material_name: Name of the material. from_node: Name of the source node. from_socket: Name of the output socket on the source node. to_node: Name of the destination node. to_socket: Name of the input socket on the destination node.

Returns: Confirmation dict.

Disconnect all links from a specific socket on a shader node.

Args: material_name: Name of the material. node_name: Name of the node. socket_name: Name of the socket to disconnect. is_input: If True, disconnect an input socket; otherwise an output socket.

Returns: Confirmation dict.

Remove a shader node from a material's node tree.

Args: material_name: Name of the material. node_name: Name of the node to remove.

Returns: Confirmation dict.

Get the full node tree of a material (all nodes and links).

Args: material_name: Name of the material.

Returns: Dict with nodes list and links list.

Set the default value of an unconnected input socket on a shader node.

This is how you dial in a procedural texture: Noise 'Scale' and 'Detail', Mapping 'Scale' and 'Rotation', a Principled BSDF 'Roughness', and so on. A socket that has a link into it ignores its default value, so disconnect it first if you want the default to take effect.

Args: material_name: Name of the material. node_name: Name of the node. socket: Socket name, or a zero-based index. Use the index when names are ambiguous — a Math node has two inputs both called 'Value'. value: A number, a boolean, or a 2-4 component list for vectors and colors (colors are RGBA).

Returns: Dict with the node, socket, and the value that was applied.

Set a node-level property (not a socket) on a shader node.

These are the dropdowns and checkboxes on the node body rather than its input sockets: Math 'operation', Mix 'blend_type', Voronoi 'feature' (use 'DISTANCE_TO_EDGE' for vein and crack patterns), Wave 'wave_type' and 'bands_direction', Noise 'noise_dimensions'.

Args: material_name: Name of the material. node_name: Name of the node. property: Property name. Must be one of the allowed node properties. value: String enum identifier, number, or boolean.

Returns: Dict with the node, property, and the value that was applied.

Add a colour stop to a ColorRamp (ShaderNodeValToRGB) node.

A new ramp starts with two stops, black at 0.0 and white at 1.0. Add stops to shape a gradient: fire needs dark red, orange, yellow, white bunched toward the top; rust needs a hard break between metal and oxide.

Args: material_name: Name of the material. node_name: Name of the ColorRamp node. position: Stop position along the ramp, 0.0 to 1.0. color: RGB or RGBA color, components 0.0 to 1.0. RGB gains alpha 1.0.

Returns: Dict with the new element's index, position, and color.

Remove a colour stop from a ColorRamp node.

Blender requires at least one stop to remain; removing the last one fails.

Args: material_name: Name of the material. node_name: Name of the ColorRamp node. index: Zero-based index of the stop to remove.

Returns: Dict with the removed index and the remaining element count.

Move or recolor an existing ColorRamp stop.

At least one of position or color must be given. Moving a stop past a neighbour reorders the ramp, so indices may shift after this call — read the ramp back with get_color_ramp if you need certainty.

Args: material_name: Name of the material. node_name: Name of the ColorRamp node. index: Zero-based index of the stop to edit. position: New position, 0.0 to 1.0. Omit to leave unchanged. color: New RGB or RGBA color. Omit to leave unchanged.

Returns: Dict with the element's resulting position and color.

Set how a ColorRamp blends between its stops.

'CONSTANT' gives hard-edged bands with no blending, which is what turns a noise or voronoi texture into discrete regions: scale plates, cracked mud, stylised cel shading. 'EASE' and 'B_SPLINE' give softer falloff than 'LINEAR'. Set color_mode to 'HSV' to sweep through hues between two stops rather than blending through grey.

Args: material_name: Name of the material. node_name: Name of the ColorRamp node. interpolation: One of EASE, CARDINAL, LINEAR, B_SPLINE, CONSTANT. color_mode: Optional. One of RGB, HSV, HSL. Omit to leave unchanged.

Returns: Dict with the applied interpolation and color mode.

Read every stop on a ColorRamp node.

Use this before editing to learn the current indices and positions, since add and move operations reorder stops.

Args: material_name: Name of the material. node_name: Name of the ColorRamp node.

Returns: Dict with elements (index, position, color), interpolation, color_mode.

Build a complete procedural texture as a material, in one call.

Prefer this over hand-wiring texture nodes. It creates the full graph — coordinates, mapping, the pattern's texture nodes, a tuned colour ramp, and the Principled BSDF — and returns the node names so you can adjust anything afterwards with set_shader_node_input or the colour ramp tools.

Procedural beats image textures here: no files, no UV unwrap needed, and it stays sharp at any camera distance.

Call list_procedural_patterns() to see what each pattern looks like.

Args: name: Name for the new material. pattern: One of the supported patterns, e.g. 'fire', 'wood', 'veins'. scale: Feature size. Lower is bigger and broader, higher is finer and busier. 5.0 is a sensible default; try 1-3 for large forms and 20+ for fine detail. detail: Fractal octaves, 0-15. Higher adds finer sub-detail at the cost of render time. Applies to noise, cloud, wood, marble, plasma and fire. The cellular patterns (voronoi, veins, scales, sparks), stripes, weave and gradient have no detail socket and ignore it. distortion: Warps the pattern. Small values (0.5-2.0) make wood and marble look organic rather than machine-perfect. Applies to noise, cloud, stripes, wood, marble, plasma and fire. The cellular patterns, weave and gradient ignore it. roughness: Surface roughness 0-1 for the Principled BSDF. metallic: Metallic 0-1 for the Principled BSDF. colors: Optional list of RGB or RGBA colours for the ramp, in order. Omit to use the pattern's own tuned palette. banded: Use CONSTANT ramp interpolation, giving hard-edged bands instead of smooth blending. Turns noise into discrete regions: scale plates, cracked mud, cel shading. connect_to_bsdf: Wire the result into the Principled BSDF base colour so the material renders immediately. Set False to leave the pattern subtree unconnected for manual wiring.

Returns: Dict with the material name, the created node names, and ignored_params listing any arguments this pattern could not use.

Generate an image texture for patterns shader nodes cannot express.

Use this only for patterns that place discrete marks. Shader nodes evaluate a function per point and have no way to say "draw a glyph here, then another over there", so runes need real pixels. Everything else should go through create_procedural_material, which stays sharp at any resolution.

The image is packed into the blend file. No file is written to disk.

Args: name: Name for the generated image datablock. pattern: A raster pattern. Currently 'runes'. size: Pixel width and height, up to 2048. Cost grows with the square. count: How many marks to stamp. 0 leaves a blank field. seed: Change for a different arrangement; the same seed always reproduces the same image. foreground: RGB or RGBA colour of the marks. background: RGB or RGBA colour behind them.

Returns: Dict with the image name, size, and mark count.

List every procedural pattern with a description of what it looks like.

Read this before calling create_procedural_material so you pick a pattern that matches the surface you are trying to make.

Returns: Dict with the sorted pattern names and a description of each.

Create a new light in the scene.

Args: type: Light type. One of: POINT, SUN, SPOT, AREA. name: Optional name for the light. location: XYZ location as [x, y, z], default [0, 0, 0]. energy: Light energy/power, default 1000. color: RGB color as [r, g, b], default [1.0, 1.0, 1.0].

Returns: Confirmation dict with light name and properties.

Set a property on a light object.

Args: object_name: Name of the light object. property: Property to set. One of: energy, color, shadow_soft_size, spot_size, spot_blend, area_size, area_size_y, use_shadow, angle, specular_factor, diffuse_factor, volume_factor. value: The value to set. Type depends on the property.

Returns: Confirmation dict.

Set the world background to a solid color or HDRI environment map.

Args: color: RGB color as [r, g, b] for solid background. Mutually exclusive with hdri_path. hdri_path: Absolute path to an HDRI image file. Mutually exclusive with color. strength: Background strength/intensity, default 1.0.

Returns: Confirmation dict.

Create a pre-built lighting rig (multiple lights arranged for common setups).

Args: type: Rig type. One of: THREE_POINT, STUDIO, RIM, OUTDOOR. target: Optional name of the object the rig should point at. intensity: Overall intensity of the lights, default 1000.

Returns: Confirmation dict with names of all created lights.

List all light objects in the scene.

Returns: List of dicts with light name, type, energy, color, and location.

Delete a light object from the scene.

Args: object_name: Name of the light object to delete.

Returns: Confirmation dict.

Configure shadow settings for a light.

Args: object_name: Name of the light object. use_shadow: Whether to enable shadows, default True. shadow_soft_size: Soft shadow radius, default 0.25.

Returns: Confirmation dict.

Create a new camera in the scene.

Args: name: Name for the camera, default "Camera". location: XYZ location as [x, y, z], default [0, 0, 0]. rotation: XYZ Euler rotation in radians as [x, y, z], default [0, 0, 0]. lens: Focal length in mm, default 50.

Returns: Confirmation dict with camera name and properties.

Set a property on a camera.

Args: object_name: Name of the camera object. property: Property to set. One of: lens, clip_start, clip_end, sensor_width, sensor_height, dof.use_dof, dof.focus_distance, dof.aperture_fstop, ortho_scale, shift_x, shift_y, type, sensor_fit. value: The value to set.

Returns: Confirmation dict.

Set the active scene camera.

Args: object_name: Name of the camera object to make active.

Returns: Confirmation dict.

Point a camera at an object or a specific location using a Track To constraint.

Args: camera_name: Name of the camera object. target: Name of an existing object to point at, as a string. For coordinates use location instead. Mutually exclusive with location. location: XYZ location to point at as [x, y, z]. Mutually exclusive with target.

Returns: Confirmation dict.

Render the viewport to a file or return as base64.

Args: filepath: Optional absolute path for output image. If empty, returns base64-encoded image. width: Render width in pixels, default 1920. height: Render height in pixels, default 1080.

Returns: Dict with filepath or base64 image data.

Match the active camera to the current 3D viewport view.

Returns: Confirmation dict with the camera's new location and rotation.

Insert a keyframe on an object property at a specific frame.

Args: object_name: Name of the object. data_path: Property to keyframe. Must be one of: location, rotation_euler, rotation_quaternion, scale, or indexed variants like location[0]. frame: Frame number to insert the keyframe at. value: Optional value to set before inserting the keyframe.

Returns: Confirmation dict with keyframe details.

Remove a keyframe from an object property at a specific frame.

Args: object_name: Name of the object. data_path: Property data path (e.g., location, rotation_euler, scale). frame: Frame number of the keyframe to remove.

Returns: Confirmation dict.

Set the current frame in the timeline.

Args: frame: Frame number to set as current.

Returns: Confirmation dict with the new current frame.

Set the start and end frames of the scene timeline.

Args: start: Start frame number. end: End frame number. Must be greater than start.

Returns: Confirmation dict with the new frame range.

Set the interpolation type for keyframes on a property.

Args: object_name: Name of the object. data_path: Property data path. interpolation: Interpolation type. One of: CONSTANT, LINEAR, BEZIER, SINE, QUAD, CUBIC, QUART, QUINT, EXPO, CIRC, BACK, BOUNCE, ELASTIC.

Returns: Confirmation dict.

Make an object follow a path (curve) using a Follow Path constraint.

Args: object_name: Name of the object to animate along the path. path_object: Name of the curve object to use as the path.

Returns: Confirmation dict with constraint details.

List all keyframes on an object.

Args: object_name: Name of the object.

Returns: List of dicts with data_path, frame, and value for each keyframe.

Remove all animation data from an object.

Args: object_name: Name of the object.

Returns: Confirmation dict.

Set the render engine.

Args: engine: Render engine to use. One of: BLENDER_EEVEE, CYCLES, BLENDER_WORKBENCH.

Returns: Confirmation dict with the active render engine.

Set the render resolution.

Args: width: Render width in pixels. Range: 1-8192. height: Render height in pixels. Range: 1-8192. percentage: Resolution percentage scale. Range: 1-100.

Returns: Confirmation dict with the new resolution settings.

Set the number of render samples.

Args: samples: Number of samples. Range: 1-10000.

Returns: Confirmation dict with the new sample count.

Set the render output format and optionally the output file path.

Args: format: Output format. One of: PNG, JPEG, OPEN_EXR, TIFF, BMP. filepath: Optional output file path. Must be an absolute path.

Returns: Confirmation dict with the new output settings.

Render the current scene to an image file.

Args: filepath: Output file path for the rendered image. Must be an absolute path with a valid image extension (.png, .jpg, .exr, .tiff, .bmp).

Returns: Confirmation dict with the output file path.

Render the animation sequence to image files.

Args: filepath: Output file path prefix for the rendered frames. Each frame will be saved with a frame number suffix. format: Output format. One of: PNG, JPEG, OPEN_EXR, TIFF, BMP.

Returns: Confirmation dict with output details.

Set EEVEE light intensity controls (Blender 5.1+).

Scales how strongly direct and indirect lighting contribute. Only applies when the render engine is EEVEE.

Args: direct_intensity: Multiplier for light arriving straight from a lamp. Range 0.0-10.0, 1.0 is unchanged. Leave unset to keep the current value. indirect_intensity: Multiplier for bounced light. Range 0.0-10.0, 1.0 is unchanged. Leave unset to keep the current value.

Returns: Dict with both intensities after the change.

Create a new curve object.

Args: type: Curve type - BEZIER, NURBS, or PATH. name: Optional name for the curve object. location: 3D location as (x, y, z).

Returns: Dict with created curve name and type.

Add a control point to an existing curve.

Args: curve_name: Name of the curve object to add a point to. location: 3D location for the new point as (x, y, z). handle_type: Handle type - AUTO, VECTOR, ALIGNED, or FREE.

Returns: Dict with curve name and new point count.

Set a property on a curve object.

Args: curve_name: Name of the curve object. property: Property to set - resolution_u, fill_mode, bevel_depth, bevel_resolution, extrude, twist_mode, or use_fill_caps. value: Value to set. Type depends on property.

Returns: Confirmation dict with property name and new value.

Convert a curve object to a mesh object.

Args: curve_name: Name of the curve object to convert.

Returns: Dict with the converted object name.

Create a 3D text object.

Args: text: The text string to display. name: Optional name for the text object. location: 3D location as (x, y, z). size: Font size. font: Optional path to a font file. Uses default Blender font if empty.

Returns: Dict with created text object name.

Switch the direction of a curve's splines.

Args: curve_name: Name of the curve object.

Returns: Dict with confirmation of direction switch.

Set the handle type for all control points of a curve.

Args: curve_name: Name of the curve object. handle_type: Handle type - AUTO, VECTOR, ALIGNED, or FREE_ALIGN.

Returns: Dict with confirmation of handle type change.

Toggle the cyclic (closed loop) state of a curve.

Args: curve_name: Name of the curve object.

Returns: Dict with confirmation of cyclic toggle.

Subdivide a curve by adding control points between existing ones.

Args: curve_name: Name of the curve object. number_cuts: Number of cuts to make (1-100).

Returns: Dict with confirmation of subdivision.

Smooth the control points of a curve.

Args: curve_name: Name of the curve object.

Returns: Dict with confirmation of smoothing.

Enter sculpt mode for a mesh object.

Args: object_name: Name of the mesh object to sculpt.

Returns: Confirmation dict with object name and mode.

Exit sculpt mode and return to object mode.

Returns: Confirmation dict with current mode.

Set the active sculpt brush.

Args: brush_type: Brush type - DRAW, CLAY, CLAY_STRIPS, INFLATE, GRAB, SMOOTH, FLATTEN, FILL, SCRAPE, PINCH, CREASE, BLOB, MASK, MULTIRES_DISPLACEMENT_SMEAR.

Returns: Confirmation dict with active brush type.

Set a property on the active sculpt brush.

Args: property: Property to set - size, strength, auto_smooth_factor, or use_frontface. value: Value to set. size is int (1-500), strength is float (0.0-1.0), auto_smooth_factor is float (0.0-1.0), use_frontface is bool.

Returns: Confirmation dict with property name and new value.

Remesh an object to create a clean topology.

Args: object_name: Name of the mesh object to remesh. voxel_size: Voxel size for remeshing (smaller = more detail). Only used in VOXEL mode. mode: Remesh mode - VOXEL, SHARP, SMOOTH, or BLOCKS.

Returns: Dict with object name and new vertex count.

Add a Multiresolution modifier for sculpting detail.

Args: object_name: Name of the mesh object. levels: Number of subdivision levels to add (1-6).

Returns: Dict with object name and modifier info.

Set sculpt symmetry axes.

Enables symmetrical sculpting across the specified axes. X-axis symmetry is the most common for character modeling.

Args: use_x: Enable X-axis symmetry. Defaults to True. use_y: Enable Y-axis symmetry. Defaults to False. use_z: Enable Z-axis symmetry. Defaults to False.

Returns: Confirmation dict with symmetry settings.

Enable dynamic topology (dyntopo) for adaptive sculpting resolution.

Dyntopo adds and removes mesh detail dynamically as you sculpt, allowing unlimited detail where needed without uniform subdivision.

Args: object_name: Name of the mesh object (must be in sculpt mode or will enter it). detail_size: Detail level (smaller = more detail). Range: 0.1-500.0. detail_mode: Detail mode. One of: RELATIVE, CONSTANT, BRUSH, MANUAL.

Returns: Confirmation dict with dyntopo settings.

Apply Smart UV Project to a mesh object.

Automatically unwraps the mesh using angle-based projection.

Args: object_name: Name of the mesh object. angle_limit: Angle limit in degrees for splitting faces (0.0-89.0). island_margin: Margin between UV islands (0.0-1.0). area_weight: Weight given to face area for island arrangement (0.0-1.0).

Returns: Confirmation dict with object name and UV map info.

Unwrap a mesh object's UVs using standard unwrap.

Requires seams to be marked for best results.

Args: object_name: Name of the mesh object. method: Unwrap method - ANGLE_BASED or CONFORMAL.

Returns: Confirmation dict with object name.

Apply a projection-based UV mapping to a mesh object.

Args: object_name: Name of the mesh object. projection: Projection type - CUBE, CYLINDER, or SPHERE.

Returns: Confirmation dict with object name and projection type.

Pack UV islands to fit efficiently within the UV space.

Args: object_name: Name of the mesh object. margin: Margin between packed islands (0.0-1.0).

Returns: Confirmation dict with object name.

Add a rigid body physics simulation to an object.

Args: object_name: Name of the object. type: Rigid body type - ACTIVE (affected by physics) or PASSIVE (static collider). mass: Mass of the object in kg. friction: Surface friction coefficient (0.0-1.0). restitution: Bounciness (0.0-1.0).

Returns: Confirmation dict with rigid body settings.

Add a cloth physics simulation to an object.

Args: object_name: Name of the mesh object. quality: Simulation quality steps (1-80). mass: Mass of the cloth in kg.

Returns: Confirmation dict with cloth settings.

Add a fluid physics simulation to an object.

Args: object_name: Name of the object. type: Fluid type - DOMAIN (container), FLOW (emitter), or EFFECTOR (obstacle). domain_type: Domain simulation type - GAS (smoke/fire) or LIQUID. Only used when type is DOMAIN.

Returns: Confirmation dict with fluid settings.

Add a particle system to an object.

Args: object_name: Name of the mesh object. count: Number of particles (max 1000000). lifetime: Particle lifetime in frames. emit_from: Emission source - VERT, FACE, or VOLUME.

Returns: Confirmation dict with particle system settings.

Set a property on an existing physics simulation.

Args: object_name: Name of the object with the physics simulation. physics_type: Physics type - RIGID_BODY, CLOTH, FLUID, or PARTICLE_SYSTEM. property: Property name to set (depends on physics type). value: Value to set.

Returns: Confirmation dict with property name and new value.

Bake a physics simulation for an object.

Args: object_name: Name of the object with physics. physics_type: Optional physics type to bake. If empty, bakes all physics on the object.

Returns: Confirmation dict.

Remove a particle system from an object.

Args: object_name: Name of the object. particle_system_name: Name of the particle system to remove. If empty, removes the first particle system.

Returns: Confirmation dict.

Set velocity settings for an object's particle system.

Args: object_name: Name of the object with a particle system. normal: Velocity along face normals. tangent: Velocity along face tangents. object_align_factor: XYZ velocity factors relative to the object. 3-element vector.

Returns: Confirmation dict.

Set rendering mode for an object's particle system.

Args: object_name: Name of the object with a particle system. render_type: Render type. One of: NONE, PATH, OBJECT, COLLECTION. instance_object: Object to instance (when render_type is OBJECT). instance_collection: Collection to instance (when render_type is COLLECTION).

Returns: Confirmation dict.

Create a Geometry Nodes modifier on an object.

Args: object_name: Name of the object to add the modifier to. name: Name for the geometry nodes modifier. Defaults to "GeometryNodes".

Returns: Dict with modifier name and node group name.

Add a node to a geometry nodes modifier's node group.

Args: modifier_name: Name of the geometry nodes modifier (used to find the node group). node_type: Blender node type identifier, e.g. GeometryNodeMeshCube, GeometryNodeSetPosition, GeometryNodeTransform, ShaderNodeMath, GeometryNodeJoinGeometry, etc. location: XY position for the node in the node editor. Defaults to (0, 0).

Returns: Dict with the created node's name and type.

Connect two nodes in a geometry nodes modifier's node group.

Args: modifier_name: Name of the geometry nodes modifier. from_node: Name of the source node. from_socket: Index of the output socket on the source node. to_node: Name of the destination node. to_socket: Index of the input socket on the destination node.

Returns: Confirmation dict with connection details.

Set an input value on a geometry nodes modifier.

Args: object_name: Name of the object with the modifier. modifier_name: Name of the geometry nodes modifier. input_name: Name of the input socket to set (as shown in the modifier panel). value: The value to set. Type depends on the input (float, int, vector, etc.).

Returns: Confirmation dict with the input name and new value.

List all available inputs on a geometry nodes modifier.

Args: object_name: Name of the object with the modifier. modifier_name: Name of the geometry nodes modifier.

Returns: List of dicts with input name, type, and current value.

Create a new armature object.

Args: name: Name for the armature. Defaults to "Armature". location: XYZ position for the armature. Defaults to origin.

Returns: Dict with the created armature's name and location.

Add a bone to an armature. Enters edit mode automatically.

Args: armature_name: Name of the armature object. bone_name: Name for the new bone. head: XYZ position of the bone head (root). Defaults to (0, 0, 0). tail: XYZ position of the bone tail (tip). Defaults to (0, 0, 1). parent_bone: Optional name of the parent bone for hierarchy.

Returns: Dict with the created bone's name, head, and tail positions.

Set a property on a bone in an armature.

Args: armature_name: Name of the armature object. bone_name: Name of the bone. property: Property to set. One of: roll, length, use_connect, use_deform, envelope_distance, head_radius, tail_radius, use_inherit_rotation, use_local_location. value: Value to set the property to.

Returns: Confirmation dict with bone name, property, and new value.

Add a constraint to an object or bone.

Args: object_name: Name of the object (armature for bone constraints). bone_name: Name of the bone (empty string for object-level constraints). constraint_type: Constraint type. One of: IK, COPY_ROTATION, COPY_LOCATION, COPY_SCALE, COPY_TRANSFORMS, TRACK_TO, DAMPED_TRACK, LOCKED_TRACK, LIMIT_ROTATION, LIMIT_LOCATION, LIMIT_SCALE, STRETCH_TO, FLOOR, CLAMP_TO, TRANSFORM, MAINTAIN_VOLUME, CHILD_OF, PIVOT, ARMATURE. properties: Optional dict of constraint properties to set (e.g., target, subtarget, chain_count, influence, etc.).

Returns: Dict with the created constraint's name and type.

Parent a mesh object to an armature with automatic weights or other methods.

Args: mesh_name: Name of the mesh object to parent. armature_name: Name of the armature object. type: Parenting method. One of: ARMATURE_AUTO (automatic weights), ARMATURE_NAME (by bone names), ARMATURE_ENVELOPE (by envelope).

Returns: Confirmation dict.

Set the pose of a bone in an armature.

Args: armature_name: Name of the armature object. bone_name: Name of the bone to pose. location: Optional XYZ location offset for the bone. rotation: Optional XYZ Euler rotation in radians. scale: Optional XYZ scale.

Returns: Confirmation dict with the bone's new pose values.

Create a new collection, optionally nested under a parent collection.

Args: name: Name for the new collection. parent: Optional name of parent collection to nest under. Empty string uses the scene's root collection.

Returns: Dict with the created collection's name and parent.

Move objects to a collection, unlinking them from their current collections.

Args: object_names: List of object names to move. collection_name: Name of the destination collection.

Returns: Dict with the moved objects and destination collection.

Set collection visibility in viewport and/or render.

Args: collection_name: Name of the collection. visible: Whether the collection should be visible. viewport: Apply visibility change to viewport. Defaults to True. render: Apply visibility change to render. Defaults to True.

Returns: Confirmation dict with visibility state.

Delete a collection.

Args: collection_name: Name of the collection to delete. delete_objects: If True, also delete all objects in the collection. If False, objects are unlinked but kept in the scene.

Returns: Confirmation dict.

Import a 3D file into Blender.

Supports FBX, OBJ, GLTF/GLB, USD, STL, PLY, Alembic (ABC), Collada (DAE), SVG, and X3D formats. Auto-detects format from file extension if type is empty.

Args: filepath: Absolute path to the file to import. Must exist. type: Optional format override. One of: FBX, OBJ, GLTF, USD, STL, PLY, ABC, DAE, SVG, X3D. Auto-detected from extension if empty.

Returns: Dict with imported file path and format.

Export scene or selected objects to a 3D file.

Supports FBX, OBJ, GLTF/GLB, USD, STL, PLY, Alembic (ABC), Collada (DAE), SVG, and X3D formats.

Args: filepath: Absolute path for the export file. type: Optional format override. Auto-detected from extension if empty. selected_only: If True, export only selected objects. Defaults to False.

Returns: Dict with exported file path and format.

Save the current Blender file.

If filepath is empty, saves to the current file path (overwrite). If filepath is provided, performs a "Save As" to the given path.

Args: filepath: Optional absolute path to save as. Must have .blend extension. Empty string saves to current file.

Returns: Dict with the saved file path.

Open a .blend file.

Args: filepath: Absolute path to the .blend file. Must exist.

Returns: Dict with the opened file path.

List recently opened files from Blender preferences.

Returns: List of file path strings.

Set the viewport shading mode.

Args: mode: Shading mode. One of: WIREFRAME, SOLID, MATERIAL, RENDERED.

Returns: Confirmation dict with the new shading mode.

Toggle a viewport overlay setting.

Args: overlay: Overlay property name. One of: show_wireframes, show_face_orientation, show_floor, show_axis_x, show_axis_y, show_axis_z, show_cursor, show_object_origins, show_relationship_lines, show_stats. enabled: Whether the overlay should be enabled.

Returns: Confirmation dict with the overlay name and state.

Frame/focus the viewport on a specific object.

Selects the object and uses View Selected to center the viewport on it.

Args: object_name: Name of the object to focus on.

Returns: Confirmation dict.

Execute Python code inside Blender's sandboxed environment.

The code runs in a restricted sandbox that blocks dangerous imports (os, subprocess, socket, etc.) and dangerous builtins (exec, eval, open). Safe Blender imports (bpy, bmesh, mathutils, math, json) are allowed.

Args: code: Python code to execute. bpy is available but must be imported.

Returns: Dict with 'output' (captured stdout) and 'success' boolean.

Capture a screenshot of the current Blender 3D viewport.

Args: max_size: Maximum size in pixels for the largest dimension (default: 1000). mode: Capture mode - 'fast' for instant viewport capture using OpenGL (default), 'full' for a complete render through the active render engine.

Returns: Dict with base64-encoded PNG image data, width, height, format, and mode.

Select, deselect or invert all geometry on a mesh.

Args: object_name: Name of the mesh object. action: One of: SELECT, DESELECT, INVERT, TOGGLE.

Returns: Dict with the counts selected afterwards.

Select specific vertices, edges or faces by index.

The deterministic way to select: no operator, no viewport, no guessing. analyze_mesh_quality reports sample indices for each defect it finds, so this is how to act on them.

Args: object_name: Name of the mesh object. element: One of: VERTEX, EDGE, FACE. indices: Indices to select. Must be non-negative and within the mesh. extend: Add to the current selection instead of replacing it.

Returns: Dict with how many elements were selected and the mesh's totals.

Select geometry on one side of the object along an axis.

The usual way to say "the top", "the front" or "the left half".

Args: object_name: Name of the mesh object. axis: One of: X, Y, Z. sign: POS for the positive side, NEG for the negative side, ALIGN for geometry lying in the plane. extend: Add to the current selection instead of replacing it.

Returns: Dict with how many elements were selected.

Grow the current selection to geometry that resembles it.

Requires something to already be selected: it compares against that.

Args: object_name: Name of the mesh object. type: What to compare. Face options: FACE_MATERIAL, FACE_AREA, FACE_SIDES, FACE_PERIMETER, FACE_NORMAL, FACE_COPLANAR, FACE_SMOOTH, FACE_FREESTYLE. Edge options: EDGE_LENGTH, EDGE_DIR, EDGE_FACES, EDGE_FACE_ANGLE, EDGE_CREASE, EDGE_BEVEL, EDGE_SEAM, EDGE_SHARP, EDGE_FREESTYLE. Vertex options: VERT_NORMAL, VERT_FACES, VERT_GROUPS, VERT_EDGES, VERT_CREASE. threshold: How close a match must be, 0.0 to 1.0.

Returns: Dict with how many elements were selected.

Select faces by how many sides they have.

The direct way to find ngons (GREATER than 4) or triangles (EQUAL to 3), which is what topology cleanup usually needs.

Args: object_name: Name of the mesh object. number: Number of sides to compare against. A face has at least 3. comparison: One of: LESS, EQUAL, GREATER, NOTEQUAL. extend: Add to the current selection instead of replacing it.

Returns: Dict with how many faces were selected.

Report what is currently selected on a mesh.

Without this a caller cannot see the result of its own selection, and the mesh tools that act on the current selection would be operating blind.

Args: object_name: Name of the mesh object.

Returns: Dict with selected and total counts per element type, and the first 50 selected indices of each, so a caller can confirm before acting.

Auto boolean union: merge two mesh objects into one.

The target object is consumed and joined into the main object. This is useful for permanently joining meshes so parts don't float away from their bodies.

Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

Args: object_name: Name of the main object to keep. target_name: Name of the object to merge into the main object.

Returns: Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

Auto boolean difference: subtract the target object from the main object.

The target object is used as a cutter and removed after the operation.

Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

Args: object_name: Name of the object to cut from. target_name: Name of the cutter object (will be removed).

Returns: Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

Auto boolean intersect: keep only the overlapping volume of two objects.

The target object is removed after the operation.

Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

Args: object_name: Name of the main object. target_name: Name of the intersecting object (will be removed).

Returns: Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

Auto boolean slice: split the main object using the target as a cutter.

Creates two separate pieces from the intersection. The target object is removed after the operation.

Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

Args: object_name: Name of the object to slice. target_name: Name of the cutter object (will be removed).

Returns: Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

Inset all faces of a mesh, creating a border/frame around each face.

Core hard-surface modeling operation for adding detail, panel lines, or preparing faces for extrusion.

On a closed mesh, selection="ALL" does nothing: a region with no boundary has nothing to inset from, and Blender reports success having changed nothing. Measured on a default cube in 5.1, the vertex, edge and face counts are identical afterwards. Select the faces you mean and pass selection="CURRENT".

Args: object_name: Name of the mesh object. thickness: Inset thickness (border width). Range: 0.0-10.0. depth: Inset depth (positive=outward, negative=inward). Range: -10.0 to 10.0.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Fill selected edges with a face.

Creates faces from a closed edge loop. Useful for closing gaps in meshes or capping open ends.

Args: object_name: Name of the mesh object.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Fill a closed edge loop with a grid of quads.

Creates a clean quad grid between edge loops. Better than fill_faces for maintaining good topology.

Args: object_name: Name of the mesh object. span: Number of grid columns. Range: 1-1000. offset: Offset for the grid alignment. Range: 0-1000.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Mark or clear UV seams on all edges of a mesh.

UV seams guide the UV unwrapping process. Edges marked as seams define where the mesh is "cut" when unwrapped to 2D.

Args: object_name: Name of the mesh object. clear: If True, clear seams instead of marking them.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Mark or clear sharp edges on a mesh.

Sharp edges control auto-smooth shading. Edges marked as sharp will have a hard edge in the shading even with smooth shading enabled.

Args: object_name: Name of the mesh object. clear: If True, clear sharp marks instead of setting them.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Recalculate face normals to be consistent (all pointing outward or inward).

Fixes meshes with flipped or inconsistent normals that cause shading artifacts.

Args: object_name: Name of the mesh object. inside: If True, normals point inward instead of outward.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Flip the direction of all face normals on a mesh.

Reverses inside/outside of all faces. Use recalculate_normals instead if normals are inconsistent rather than uniformly wrong.

Args: object_name: Name of the mesh object.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Convert all quad faces to triangles.

Useful for game engine export or when triangulated geometry is required.

Args: object_name: Name of the mesh object.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Convert adjacent triangle pairs to quad faces where possible.

Improves topology for subdivision and deformation. Not all triangles can be merged — only adjacent pairs with compatible angles.

Args: object_name: Name of the mesh object.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Dissolve all faces, merging them into surrounding geometry.

Removes faces while keeping the surrounding mesh structure intact. Cleaner than deleting faces which leaves holes.

Args: object_name: Name of the mesh object.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Dissolve all edges, merging adjacent faces.

Simplifies topology by removing unnecessary edge loops while preserving the overall shape.

Args: object_name: Name of the mesh object.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Dissolve all vertices, merging connected edges and faces.

Removes vertices while preserving surrounding geometry.

Args: object_name: Name of the mesh object.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Project a cutter object's outline onto a mesh to cut it.

The cutter object (curve or mesh) is projected from the viewport onto the target mesh, cutting new edges into it.

Args: object_name: Name of the mesh to cut into. cutter_name: Name of the cutter object (curve or mesh) to project.

Returns: Confirmation dict.

Spin (lathe) mesh geometry around an axis.

Creates rotational geometry by duplicating and rotating the selected geometry around a center point. Great for creating round shapes like vases, columns, or wheels.

Args: object_name: Name of the mesh object. angle: Total spin angle in radians. Range: -6.283 to 6.283 (full circle). steps: Number of steps in the spin. Range: 1-1000. axis: Spin axis as XYZ vector. Defaults to Z-up (0, 0, 1). center: Center point for the spin as XYZ. Defaults to origin.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Set edge crease value on all edges for subdivision surface control.

Crease values control how sharp edges remain when a Subdivision Surface modifier is applied. 0 = fully smooth, 1 = fully sharp.

Args: object_name: Name of the mesh object. value: Crease value. Range: -1.0 to 1.0.

selection: "ALL" to act on the whole mesh, or "CURRENT" to act only
    on what is already selected. Use the select_* tools to choose
    first. Defaults to "ALL".

Returns: Confirmation dict.

Select all geometry linked to the current selection.

Expands selection to include all connected vertices, edges, and faces. Useful for isolating mesh islands or selecting connected components.

Args: object_name: Name of the mesh object.

Returns: Confirmation dict.

Analyze mesh topology quality and return a structured defect report.

Checks for non-manifold edges, loose vertices, zero-area faces, duplicate vertices, and wire edges. Returns counts and sample indices (capped at 50 per category) for each defect type.

Args: object_name: Name of the mesh object to analyze.

Returns: Dict with vertex/edge/face counts, defect counts and sample indices, and an issues_found boolean.

Repair the defects analyze_mesh_quality reports.

Pairs with analyze_mesh_quality: run that first, then call this with the repairs the report calls for. Removing loose geometry and dissolving degenerate faces cannot change a well-formed mesh, so both are on by default. Filling holes creates new geometry and is opt-in.

Args: object_name: Name of the mesh object to repair. remove_loose: Delete loose vertices and wire edges, the ones reported as loose_vertex_count and wire_edge_count. dissolve_degenerate: Dissolve zero-area faces and zero-length edges, reported as zero_area_face_count. fill_holes: Close boundary loops, which reduces non_manifold_edge_count but invents geometry to do it.

Returns: Dict with the counts before and after, so the effect is visible.

Reduce a mesh's polygon count, collapsing edges to hit a target.

The counterpart to subdivision: an agent that has stacked Subdivision modifiers has otherwise no way back down, and a dense mesh slows every later operation.

Args: object_name: Name of the mesh object to simplify. ratio: Fraction of faces to keep, between 0 and 1. 0.5 halves the face count. 1.0 keeps everything and is refused as a no-op.

Returns: Dict with the face count before and after.

Create a new annotation data block.

Annotations are viewport overlays used for drawing marks, notes, and guides. Unlike Grease Pencil objects, annotations are not positioned in 3D space.

Args: name: Optional name for the annotation. Auto-generated if empty.

Returns: Dict with the created annotation's name.

Add a layer to an annotation.

Layers organize annotation strokes. Each layer can have its own blend mode, opacity, and color.

Args: annotation_name: Name of the annotation data block. layer_name: Name for the new layer.

Returns: Confirmation dict with annotation and layer names.

Remove a layer from an annotation.

Args: annotation_name: Name of the annotation data block. layer_name: Name of the layer to remove.

Returns: Confirmation dict.

Add a stroke to an annotation layer.

Creates a new stroke with the given points on the specified layer. Note: AnnotationStroke does not support per-point strength/opacity.

Args: annotation_name: Name of the annotation data block. layer_name: Name of the layer to add the stroke to. points: List of XYZ coordinates, e.g. [[0,0,0], [1,1,0], [2,0,0]]. Maximum 10000 points. pressure: Pen pressure for all points. Range: 0.0-1.0.

Returns: Confirmation dict with point count.

Set a property on an annotation stroke.

Args: annotation_name: Name of the annotation data block. layer_name: Name of the layer containing the stroke. stroke_index: Index of the stroke in the layer (0-based). property: Property to set. One of: line_width, material_index, display_mode. value: The value to set.

Returns: Confirmation dict.

Sweep a closed profile along a 3D path to make a solid tube, pipe, cable or rope.

Use this for anything that follows a route: hoses, handrails, wires, vines, tentacles, roads. It orients the profile with parallel transport, so the tube never creases or folds where the path turns vertical, and it reports whether any bend is too tight for the profile to fit around.

Args: path_points: Centreline as a list of [x, y, z] points, in order. At least 2, at most 2000. Consecutive points must differ. profile: Cross-section shape - CIRCLE, SQUARE, HEXAGON, or TRIANGLE. radius: Distance from the centreline to the furthest point of the profile, in Blender units. Must be positive. sides: Number of sides for a CIRCLE profile (3-1024). Ignored by the fixed-sided profiles. resolution: Samples generated between each pair of path points, which smooths the path with a centripetal Catmull-Rom spline. 0 uses the points exactly as given. 8-16 gives a smooth curve. twist: Total rotation of the profile about the path from start to end, in radians. Spreads evenly along the path. caps: Close both ends. Leave True for a printable solid. name: Name for the created object.

Returns: Dict with the object name, vertex and face counts, and a validity report: min_clearance_ratio (path curvature radius over profile radius at the tightest point), tightest_point, and self_intersects. A ratio below 1.0 means rings overlap inside the bend, so the result is watertight but is not a solid.

Check whether a path can carry a profile of a given radius, without building it.

Where a path's radius of curvature falls below the profile radius, the swept rings pass through each other on the inside of the bend. The result still reports as watertight and manifold with no degenerate faces, so no ordinary mesh check catches it. Call this before sweeping, or to find where an existing path needs widening.

Args: path_points: Centreline as a list of [x, y, z] points, in order. radius: Outer radius of the profile you intend to sweep. resolution: Samples between path points, matching what you will pass to sweep_profile_along_path so the check covers the same curve.

Returns: Dict with min_clearance_ratio (curvature radius over profile radius at the tightest station; below 1.0 self-intersects), tightest_index, tightest_point, self_intersects, and counts of stations below 1.0 and below 1.5. Aim for 1.5 or more for a clean surface.

Check whether a mesh will 3D print, using Blender's 3D Print Toolbox.

Catches three defects a mesh can carry while still passing analyze_mesh_quality, because each one leaves the mesh manifold, watertight and free of degenerate faces:

• Bad contiguous edges: a shell whose normals agree with each other but collectively face inward. Recalculating normals reports nothing to fix, and the slicer rejects the file as having reversed faces.

• Intersect faces: the surface passing through itself.

• Thin faces: walls thinner than the nozzle, which slice away to nothing.

It also reports shell count, zero-area faces and edges, non-flat faces, sharp edges and overhanging faces. Index lists are capped at 50 samples and can be fed straight to select_by_index to see the problem in Blender.

Requires the 3D Print Toolbox extension, which ships with Blender but is off by default. If it is disabled this returns an error saying how to enable it; suggest_extensions also reports whether it is on.

Args: object_name: Name of the mesh object to check. checks: Which checks to run - any of SOLID (non-manifold and bad contiguous edges), INTERSECT, DEGENERATE (zero faces and edges), THICKNESS, SHARP, OVERHANG, NONPLANAR. Omit or pass an empty list to run everything, which also reports shell count. Counts are only returned for checks that actually ran. overhang_angle: Overhang threshold in RADIANS. Faces steeper than this need support. 0.785 (45 degrees) is the usual FDM limit. Leave unset to keep the toolbox's current setting. min_thickness: Minimum wall thickness in Blender units. Set it to your nozzle width. Leave unset to keep the current setting. sharp_angle: Sharp-edge threshold in RADIANS. nonplanar_angle: Non-flat face threshold in RADIANS. zero_threshold: Area below which a face counts as zero-area.

Returns: Dict with a count (and sample indices) per check that ran, plus checks_run, issues_found, and print_blocking: the defects that stop a print, as opposed to overhangs and sharp edges which are advisory.