pydim.create_text

Creates a 2d annotation text in the model, optionally with a leader.

Similar to the Text -> Text at point / horizontal / vertical and Text -> Leader direct functions in the PYTHA user interface. Annotation texts are drawing aids — they live in one view and are not 3d objects (for those see pytha.create_text_3d). Like a dimension, a text can be anchored to a part point and then follows the part.

pydim.create_text(text, anchor [,options])

Parameter	Type	Description
text	string	The text content. An empty string creates nothing and returns nil.
anchor	{{x,y,z} [,part]}	The anchor: the coordinate at index 1 and, optionally, a part element handle at index 2 that restricts the point search to that part. The coordinate is projected into options.view to position the text. If it coincides with a part point, the text is bound to that point (see Anchoring below). Group handles are not allowed.
options	{...}	Optional: a table that may contain the following options:
options.view	string	The view in which the text is displayed: "xy", "-xy", "xz", "-xz", "yz", "-yz" or "axo" (default "axo").
options.offset	{dx,dy}	Offset of the text from the projected anchor, in object units in the plane of the view (default {0,0}). With options.leader this is where the text sits relative to the arrow tip.
options.angle	number	Rotation of the text in degrees (default 0). 0 is horizontal, 90 vertical.
options.orientation	string	The point of the text box that sits on the text position, see Orientation below (default "top_left", or the leader side if options.leader is used).
options.attached	boolean	false always creates a free text, even if the coordinate hits a part point (default true).
options.leader	boolean or {...}	true adds a leader with the current default leader values; a table additionally overrides them, see below. Without this option no leader is created.
options.style	{...}	Text appearance, see below.

Style keys (all optional; unset keys keep the value of the current 2d text defaults):

Key	Type	Description
size	number	Text height, in mm or in object units according to in_object_units.
aspect_ratio	number	Width-to-height ratio of the text (0 = font default).
width	number	Width of the text box. Setting it also switches the text to fixed width, so the content wraps inside the box. Unset, the width is derived from the string.
font	string	Font name.
pen	number	Pen of the text.
layer	number	Layer of the text (default: the working layer).
bold	boolean	true renders the text bold.
italic	boolean	true renders the text italic.
underline	boolean	true underlines the text.
in_object_units	boolean	true interprets size and width in object units instead of mm.

Leader keys (all optional; unset keys keep the current default leader values):

Key	Type	Description
pen	number	Pen of the leader.
line_type	number	Line type of the leader.
flag_length	number	Length of the horizontal flag at the text.
arrow_length	number	Length of the arrow head at the tip.

Return value

Type	Description
element_handle	An element handle of type "text" for the new text — or nil if text is empty.

Anchoring

If the anchor coordinate coincides with a point of a part (within the modelling tolerance), the text is bound to that point: it stores the offset from the point and follows the part when the part is moved or modified. Otherwise the text is created as a free text at the projected coordinate. Unlike the pydim dimension functions, a coordinate that matches no point is not an error — a free annotation text is a valid result. Use options.attached = false to force a free text.

Orientation

options.orientation names the point of the text box that sits on the text position. Only the compound forms are accepted, because the plain "left"/"center"/"right" of the 3d text and the plot text mean different rows there:

"top_left"	"top_center"	"top_right"
"middle_left"	"middle_center"	"middle_right"
"baseline_left"	"baseline_center"	"baseline_right"
"bottom_left"	"bottom_center"	"bottom_right"

Example:

local part = pytha.create_block(600, 400, 300)

-- free label above the block in the XY view
pydim.create_text("Shelf", {{300, 400, 0}},
    {view = "xy", offset = {0, 60}, orientation = "bottom_center"})

-- position number with a leader, anchored to a corner of the part
pydim.create_text("12", {{600, 400, 0}, part},
    {view = "xy",
     offset = {150, 100},
     leader = true,
     style = {size = 5, bold = true}})

Remarks:

• Annotation texts are created in the model, not on plot sheets — for sheet texts see pyplot.insert_text.
• Lua creates at most one leader per text. Further leaders can still be added interactively with Text -> Leader at text; pydim.get_text therefore reports a leader_count.
• With a leader and without an explicit options.orientation, the text box docks on the side the text sits on: "middle_left" for a positive dx, "middle_right" otherwise — the same rule the interactive leader input follows.
• The perspective view is not supported.

Version Support:

Minimum PYTHA Version: V27

See also:

pydim, pydim.get_text, pydim.update_text, pydim.delete_text, element handles, pytha.create_text_3d, pyplot.insert_text