Skip to content

pydim

Jump to bottom
fabian-flassig edited this page Aug 25, 2026 · 2 revisions

The pydim.* api functions create the annotations of the PYTHA model programmatically — the dimensions a user creates with the Dimensions functions, and the 2d texts and leaders of the Text functions in the PYTHA user interface.

Dimension functions:

Annotation text functions:

Dimension points

Dimensions in PYTHA are anchored to part points or reference points, not to free coordinates: when the element is modified, its dimensions follow. pydim therefore expects coordinates that coincide with an existing point. Each dimension point is given as a table with the coordinate at index 1 and, optionally, a part or group element handle at index 2 that restricts the point search to that element:

{ {x, y, z} }           -- searched everywhere
{ {x, y, z}, part }     -- searched only in this part
{ {x, y, z}, group }    -- searched only among this group's reference points

The search resolves the coordinate in this order:

  1. Part reference points (of the given part, or of all parts)
  2. Group reference points (only without a part handle)
  3. Plain part points

Reference points always take priority over plain part points. A group handle only matches the group's reference points — groups have no plain points. If a coordinate does not match any point, no dimension is created and the function returns nil.

Edges

pydim.create_angular_dimension and pydim.create_perpendicular_dimension reference part edges. An edge is given as two dimension-point tables for its end coordinates; the coordinates are resolved to the part edge that connects them (the order of the two ends does not matter). An edge always lies completely within one part, so if both end points carry a part handle, it must be the same part. Edges connect plain part points only — group handles and reference points cannot describe an edge.

Dimension types and views

Every dimension belongs to one view and is displayed in that view only ("xy", "xz", "yz", their flipped counterparts, or "axo").

  • In the plane views, "horizontal" measures along the horizontal axis of the view, "vertical" along the vertical axis, and "parallel" along the connection of the two dimension points.
  • In the axo view, "horizontal" and "vertical" additionally need the plane the dimension lies in. A "parallel" dimension in the axo view is axis-parallel: it needs the axis the dimension line is parallel to and the plane it is projected into.

Dimension styles

A new dimension uses the current default dimension style (Environment -> Settings -> Dimension). Both can be overridden per dimension:

  • style_file — a path handle to a dimension style file (as saved from the dimension attributes dialog) that is loaded as the base style.
  • style — a table with individual style settings (pens, delimiters, text, tolerances, ...) applied on top.

Annotation texts

2d annotation texts are drawing aids, not 3d objects — they live in one view like a dimension does and are typically used for labels such as position numbers. For 3d text see pytha.create_text_3d, for texts on a plot sheet pyplot.insert_text.

The anchor of a text has the same form as a dimension point, but is resolved more leniently: a coordinate that hits a part point binds the text to that point so it follows the part, while a coordinate that matches no point simply yields a free text instead of an error.

A leader is a property of its text: pydim.create_text creates at most one leader together with the text, pydim.update_text changes or removes it, and pydim.delete_text deletes it with the text. There is no separate leader handle. A user can still attach further leaders interactively, so pydim.get_text reports a leader_count.

See also:

pytha, pyplot, Element Handles, Path Handles, pytha.create_text_3d, pyplot.insert_text

Clone this wiki locally