Dimension Controller

3D dimension annotations on the model.

Domain of dimension elements as first-class objects in the model: their creation on a defined plane, the points they measure, their formatting and orientation, and visualisation options such as overall dimensions. Distinct from shop-drawing dimensions, which are produced as part of 2D output.

`add_segment(element_id: ElementId, segment: point_3d) -> None`

Adds a new point to a dimension's point list. A dimension segment is automatically created between this point and the previous point. This method can be called multiple times to progressively add more measurement points to the dimension.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required
`segment`	`point_3d`	The point to add to the dimension (despite the parameter name, this is a point, not a segment).	required

`create_dimension(xl: point_3d, plane_normal: point_3d, distance: point_3d, dimension_points: list[point_3d]) -> ElementId`

Creates a dimension element to measure distances on 3D parts. The dimension is drawn on a plane defined by its normal and offset distance. Points added to the dimension are projected onto this plane, and dimension segments are automatically created between consecutive points.

Parameters:

Name	Type	Description	Default
`xl`	`point_3d`	The direction vector defining the dimension line axis (the direction of the measurement arrow). Can be aligned with X, Y, Z axes or any 3D direction.	required
`plane_normal`	`point_3d`	The normal vector defining the orientation of the dimension plane.	required
`distance`	`point_3d`	The offset vector from the dimensioned geometry to where the dimension line is drawn. Can offset in any direction.	required
`dimension_points`	`list[point_3d]`	A list of dimension points to measure. At least 2 points are needed for a valid dimension measurement, but the points can be added later using addSegment(). Points are projected onto the dimension plane.	required

Examples:

>>> import cadwork
>>> import dimension_controller as dc

>>> # Create a list of dimension points
>>> list_points = []
>>> list_points.append(cadwork.point_3d(0., 0., 0.))
>>> list_points.append(cadwork.point_3d(1000., 0., 0.))
>>> list_points.append(cadwork.point_3d(2000., 500., 0.))
>>> list_points.append(cadwork.point_3d(3000., 200., 0.))
>>> list_points.append(cadwork.point_3d(4000., 360., 0.))
>>> list_points.append(cadwork.point_3d(6000., 451., 0.))

>>> # Create the dimension element
>>> id_dimension = dc.create_dimension(
>>>     cadwork.point_3d(1., 0., 0.),  # xl - dimension arrow direction
>>>     cadwork.point_3d(0., 1., 0.),  # plane_normal
>>>     cadwork.point_3d(0., 0., 500.),  # distance - offset from geometry
>>>     list_points  # dimension_points
>>> )

Returns:

Type	Description
`ElementId`	The element id of the created dimension element.

`get_default_anchor_length(element_id: ElementId) -> float`

Gets the default anchor length.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`float`	The default anchor length.

`get_dimension_base_format(element_id: ElementId) -> dimension_base_format`

Get the dimension base format.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`dimension_base_format`	The format used for the dimension. Enum value `None` may indicate that something went wrong while retrieving the value due to e.g. the element not being a valid dimension.

`get_dimension_points(element_id: ElementId) -> list[point_3d]`

Gets all dimension points ordered by dimension direction.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`list[point_3d]`	A list of dimension points.

`get_distance(element_id: ElementId) -> point_3d`

Get the distance to the dimension reference point. The point is in the plane of the dimensioning.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`point_3d`	The distance vector.

`get_plane_normal(element_id: ElementId) -> point_3d`

Get the plane normal.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`point_3d`	The plane normal vector.

`get_plane_xl(element_id: ElementId) -> point_3d`

Get the plane x direction.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`point_3d`	The plane x direction vector.

`get_segment_count(element_id: ElementId) -> int`

Get count of segments.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`int`	The number of segments.

`get_segment_direction(element_id: ElementId, segment_index: int) -> point_3d`

Get the normalized direction from the anchor point to the point on the dimension.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required
`segment_index`	`int`	The segment index.	required

Returns:

Type	Description
`point_3d`	The segment direction vector.

`get_segment_distance(element_id: ElementId, segment_index: int) -> float`

Get the distance from the anchor point to the dimension segment.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required
`segment_index`	`int`	The segment index.	required

Returns:

Type	Description
`float`	The distance from the anchor point to the dimension segment.

`get_total_dimension(element_id: ElementId) -> bool`

Query whether the visualisation of the overall dimension is set for a dimension element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`bool`	True if the visualisation is set, false otherwise. For elements that are not of type dimension, the return value is per default false.

`set_default_anchor_length(element_id_list: list[ElementId], length: float) -> None`

Sets the default anchor length of a dimension element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`length`	`float`	The default anchor length to set.	required

`set_distance(element_id_list: list[ElementId], distance: point_3d) -> None`

Sets the distance vector between the points and the line.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`distance`	`point_3d`	The distance vector to set.	required

`set_line_color(element_id_list: list[ElementId], color_id: ColorId) -> None`

Sets the line color of a dimension element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`color_id`	`ColorId`	The color id to set.	required

`set_line_thickness(element_id_list: list[ElementId], thickness: float) -> None`

Sets the line thickness of a dimension element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`thickness`	`float`	The line thickness to set.	required

`set_orientation(element_id_list: list[ElementId], view_dir: point_3d, view_dir_up: point_3d) -> None`

Sets the orientation of dimension elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`view_dir`	`point_3d`	The view direction vector.	required
`view_dir_up`	`point_3d`	The view direction up vector.	required

`set_precision(element_id_list: list[ElementId], precision: UnsignedInt) -> None`

Sets the precision/decimal places of a dimension element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`precision`	`UnsignedInt`	The precision/decimal places to set.	required

`set_text_color(element_id_list: list[ElementId], color_id: ColorId) -> None`

Sets the text color of a dimension element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`color_id`	`ColorId`	The color id to set.	required

`set_text_size(element_id_list: list[ElementId], text_size: float) -> None`

Sets the text size of a dimension element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`text_size`	`float`	The text size to set.	required

`set_total_dimension(element_id_list: list[ElementId], total: bool) -> None`

Set whether the visualisation of the overall dimension is set for a dimension element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`total`	`bool`	True if the visualisation is set, false otherwise.	required

`shift_distance_and_texts(element_id_list: list[ElementId], shifted: bool) -> None`

Sets if distance and texts are shifted.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`shifted`	`bool`	True if distance and texts are shifted, false otherwise.	required