Skip to main content
Glama

print_export

DestructiveIdempotent

Exports a structure as aligned, watertight STL files, one per colour group, for multi-colour 3D printing.

Instructions

Exports a structure as watertight STL files ready for multi-colour 3D printing.

Each colour group becomes one STL file. PyMOL's exporters write the whole visible scene, so each group is isolated on its own before export, then rebuilt into a watertight solid. Every STL is written in PyMOL model coordinates (Å, the numbers get_coords reports) whatever the camera view, so groups from one call, or from separate calls, line up; the camera is left as it was. A slicer can load them as aligned multi-material parts (e.g. add the second STL as a "part" of the first in Bambu Studio).

representation="displayed" prints what PyMOL shows, sticks and spheres included; "cartoon" keeps to cartoon and surface triangles and names what it left out. A group keeps every separate piece (two chains that do not touch print as two pieces) unless bodies="largest". The voxel method's growth of about 0.62 voxel per surface is undone unless undo_voxel_growth=False, but gaps narrower than about 2.5 voxels fuse while voxelising and cannot be reopened: a clearance needs voxel_pitch <= gap / 2.5.

STL has no units and slicers read it as millimetres, so mm_per_angstrom sets the print size. The result gives each part's size in mm and warns about any part small enough for a slicer to take for inches and enlarge 25.4x.

Requires the optional print extra (trimesh, pymeshlab, manifold3d); see the install hint returned if the libraries are missing.

Input Schema

NameRequiredDescriptionDefault
bodiesNo"all" (default) keeps every separate piece of a group, e.g. both dimers of 4hhb's ribbon or all four hemes, and the result says it prints as N pieces. "largest" keeps only the biggest piece and reports what it dropped, with a WARNING when that is over 1% of the volume. Either way enclosed cavities are filled and stray fragments under 8 faces removed.all
groupsYesSemicolon-separated ``label=selection`` pairs, one per colour. Example: "protein=polymer.protein; nucleic=polymer.nucleic". In cartoon and displayed modes each group names whole objects, e.g. "barrel=(barrel or barrel_spine)".
methodNo"auto" (light cleanup if the export is already watertight apart from stray fragments, else poisson with voxel fallback), "poisson" (keeps detail, best for bulky surfaces; cannot merge sticks and spheres), or "voxel" (robust for thin cartoons, tubes and nucleic acids).auto
out_dirNoDirectory for the STL files (default: current directory)..
obj_nameYesPyMOL object the groups are taken from (e.g. "1abc"); the STL files are named after it.
voxel_pitchNoVoxel size in Ångström for the voxel method; it stays in Å whatever mm_per_angstrom is. Use about one third of the thinnest feature you need to keep: 0.7 keeps a ~10 Å helix, print_ribbon_view ribbons want 0.2, thin rods 0.1. The result warns when a displayed cartoon feature is under 3 voxels across. Halving it costs about 5x the time.
poisson_depthNoScreened-Poisson octree depth; higher = more detail.
representationNoWhat geometry to export. "surface" (default) isolates each group as its own temporary object and exports its molecular surface. "cartoon" exports the cartoon and surface triangles the group's objects *display*, keeping per-residue rep flags and per-object cartoon type (e.g. a `cartoon tube` spine from print_ribbon_view); it leaves out sticks, spheres, lines and dashes and names what it left out. "displayed" exports everything PyMOL draws for the group's objects: those triangles plus sticks, spheres, lines, ribbon and distance dashes (as solid rods), merged exactly. In cartoon and displayed modes groups are isolated by object visibility, so each group names whole object(s), one colour per object (e.g. "1abc or 1abc_spine"); name measurement and CGO objects in the group too.surface
mm_per_angstromNoPrint scale in millimetres per Ångström. 1.0 (default) prints 1 Å as 1 mm; 3.0 makes a 40 Å protein 120 mm across. Applied after repair to every group about the same origin, so the parts stay aligned; voxel_pitch stays in Å. Raise it when the result warns that a part is small enough for a slicer to mistake it for inches.
undo_voxel_growthNoVoxel method only: move every surface back in by 0.62 x voxel_pitch, the amount voxelising grows it (a 0.33 Å rod came out 0.38 Å at 0.1 Å pitch). Default true. Gaps narrower than about 2.5 x voxel_pitch fuse while voxelising and cannot be reopened, so where a clearance matters use voxel_pitch <= gap / 2.5.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv1.5.2
    • addedInput schema / properties / bodies
      Added value: +{
      +  "default": "all",
      +  "description": "\"all\" (default) keeps every separate piece of a group, e.g. both dimers of 4hhb's ribbon or all four hemes, and the result says it prints as N pieces. \"largest\" keeps only the biggest piece and reports what it dropped, with a WARNING when that is over 1% of the volume. Either way enclosed cavities are filled and stray fragments under 8 faces removed.",
      +  "title": "Bodies",
      +  "type": "string"
      +}
    • changedInput schema / properties / groups / description
      Previous value: -"Semicolon-separated ``label=selection`` pairs, one per colour. Example: \"protein=polymer.protein; nucleic=polymer.nucleic\"."New value: +"Semicolon-separated ``label=selection`` pairs, one per colour. Example: \"protein=polymer.protein; nucleic=polymer.nucleic\". In cartoon and displayed modes each group names whole objects, e.g. \"barrel=(barrel or barrel_spine)\"."
    • changedInput schema / properties / method / description
      Previous value: -"\"auto\" (light cleanup if the export is already watertight, else poisson with voxel fallback), \"poisson\" (keeps detail, best for bulky chains), or \"voxel\" (robust for thin nucleic acids)."New value: +"\"auto\" (light cleanup if the export is already watertight apart from stray fragments, else poisson with voxel fallback), \"poisson\" (keeps detail, best for bulky surfaces; cannot merge sticks and spheres), or \"voxel\" (robust for thin cartoons, tubes and nucleic acids)."
    • addedInput schema / properties / mm_per_angstrom
      Added value: +{
      +  "default": 1,
      +  "description": "Print scale in millimetres per Ångström. 1.0 (default) prints 1 Å as 1 mm; 3.0 makes a 40 Å protein 120 mm across. Applied after repair to every group about the same origin, so the parts stay aligned; voxel_pitch stays in Å. Raise it when the result warns that a part is small enough for a slicer to mistake it for inches.",
      +  "title": "Mm Per Angstrom",
      +  "type": "number"
      +}
    • changedInput schema / properties / obj_name / description
      Previous value: -"PyMOL object to export (e.g. \"1abc\")."New value: +"PyMOL object the groups are taken from (e.g. \"1abc\"); the STL files are named after it."
    • changedInput schema / properties / representation / description
      Previous value: -"What geometry to export. \"surface\" (default, unchanged) isolates each group as its own temp object and exports its molecular surface. \"cartoon\" exports the *currently displayed* cartoon geometry of the real objects, preserving per-residue rep flags and per-object cartoon type (e.g. a `cartoon tube` spine from :func:`print_ribbon_view`). In cartoon mode each group must name whole object(s) — one colour per object (e.g. \"1abc or 1abc_spine\") — and groups are isolated by toggling object visibility, no temp objects."New value: +"What geometry to export. \"surface\" (default) isolates each group as its own temporary object and exports its molecular surface. \"cartoon\" exports the cartoon and surface triangles the group's objects *display*, keeping per-residue rep flags and per-object cartoon type (e.g. a `cartoon tube` spine from print_ribbon_view); it leaves out sticks, spheres, lines and dashes and names what it left out. \"displayed\" exports everything PyMOL draws for the group's objects: those triangles plus sticks, spheres, lines, ribbon and distance dashes (as solid rods), merged exactly. In cartoon and displayed modes groups are isolated by object visibility, so each group names whole object(s), one colour per object (e.g. \"1abc or 1abc_spine\"); name measurement and CGO objects in the group too."
    • addedInput schema / properties / undo_voxel_growth
      Added value: +{
      +  "default": true,
      +  "description": "Voxel method only: move every surface back in by 0.62 x voxel_pitch, the amount voxelising grows it (a 0.33 Å rod came out 0.38 Å at 0.1 Å pitch). Default true. Gaps narrower than about 2.5 x voxel_pitch fuse while voxelising and cannot be reopened, so where a clearance matters use voxel_pitch <= gap / 2.5.",
      +  "title": "Undo Voxel Growth",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / voxel_pitch / description
      Previous value: -"Voxel size in Angstrom for the voxel method. Smaller keeps more detail; 0.7 keeps a ~10 A helix intact."New value: +"Voxel size in Ångström for the voxel method; it stays in Å whatever mm_per_angstrom is. Use about one third of the thinnest feature you need to keep: 0.7 keeps a ~10 Å helix, print_ribbon_view ribbons want 0.2, thin rods 0.1. The result warns when a displayed cartoon feature is under 3 voxels across. Halving it costs about 5x the time."
  2. Changed7 schema fields changedv1.5.1
    • addedInput schema / properties / groups / description
      Added value: +"Semicolon-separated ``label=selection`` pairs, one per colour. Example: \"protein=polymer.protein; nucleic=polymer.nucleic\"."
    • addedInput schema / properties / method / description
      Added value: +"\"auto\" (light cleanup if the export is already watertight, else poisson with voxel fallback), \"poisson\" (keeps detail, best for bulky chains), or \"voxel\" (robust for thin nucleic acids)."
    • addedInput schema / properties / obj_name / description
      Added value: +"PyMOL object to export (e.g. \"1abc\")."
    • addedInput schema / properties / out_dir / description
      Added value: +"Directory for the STL files (default: current directory)."
    • addedInput schema / properties / poisson_depth / description
      Added value: +"Screened-Poisson octree depth; higher = more detail."
    • addedInput schema / properties / representation / description
      Added value: +"What geometry to export. \"surface\" (default, unchanged) isolates each group as its own temp object and exports its molecular surface. \"cartoon\" exports the *currently displayed* cartoon geometry of the real objects, preserving per-residue rep flags and per-object cartoon type (e.g. a `cartoon tube` spine from :func:`print_ribbon_view`). In cartoon mode each group must name whole object(s) — one colour per object (e.g. \"1abc or 1abc_spine\") — and groups are isolated by toggling object visibility, no temp objects."
    • addedInput schema / properties / voxel_pitch / description
      Added value: +"Voxel size in Angstrom for the voxel method. Smaller keeps more detail; 0.7 keeps a ~10 A helix intact."
  3. First observedv1.2.1

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations flag destructiveHint and non-readOnly, and the description supplies the operational detail behind that: files are written to out_dir, each colour group becomes its own isolated-and-rebuilt STL, coordinates stay in PyMOL model Å regardless of camera view, and the camera is left untouched. It also discloses the optional dependency (trimesh, pymeshlab, manifold3d), the install-hint failure mode, and that results include per-part mm sizes and size warnings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and each paragraph covers a distinct concern (grouping, representation, bodies, voxel behaviour, scale, dependencies). It is longer than typical and overlaps noticeably with the schema's own parameter descriptions, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, an output schema, and annotations already in place, the description fills the remaining gaps an agent needs: model-space alignment across calls, the watertight-rebuild caveats, physical units/slicer behaviour, and library prerequisites. Nothing material for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already well documented. The description's parameter commentary (voxel growth of 0.62 voxel, the 2.5-voxel fusion limit, mm_per_angstrom scaling) largely restates what the schema fields say, and repeated content earns no additional credit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource — exporting a structure as watertight STL files — plus the target use case (multi-colour 3D printing). Nothing else in the sibling list (save, png, ray, draw) produces printable multi-material STL output, so an agent can identify it immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives conditional guidance for choosing modes: 'displayed' for PyMOL-visible sticks/spheres, 'cartoon' for cartoon and surface triangles, bodies='largest' to drop extra pieces, and a clearance rule (voxel_pitch <= gap / 2.5). It does not explicitly name alternative tools (e.g. save) for non-printing exports, so the when-not-to-use case is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.