Documentation / generated/blender-operations.md
Core 11629ae · View or edit Markdown on GitHub ↗

Blender operation reference

Generated from the current declarations. Do not edit this file by hand.

Types, limits and defaults below describe resolved values. Runtime expressions must produce these types. Unknown options are rejected; defaults apply only when omitted. Constructor options must be constant after document composition.

Index#

applyTransform, array, assignMaterial, bend, bevel, boolean, cone, cube, curveFromCSV, cylinder, decimate, disk, grid, icoSphere, join, lathe, material, mirror, plane, polylineTube, readGltf, readPLY, readSTL, shadeSmooth, shrinkwrap, smooth, solidify, subdivision, torus, transform, triangulate, twist, uvSphere, voxelRemesh, weightedNormal, weld, wireframe

applyTransform#

Bakes the input object's world transform (location, rotation and scale from centre, cube size or transform) into the vertex coordinates of a copy and resets the object transform to identity. The world-space shape is unchanged, but later modifiers then act on world-sized geometry about the world origin. Insert it before bevel, solidify, voxelRemesh, bend, twist or mirror when their sizes, axes or planes must refer to world units.

Common mistakes and assumptions:

• It does not move anything visibly; compare modifier results with and without it when proportions look wrong.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: applyTransform. Output kind: ["data"].

Options: none.

array#

Repeats the input mesh count times in one new mesh with Blender's Array modifier, each copy offset by relativeOffset times the input's bounding-box size along each local axis (relative offset on, constant offset and vertex merging off, as in a new Blender modifier). Use it for regular rows of blades, fins, bolts or test specimens.

Common mistakes and assumptions:

• count includes the original; count 1 produces no copies.
• Copies touching at relativeOffset 1 are not merged; add weld if they must be connected.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: array. Output kind: ["data"].

assignMaterial#

Copies the evaluated input mesh (with its world transform) and replaces all of its material slots with the single material input on every face. The upstream object and its materials stay unchanged, so the same geometry can be styled differently for several presentations. Use it for imported or processed meshes, which have no material input of their own.

Common mistakes and assumptions:

• Per-face material assignments from join or imports are lost; every face gets this material.

Native binding: assignMaterial. Output kind: ["data"].

Options: none.

bend#

Bends a copy of the input mesh with Blender's Simple Deform modifier in Bend mode: the mesh is curved about the selected local axis by a total angle in radians spread over the mesh's extent. Other Simple Deform settings keep Blender's defaults (no origin object, full 0 to 1 limits), so the deformation is centred on the input object's local origin. Give the input enough vertices along the bend (subdivision method SIMPLE or grid) for a smooth curve.

Common mistakes and assumptions:

• angle is in radians, not degrees (1.5708 is a right-angle bend).
• A cube or plane has too few vertices to bend smoothly; subdivide first.
• Bending acts in local coordinates; bake transform scaling with applyTransform first when proportions matter.

Native binding: bend. Output kind: ["data"].

bevel#

Rounds or chamfers the edges of a copy of the input mesh with a Blender Bevel modifier (affect: edges) and produces a new mesh object with the input's world transform; the input object is unchanged. width and segments are assigned; the other Bevel settings keep Blender's new-modifier values, so width is the Offset of the new edges from the original edge and only edges whose faces meet more sharply than the 30 degree angle limit are bevelled. Follow it with shadeSmooth and weightedNormal for clean hard-surface shading.

Common mistakes and assumptions:

• width is in the input's local units; after cube or transform scaling the world bevel is larger or smaller. Use applyTransform before bevel to work in world units.
• Gently curved regions (faces meeting at less than 30 degrees) are not bevelled by the native angle limit.

Native binding: bevel. Output kind: ["data"].

boolean#

Combines the input mesh with a second mesh, the operand, using Blender's Boolean modifier with the Exact solver: DIFFERENCE cuts the operand away, UNION merges both volumes and INTERSECT keeps only the overlap. The result is a new mesh object; the operand is unchanged and is rendered only if listed as visible. Use it for holes, cut-aways and section views.

Common mistakes and assumptions:

• Both meshes should be closed, consistently oriented volumes; open sheets give unreliable results (solidify them first).
• Coplanar faces are handled by the Exact solver but are slow on dense meshes; offset the operand slightly when possible.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: boolean. Output kind: ["data"].

cone#

Creates a capped cone or frustum about the local Z axis with Blender's bmesh cone generator: radius at the lower (-Z) end, tipRadius at the upper (+Z) end and depth as the full height, centred on centre. A tipRadius of 0 gives a pointed cone; a positive tipRadius gives a frustum such as a nozzle or diffuser section.

Common mistakes and assumptions:

• To point the tip downwards, rotate with transform (for example rotation [180, 0, 0]) rather than swapping radii.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: cone. Output kind: ["data"].

cube#

Creates a closed six-face cube mesh object with edge length size, centred on centre, using the material input. Schemaxis builds a fixed mesh spanning -1 to 1 on each local axis and realises size as the object's scale (size/2 on every axis) and centre as its location. Choose it for boxes, test parts and bevelled enclosures; for a non-cubic box follow it with transform scale, and use uvSphere, cylinder or the other primitives for other shapes.

Common mistakes and assumptions:

• Downstream modifiers (bevel width, solidify thickness, voxelSize, weld distance) act on the -1..1 local mesh, so they scale with size; insert applyTransform first when they must be in world units.
• This is the operation in the recorded native qualification cases (signed volume 8 for size 2 and 27 for size 3).

Native binding: cube. Output kind: ["data"].

curveFromCSV#

Reads point coordinates from named columns of a numeric CSV table and sweeps the same round tube as polylineTube along them (rows in file order, 2 to 1024 rows). With zColumn empty the curve is planar at z = 0. The file is copied into the run directory and its SHA-256 digest is checked, so a measured or simulated trajectory becomes a reproducible presentation mesh.

Common mistakes and assumptions:

• Every cell of the CSV, including unused columns, must be a finite number under a UTF-8 header row; text columns fail with INVALID_TABLE.
• Coordinates are used as Blender units without conversion; rescale with transform if the table is in millimetres.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: curveFromCSV. Output kind: ["data"].

• file is a constructor option.

cylinder#

Creates a closed, capped polygonal cylinder about the local Z axis with Blender's bmesh cone generator using the same radius at both ends; depth is the full height, centred on centre. The ends are single n-gon caps. Use cone for tapered sections and lathe for arbitrary axisymmetric profiles.

Common mistakes and assumptions:

• The axis is always local Z; use transform rotation to align it with another axis.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: cylinder. Output kind: ["data"].

decimate#

Reduces the polygon count of a copy of the input mesh with Blender's Decimate modifier in its default Collapse mode, keeping approximately ratio of the triangles. Use it to lighten heavy imports or remeshed surfaces for rendering or publication; geometric detail and sharp edges can be lost.

Common mistakes and assumptions:

• The Schemaxis default ratio 0.5 halves the triangles even when you only wanted to add the node; set 1 to keep everything.
• Do not use decimated geometry for measurements that need the original surface.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: decimate. Output kind: ["data"].

disk#

Creates a flat circular disk as one polygon whose segments vertices lie on a circle of the given radius in the local XY plane, centred on centre, with its normal along +Z. The polygon is inscribed in the circle, so its area is slightly smaller than pi r squared at low segment counts. Use it for end plates, markers and backdrops; use grid or subdivision when the face needs interior vertices.

Common mistakes and assumptions:

• The single n-gon has no interior vertices, so deforming it with bend or twist has little effect.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: disk. Output kind: ["data"].

grid#

Creates a flat rectangular grid of xSegments by ySegments quads in the local XY plane (z = 0), width along X and height along Y, centred on centre, with face normals along +Z. It is a single-sided surface with no thickness; choose it over plane when later deformation (bend, twist, shrinkwrap, smooth) needs interior vertices.

Common mistakes and assumptions:

• Add solidify when the grid must have a thickness or a closed volume.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: grid. Output kind: ["data"].

icoSphere#

Creates a closed sphere mesh by recursively subdividing an icosahedron with Blender's bmesh generator, giving near-uniform triangles with vertices on the given radius about centre. Choose it over uvSphere when even triangle size matters (wire cages, remeshing, deformation); subdivisions grows the face count by a factor of four per level.

Common mistakes and assumptions:

• Like uvSphere, the mesh is inscribed in the true sphere and slightly undersized in volume.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: icoSphere. Output kind: ["data"].

join#

Combines the evaluated geometry of two or more mesh nodes into one mesh in world coordinates (the result has an identity transform), keeping each face's material and smooth flag. It only gathers faces: overlapping parts remain separate intersecting shells, unlike a boolean UNION. Follow with weld to fuse touching seams or voxelRemesh to fuse overlaps into one surface.

Common mistakes and assumptions:

• UV maps, vertex groups, custom attributes and custom normals are not preserved.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: join. Output kind: ["data"].

Options: none.

lathe#

Revolves a [radius, height] profile a full turn about the local Z axis to create a surface of revolution (vessels, nozzles, knobs), with optional flat caps at the first and last profile points. Schemaxis generates the quad mesh itself from the profile and segments, then applies the material, centre and smoothShading. Choose it when the shape is axisymmetric; use cylinder or cone for constant or linearly tapering sections.

Common mistakes and assumptions:

• Radii must be positive and heights must strictly increase; violations fail with INVALID_PROFILE at the profile's authored location during planning whenever the values are known host-side (literals, axes, times, expressions), and again when Blender builds the mesh; profiles that read native observations are checked only when Blender runs.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: lathe. Output kind: ["data"].

material#

Creates a Blender material whose Principled BSDF shader inputs are set from the options: colour drives Base Color and Alpha, and the other options drive Roughness, Metallic, IOR, Transmission Weight, Coat Weight, Coat Roughness, Emission Color and Emission Strength. It produces a material resource, not geometry: every primitive needs one through its material input, and assignMaterial applies one to any processed or imported mesh. Every option has a Schemaxis default that is always assigned and read back from the shader, so an empty options object gives a mid-rough, non-metallic blue surface.

Common mistakes and assumptions:

• A material cannot be listed in a scene's visible or meshes; list the mesh that uses it.
• A material that no selected mesh references is pruned and never created, so it is absent from the saved scene.
• Colour values are linear shader values from 0 to 1, not sRGB hex codes; the PNG passes through Blender's colour management.
• Mesh publications (scene meshes) are STL files, which do not carry materials.

Native binding: material. Output kind: ["material"].

Inputs: none.

mirror#

Adds the reflection of a copy of the input mesh across the selected local axis planes with Blender's Mirror modifier; the planes pass through the input object's local origin, and merge welds vertices that land on the mirror plane (Blender's 0.001 merge distance). Use it to model one half or quarter of a symmetric part and complete it.

Common mistakes and assumptions:

• Primitives have their origin at centre, so mirroring a whole primitive overlaps it with itself; model only one side of the plane.
• To mirror about a world plane after transform, insert applyTransform so the local origin is the world origin.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: mirror. Output kind: ["data"].

plane#

Creates a single rectangular quad of width (local X) by height (local Y) in the XY plane, centred on centre, with its normal along +Z. Use it for floors, backdrops and cutting or wrapping sheets; choose grid instead when the surface will be deformed, because a plane has only four vertices.

Common mistakes and assumptions:

• A plane has no thickness; add solidify before boolean or STL publication that needs a closed solid.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: plane. Output kind: ["data"].

polylineTube#

Sweeps a round tube of the given radius along straight segments between explicit 3D points, using a temporary native Blender POLY curve with a bevel that is converted to mesh and then discarded. Points are in the node's local coordinates and centre moves the whole tube. Choose it for pipes, wires, streamline-like paths or trajectories you can list inline; use curveFromCSV when the points come from a table.

Common mistakes and assumptions:

• Consecutive duplicate points create zero-length segments and fail with INVALID_GEOMETRY.
• A closed tube needs at least three points.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: polylineTube. Output kind: ["data"].

readGltf#

Imports exactly one mesh object from a glTF 2.0 JSON file (.gltf) with Blender's glTF importer at its default settings; buffers and images must be embedded as data: URIs. Other imported objects are deleted, the mesh is unparented with its world transform kept, and imported materials stay on it. Use it to bring ParaView scene exports or other verified glTF artifacts into Blender; use readSTL or readPLY for those formats.

Common mistakes and assumptions:

• Binary .glb files, external .bin or image files, and documents with more than one mesh fail with UNSUPPORTED_RESOURCE.
• glTF is a Y-up, metre-based format; the freecad-to-blender example applies transform rotation [-90, 0, 0] and scale 0.001 to restore a millimetre CAD part exported by ParaView.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: readGltf. Output kind: ["data"].

Inputs: none.

• file is a constructor option.

readPLY#

Imports one polygon mesh from a PLY file with Blender's PLY importer, multiplying coordinates by scale and keeping the file's axes (Y forward, Z up, scene units ignored); other importer options keep Blender's defaults. PLY carries no unit information, so scale converts units. Point-only PLY files are rejected because the mesh must have faces.

Common mistakes and assumptions:

• A point cloud PLY fails with UNSUPPORTED_RESOURCE; mesh it elsewhere first.
• scale is a constant set at creation; it cannot vary with an $axis.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: readPLY. Output kind: ["data"].

Inputs: none.

• file is a constructor option.
• scale is a constructor option.

readSTL#

Imports one triangle mesh from an STL file with Blender's STL importer, multiplying coordinates by scale and keeping the file's axes (Y forward, Z up, scene units ignored). STL carries no unit information, so scale is how you convert: 0.001 turns a millimetre CAD export into metre-sized Blender units. The file is copied into the run directory and its digest checked.

Common mistakes and assumptions:

• The file must produce exactly one mesh object with faces; otherwise UNSUPPORTED_RESOURCE.
• scale is a constant set at creation; it cannot vary with an $axis. Use transform for varying scale.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: readSTL. Output kind: ["data"].

Inputs: none.

• file is a constructor option.
• scale is a constructor option.

shadeSmooth#

Copies the input mesh and sets every face to smooth (enabled true) or flat (enabled false) shading. Smooth shading interpolates normals across faces so tessellated curved surfaces render without facets; positions and topology are unchanged. Use subdivision or smooth when the geometry itself must change.

Common mistakes and assumptions:

• Smooth shading on hard-edged parts creates dark gradients; follow with weightedNormal or bevel the edges.
• STL publications do not carry shading flags.

Native binding: shadeSmooth. Output kind: ["data"].

shrinkwrap#

Moves each vertex of a copy of the input mesh onto the surface of a second mesh, the target, using Blender's Shrinkwrap modifier with its default Nearest Surface Point method; mode decides how vertices may sit relative to the target and offset keeps a gap. Use it to drape a patch, label or coating onto another shape. The target is not changed and is rendered only if it is listed as visible.

Common mistakes and assumptions:

• The input needs enough vertices to follow curvature; subdivide a plane before wrapping.
• Both meshes must be graph nodes; the target is resolved through its own transform in world space.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: shrinkwrap. Output kind: ["data"].

smooth#

Relaxes vertex positions of a copy of the input mesh with Blender's Smooth modifier, moving each vertex towards its neighbours by factor for a number of iterations on all three axes; topology is unchanged. Use it to soften noisy scans or faceted imports. Repeated smoothing shrinks the shape and rounds corners.

Common mistakes and assumptions:

• A cube or other low-vertex mesh collapses quickly; subdivide first or use shadeSmooth when only the shading should look smooth.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: smooth. Output kind: ["data"].

solidify#

Gives a copy of the input surface a uniform shell thickness with Blender's Solidify modifier (Simple extrusion mode, rims on); offset places the shell inside, centred on or outside the original surface relative to its normals. Use it to turn sheets (plane, grid, wrapped or imported surfaces) into closed panels or shells that can be rendered with thickness, published as solid STL or used in boolean.

Common mistakes and assumptions:

• thickness is in the input's local units; a scaled input yields a different world thickness.
• Inconsistent face normals make the shell grow in different directions; check normals of imported meshes.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: solidify. Output kind: ["data"].

subdivision#

Subdivides a copy of the input mesh with Blender's Subdivision Surface modifier; Schemaxis sets the same level for viewport and render evaluation, so images, saved scenes and STL publications agree. CATMULL_CLARK smooths and rounds the shape; SIMPLE only adds vertices and keeps the shape, which is the usual preparation for bend, twist, shrinkwrap or smooth.

Common mistakes and assumptions:

• Each level multiplies the face count by about four; level 4 on a detailed import can be very large.
• CATMULL_CLARK shrinks sharp shapes such as a cube towards a rounded blob; add bevel first or use SIMPLE.

Native binding: subdivision. Output kind: ["data"].

torus#

Creates a closed ring (torus) of quads lying in the local XY plane around the local Z axis: majorRadius is the distance from centre to the middle of the tube and minorRadius is the tube radius. majorSegments divides the ring and minorSegments divides the tube cross-section. Use it for O-rings, seals and annular markers.

Common mistakes and assumptions:

• Keep minorRadius below majorRadius; otherwise the tube passes through the axis and the surface self-intersects.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: torus. Output kind: ["data"].

transform#

Places a copy of the input mesh by composing translation, rotation (XYZ Euler, degrees) and scale on top of the input object's world transform: world = T * R * S * input. Scale and rotation therefore act about the world origin, not the part's own centre. The mesh vertices are not changed; only the object transform is, so later modifiers still work in the original local coordinates unless you add applyTransform.

Common mistakes and assumptions:

• A part centred away from the origin moves when scaled or rotated; translate it to the origin first or apply the transform before it is offset.
• Rotation is in degrees here, whereas bend and twist angles are radians.

Native binding: transform. Output kind: ["data"].

triangulate#

Splits every quad and n-gon of a copy of the input mesh into triangles with Blender's Triangulate modifier at its default settings (quads along the shortest diagonal, n-gons by the Beauty method). Use it before wireframe for a triangle cage or to control how polygons are split before export; it has no options.

Common mistakes and assumptions:

• STL publication triangulates anyway; add this node only when the triangle layout itself matters.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: triangulate. Output kind: ["data"].

Options: none.

twist#

Twists a copy of the input mesh with Blender's Simple Deform modifier in Twist mode: cross-sections rotate about the selected local axis, accumulating the total angle (radians) over the mesh's extent along that axis, about the input object's local origin. Use it for twisted blades, helical shapes or parametric sweeps (the angle may be an $axis value). Subdivide the input along the axis first so the twist is resolved.

Common mistakes and assumptions:

• angle is in radians (6.2832 is one full turn).
• Without intermediate vertices along the axis the faces only shear between the end loops.

Native binding: twist. Output kind: ["data"].

uvSphere#

Creates a closed sphere mesh with Blender's bmesh UV-sphere generator: segments meridians around the local Z axis and rings latitude bands between the poles, all vertices on the given radius about centre. Faces crowd towards the poles; choose icoSphere for evenly sized triangles, for example before voxelRemesh or wireframe.

Common mistakes and assumptions:

• The mesh is inscribed in the true sphere, so its volume is below 4/3 pi r cubed; raise segments and rings when volume or silhouette accuracy matters.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: uvSphere. Output kind: ["data"].

voxelRemesh#

Rebuilds a copy of the input mesh as a new surface from a voxelised volume using Blender's Remesh modifier in Voxel mode. The result is a single quad-dominant surface; overlapping joined parts fuse into one shell (a 'voxel union') and features smaller than voxelSize are lost. Schemaxis first rejects requests whose estimated bounding grid exceeds 8 million cells (RESOURCE_BUDGET_EXCEEDED).

Common mistakes and assumptions:

• voxelSize is in the input's local units; on a scaled object (cube size, transform scale) the world voxel size differs. Use applyTransform first.
• The input should enclose a volume; open sheets produce thin or unexpected shells.
• Topology, vertex count and fine detail change; do not use the result for dimensional checks finer than the voxel size.

Native binding: voxelRemesh. Output kind: ["data"].

weightedNormal#

Recomputes the shading normals of a copy of the input mesh with Blender's Weighted Normal modifier (native face area weighting), so large flat faces stay visually flat next to small bevel faces. It changes only the normals used for shading and rendering; vertex positions and topology are unchanged. Typical chain: bevel, shadeSmooth, weightedNormal.

Common mistakes and assumptions:

• STL mesh publications discard normals, so the effect appears only in rendered images and the saved scene.
• This operation does not repair topology or holes.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: weightedNormal. Output kind: ["data"].

weld#

Merges vertices of a copy of the input mesh that lie closer than distance, using Blender's Weld modifier in its default All mode. Use it after join, imports or array copies to fuse coincident seams so the surface becomes connected (important before solidify, smooth or STL publication of a watertight part). It removes duplicate vertices only; it does not fill gaps wider than distance.

Common mistakes and assumptions:

• distance is in the input's local units; a value close to real feature sizes collapses small details.
• The adaptor's recorded native qualification cases cover only a material on a cube; this operation relies on repository examples, not on a recorded qualification case.

Native binding: weld. Output kind: ["data"].

wireframe#

Turns every edge of a copy of the input mesh into a solid strut of the given thickness using Blender's Wireframe modifier; replace removes the original faces and boundary also builds struts along open edges. Use it to show a mesh's tessellation or to create lattice-like presentation geometry; triangulate first for a triangle cage.

Common mistakes and assumptions:

• A triangle wireframe shows tessellation, not physical structure such as flow features.
• thickness is in the input's local units and is scaled by the input object's transform.

Native binding: wireframe. Output kind: ["data"].