pydim.create_linear_dimension

Creates a linear dimension between two part points in the model.

Similar to the Dimensions -> Horizontal / Vertical / Parallel functions in the PYTHA user interface. The dimension is anchored to existing part points and follows the parts when they are modified.

pydim.create_linear_dimension(point1, point2 [,options])

Parameter	Type	Description
point1	{{x,y,z} [,element]}	First dimension point: the coordinate at index 1 and, optionally, a part or group element handle at index 2. The coordinate must coincide with an existing point; reference points take priority over part points, a group handle only matches the group's reference points (see pydim).
point2	{{x,y,z} [,element]}	Second dimension point, same form as point1.
options	{...}	Optional: a table that may contain the following options:
options.type	string	Dimension type: "horizontal", "vertical" or "parallel" (default "parallel").
options.view	string	The view in which the dimension is displayed: "xy", "-xy", "xz", "-xz", "yz", "-yz" or "axo" (default "axo").
options.distance	number	Signed distance of the dimension line from point1, measured along the extension lines. The sign selects the side (default 0).
options.plane	string	Axo view only: the plane the dimension lies in: "xy", "xz" or "yz".
options.axis	string	Axo "parallel" dimensions only: the axis the dimension line is parallel to: "x", "y" or "z". options.plane must contain this axis; the second axis of the plane becomes the extension line direction.
options.saw_angle	boolean	true additionally shows the saw angle (like Dimensions -> Parallel+Saw angle).
options.style_file	path handle	A dimension style file (as saved from the dimension attributes dialog) loaded as the base style, e.g. from pyio.get_plugin_folder_path.
options.style	{...}	Individual style settings applied on top, see below.

Style keys (all optional; unset keys keep the value of the current default dimension style or of options.style_file):

Key	Type	Description
decimals	number	Number of decimals of the dimension value.
text_pen	number	Pen of the dimension text.
line_pen	number	Pen of the dimension line.
extension_pen	number	Pen of the extension lines.
delimiter_pen	number	Pen of the delimiters.
delimiter	string	Delimiter type: "arrow", "stroke", "circle" or "none".
delimiter_size	number	Delimiter size.
extension_style	string	Extension line style: "free", "length" or "distance".
extension_value	number	Length resp. distance value for extension_style.
extension_line_type	number	Line type of the extension lines.
no_extension_lines	boolean	true suppresses the extension lines.
text_position	string	Position of the text relative to the dimension line: "top", "middle" or "bottom".
text_distance	number	Distance of the text from the dimension line.
architecture_notation	boolean	true uses architecture notation.
tolerance_plus	number	Plus tolerance shown with the value.
tolerance_minus	number	Minus tolerance shown with the value.
leading_text	string	Text placed before the value.
trailing_text	string	Text placed after the value.
subtext	string	Text placed below the value.
diameter	boolean	true prefixes the value with the diameter sign.
font	string	Font name of the dimension text.
text_height	number	Text height.
text_ratio	number	Width-to-height ratio of the text (0 = font default).
bold	boolean	true renders the text bold.
italic	boolean	true renders the text italic.
layer	number	Layer of the dimension.
in_object_units	boolean	true interprets the size values in object units instead of mm.

Return value

Type	Description
element_handle	An element handle of type "dimension" for the new dimension — or nil if one of the coordinates does not match a part point or the dimension value would be 0.

Example:

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

-- length of the block in the XY view, dimension line 50 mm below the part
pydim.create_linear_dimension(
    {{0, 0, 0}, part},
    {{600, 0, 0}, part},
    {type = "horizontal", view = "xy", distance = -50})

-- height of the block in the axo view, dimension line parallel to the z axis
pydim.create_linear_dimension(
    {{600, 0, 0}, part},
    {{600, 0, 300}, part},
    {type = "parallel", view = "axo", axis = "z", plane = "xz", distance = 100})

With a style file shipped in the plugin folder and individual overrides:

local stil = pyio.get_plugin_folder_path("resource/annotation.txt")
pydim.create_linear_dimension(
    {{850, 200, 0}}, {{1150, 200, 0}},
    {type = "horizontal", view = "xy", distance = -250,
     style_file = stil,
     style = {decimals = 1, diameter = true, text_height = 5}})

Remarks:

• 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" require options.plane; "parallel" requires options.axis and options.plane.
• Dimensions are created in the model, not on plot sheets.
• The function will raise an error on invalid option combinations (e.g. an axo dimension without options.plane).

Version Support:

Minimum PYTHA Version: V27

See also:

pydim, element handles, Path Handles, get_plugin_folder_path, delete_element