Dimension

The DIMENSION entity (DXF Reference) represents several types of dimensions in many orientations and alignments. The basic types of dimensioning are linear, radial, angular, ordinate, and arc length.

For more information about dimensions see the online help from AutoDesk: About the Types of Dimensions

Subclass of	ezdxf.entities.DXFGraphic
DXF type	'DIMENSION'
factory function	see table below
Inherited DXF attributes	Common graphical DXF attributes

Factory Functions

Linear and Rotated Dimension (DXF)	add_linear_dim()
Aligned Dimension (DXF)	add_aligned_dim()
Angular Dimension (DXF)	add_angular_dim() (not implemented)
Angular 3P Dimension (DXF)	add_angular_3p_dim() (not implemented)
Diameter Dimension (DXF)	add_diameter_dim()
Radius Dimension (DXF)	add_radius_dim()
Ordinate Dimension (DXF)	add_ordinate_dim() (not implemented)

Warning

Do not instantiate entity classes by yourself - always use the provided factory functions!

class ezdxf.entities.Dimension

There is only one Dimension class to represent all different dimension types.

dxf.version

Version number: 0 = R2010. (int, DXF R2010)

dxf.geometry

Name of the BLOCK that contains the entities that make up the dimension picture.

For AutoCAD this graphical representation is mandatory, else AutoCAD will not open the DXF drawing. BricsCAD will render the DIMENSION entity by itself, if the graphical representation is not present, but uses the BLOCK instead of rendering, if it is present.

dxf.dimstyle

Dimension style (DimStyle) name as string.

dxf.dimtype

Values 0-6 are integer values that represent the dimension type. Values 32, 64, and 128 are bit values, which are added to the integer values.

0	Linear and Rotated Dimension (DXF)
1	Aligned Dimension (DXF)
2	Angular Dimension (DXF)
3	Diameter Dimension (DXF)
4	Radius Dimension (DXF)
5	Angular 3P Dimension (DXF)
6	Ordinate Dimension (DXF)
8	subclass ezdxf.entities.ArcDimension introduced in DXF R2004
32	Indicates that graphical representation geometry is referenced by this dimension only. (always set in DXF R13 and later)
64	Ordinate type. This is a bit value (bit 7) used only with integer value 6. If set, ordinate is X-type; if not set, ordinate is Y-type
128	This is a bit value (bit 8) added to the other dimtype values if the dimension text has been positioned at a user-defined location rather than at the default location

dxf.defpoint

Definition point for all dimension types. (3D Point in WCS)

Linear and rotated dimension: dxf.defpoint specifies the dimension line location.

Arc and angular dimension: dxf.defpoint and dxfdefpoint4 specify the endpoints of the line used to determine the second extension line.

dxf.defpoint2

Definition point for linear and angular dimensions. (3D Point in WCS)

Linear and rotated dimension: The dxf.defpoint2 specifies the start point of the first extension line.

Arc and angular dimension: The dxf.defpoint2 and dxf.defpoint3 specify the endpoints of the line used to determine the first extension line.

dxf.defpoint3

Definition point for linear and angular dimensions. (3D Point in WCS)

Linear and rotated dimension: The dxf.defpoint3 specifies the start point of the second extension line.

Arc and angular dimension: The dxf.defpoint2 and dxf.defpoint3 specify the endpoints of the line used to determine the first extension line.

dxf.defpoint4

Definition point for diameter, radius, and angular dimensions. (3D Point in WCS)

Arc and angular dimension: dxf.defpoint and dxf.defpoint4 specify the endpoints of the line used to determine the second extension line.

dxf.defpoint5

Point defining dimension arc for angular dimensions, specifies the location of the dimension line arc. (3D Point in OCS)

dxf.angle

Angle of linear and rotated dimensions in degrees. (float)

dxf.leader_length

Leader length for radius and diameter dimensions. (float)

dxf.text_midpoint

Middle point of dimension text. (3D Point in OCS)

dxf.insert

Insertion point for clones of a linear dimensions—Baseline and Continue. (3D Point in OCS)

This value is used by CAD application (Baseline and Continue) and ignored by ezdxf.

dxf.attachment_point

Text attachment point (int, DXF R2000), default value is 5.

1	Top left
2	Top center
3	Top right
4	Middle left
5	Middle center
6	Middle right
7	Bottom left
8	Bottom center
9	Bottom right

dxf.line_spacing_style

Dimension text line-spacing style (int, DXF R2000), default value is 1.

1	At least (taller characters will override)
2	Exact (taller characters will not override)

dxf.line_spacing_factor

Dimension text-line spacing factor. (float, DXF R2000)

Percentage of default (3-on-5) line spacing to be applied. Valid values range from 0.25 to 4.00.

dxf.actual_measurement

Actual measurement (float, DXF R2000), this is an optional attribute and often not present. (read-only value)

dxf.text

Dimension text explicitly entered by the user (str), default value is an empty string.

If empty string or '<>', the dimension measurement is drawn as the text, if ' ' (one blank space), the text is suppressed. Anything else is drawn as the text.

dxf.oblique_angle

Linear dimension types with an oblique angle have an optional dxf.oblique_angle.

When added to the rotation dxf.angle of the linear dimension, it gives the angle of the extension lines.

dxf.text_rotation

Defines is the rotation angle of the dimension text away from its default orientation (the direction of the dimension line). (float)

dxf.horizontal_direction

Indicates the horizontal direction for the dimension entity (float).

This attribute determines the orientation of dimension text and lines for horizontal, vertical, and rotated linear dimensions. This value is the negative of the angle in the OCS xy-plane between the dimension line and the OCS x-axis.

dimtype

dxf.dimtype without binary flags (32, 62, 128).

get_dim_style() → DimStyle

Returns the associated DimStyle entity.

get_geometry_block() → Optional[BlockLayout]

Returns BlockLayout of associated anonymous dimension block, which contains the entities that make up the dimension picture. Returns None if block name is not set or the BLOCK itself does not exist

New in version 0.10.

get_measurement() → Union[float, ezdxf.math.vector.Vector]

Returns the actual dimension measurement in WCS units, no scaling applied for linear dimensions. Returns angle in degrees for angular dimension from 2 lines and angular dimension from 3 points. Returns vector from origin to feature location for ordinate dimensions.

New in version 0.10.2.

Changed in version 0.11: Added support for angular and ordinate dimensions.

override() → DimStyleOverride

Returns the DimStyleOverride object.

New in version 0.12.

render()

Render graphical representation as anonymous block.

New in version 0.12.

transform(m: Matrix44) → Dimension

Transform DIMENSION entity by transformation matrix m inplace.

Raises NonUniformScalingError() for non uniform scaling.

New in version 0.13.

virtual_entities() → Iterable[DXFGraphic]

Yields ‘virtual’ parts of DIMENSION as basic DXF entities like LINE, ARC or TEXT.

This entities are located at the original positions, but are not stored in the entity database, have no handle and are not assigned to any layout.

New in version 0.12.

explode(target_layout: BaseLayout = None) → EntityQuery

Explode parts of DIMENSION as basic DXF entities like LINE, ARC or TEXT into target layout, if target layout is None, the target layout is the layout of the DIMENSION.

Returns an EntityQuery container with all DXF parts.

Parameters

target_layout – target layout for DXF parts, None for same layout as source entity.

New in version 0.12.

DimStyleOverride

All of the DimStyle attributes can be overridden for each Dimension entity individually.

The DimStyleOverride class manages all the complex dependencies between DimStyle and Dimension, the different features of all DXF versions and the rendering process to create the Dimension picture as BLOCK, which is required for AutoCAD.

class ezdxf.entities.DimStyleOverride

dimension

Base Dimension entity.

dimstyle

By dimension referenced DimStyle entity.

dimstyle_attribs

Contains all overridden attributes of dimension, as a dict with DimStyle attribute names as keys.

__getitem__(key: str) → Any

Returns DIMSTYLE attribute key, see also get().

__setitem__(key: str, value: Any) → None

Set DIMSTYLE attribute key in dimstyle_attribs.

__delitem__(key: str) → None

Deletes DIMSTYLE attribute key from dimstyle_attribs, ignores KeyErrors silently.

get(attribute: str, default: Any = None) → Any

Returns DIMSTYLE attribute from override dict dimstyle_attribs or base DimStyle.

Returns default value for attributes not supported by DXF R12. This is a hack to use the same algorithm to render DXF R2000 and DXF R12 DIMENSION entities. But the DXF R2000 attributes are not stored in the DXF R12 file! Does not catch invalid attributes names! Look into debug log for ignored DIMSTYLE attributes.

pop(attribute: str, default: Any = None) → Any

Returns DIMSTYLE attribute from override dict dimstyle_attribs and removes this attribute from override dict.

update(attribs: dict) → None

Update override dict dimstyle_attribs.

Parameters

attribs – dict of DIMSTYLE attributes

commit() → None

Writes overridden DIMSTYLE attributes into ACAD:DSTYLE section of XDATA of the DIMENSION entity.

get_arrow_names() → Tuple[str, str]

Get arrow names as strings like ‘ARCHTICK’.

Returns

tuple of [dimblk1, dimblk2]

Return type

Tuple[str, str]

set_arrows(blk: str = None, blk1: str = None, blk2: str = None, ldrblk: str = None, size: float = None) → None

Set arrows or user defined blocks and disable oblique stroke as tick.

Parameters

• blk – defines both arrows at once as name str or user defined block (name)

• blk1 – defines left arrow as name str or as user defined block (name)

• blk2 – defines right arrow as name str or as user defined block (name)

• ldrblk – defines leader arrow as name str or as user defined block (name)

• size – arrow size in drawing units

set_tick(size: float = 1) → None

Use oblique stroke as tick, disables arrows.

Parameters

size – arrow size in daring units

set_text_align(halign: str = None, valign: str = None, vshift: float = None) → None

Set measurement text alignment, halign defines the horizontal alignment, valign defines the vertical alignment, above1 and above2 means above extension line 1 or 2 and aligned with extension line.

Parameters

• halign – left, right, center, above1, above2, requires DXF R2000+

• valign – above, center, below

• vshift – vertical text shift, if valign is center; >0 shift upward, <0 shift downwards

set_tolerance(upper: float, lower: float = None, hfactor: float = None, align: str = None, dec: int = None, leading_zeros: bool = None, trailing_zeros: bool = None) → None

Set tolerance text format, upper and lower value, text height factor, number of decimal places or leading and trailing zero suppression.

Parameters

• upper – upper tolerance value

• lower – lower tolerance value, if None same as upper

• hfactor – tolerance text height factor in relation to the dimension text height

• align – tolerance text alignment “TOP”, “MIDDLE”, “BOTTOM”

• dec – Sets the number of decimal places displayed

• leading_zeros – suppress leading zeros for decimal dimensions if False

• trailing_zeros – suppress trailing zeros for decimal dimensions if False

set_limits(upper: float, lower: float, hfactor: float = None, dec: int = None, leading_zeros: bool = None, trailing_zeros: bool = None) → None

Set limits text format, upper and lower limit values, text height factor, number of decimal places or leading and trailing zero suppression.

Parameters

• upper – upper limit value added to measurement value

• lower – lower lower value subtracted from measurement value

• hfactor – limit text height factor in relation to the dimension text height

• dec – Sets the number of decimal places displayed, required DXF R2000+

• leading_zeros – suppress leading zeros for decimal dimensions if False, required DXF R2000+

• trailing_zeros – suppress trailing zeros for decimal dimensions if False, required DXF R2000+

set_text_format(prefix: str = '', postfix: str = '', rnd: float = None, dec: int = None, sep: str = None, leading_zeros: bool = None, trailing_zeros: bool = None) → None

Set dimension text format, like prefix and postfix string, rounding rule and number of decimal places.

Parameters

• prefix – dimension text prefix text as string

• postfix – dimension text postfix text as string

• rnd – Rounds all dimensioning distances to the specified value, for instance, if DIMRND is set to 0.25, all distances round to the nearest 0.25 unit. If you set DIMRND to 1.0, all distances round to the nearest integer.

• dec – Sets the number of decimal places displayed for the primary units of a dimension. requires DXF R2000+

• sep – “.” or “,” as decimal separator

• leading_zeros – suppress leading zeros for decimal dimensions if False

• trailing_zeros – suppress trailing zeros for decimal dimensions if False

set_dimline_format(color: int = None, linetype: str = None, lineweight: int = None, extension: float = None, disable1: bool = None, disable2: bool = None)

Set dimension line properties

Parameters

• color – color index

• linetype – linetype as string

• lineweight – line weight as int, 13 = 0.13mm, 200 = 2.00mm

• extension – extension length

• disable1 – True to suppress first part of dimension line

• disable2 – True to suppress second part of dimension line

set_extline_format(color: int = None, lineweight: int = None, extension: float = None, offset: float = None, fixed_length: float = None)

Set common extension line attributes.

Parameters

• color – color index

• lineweight – line weight as int, 13 = 0.13mm, 200 = 2.00mm

• extension – extension length above dimension line

• offset – offset from measurement point

• fixed_length – set fixed length extension line, length below the dimension line

set_extline1(linetype: str = None, disable=False)

Set extension line 1 attributes.

Parameters

• linetype – linetype for extension line 1

• disable – disable extension line 1 if True

set_extline2(linetype: str = None, disable=False)

Set extension line 2 attributes.

Parameters

• linetype – linetype for extension line 2

• disable – disable extension line 2 if True

set_text(text: str = '<>') → None

Set dimension text.

• text = ' ' to suppress dimension text

• text = '' or '<>' to use measured distance as dimension text

• else use text literally

shift_text(dh: float, dv: float) → None

Set relative text movement, implemented as user location override without leader.

Parameters

• dh – shift text in text direction

• dv – shift text perpendicular to text direction

set_location(location: Vertex, leader=False, relative=False) → None

Set text location by user, special version for linear dimensions, behaves for other dimension types like user_location_override().

Parameters

• location – user defined text location (Vertex)

• leader – create leader from text to dimension line

• relative – location is relative to default location.

user_location_override(location: Vertex) → None

Set text location by user, location is relative to the origin of the UCS defined in the render() method or WCS if the ucs argument is None.

render(ucs: UCS = None, discard=False) → BaseDimensionRenderer

Initiate dimension line rendering process and also writes overridden dimension style attributes into the DSTYLE XDATA section.

For a friendly CAD applications like BricsCAD you can discard the dimension line rendering, because it is done automatically by BricsCAD, if no dimension rendering BLOCK is available and it is likely to get better results as by ezdxf.

AutoCAD does not render DIMENSION entities automatically, so I rate AutoCAD as an unfriendly CAD application.

Parameters

• ucs – user coordinate system

• discard – discard rendering done by ezdxf (works with BricsCAD, but not with AutoCAD)

Returns

Rendering object used to render the DIMENSION entity for analytics

Return type

BaseDimensionRenderer