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
Important
The DIMENSION entity is reused to create dimensional constraints, such
entities do not have an associated geometrical block nor a dimension type
group code (2) and reside on layer *ADSK_CONSTRAINTS
.
Use property Dimension.is_dimensional_constraint
to check for this
objects. Dimensional constraints are not documented in the DXF reference and
not supported by ezdxf.
See also
Subclass of |
|
DXF type |
|
factory function |
see table below |
Inherited DXF attributes |
Factory Functions¶
Angular Dimension by center, radius, angles |
|
Angular Dimension by ConstructionArc |
|
|
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.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
1
2
3
4
5
6
8
subclass
ezdxf.entities.ArcDimension
introduced in DXF R200432
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
anddxfdefpoint4
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
anddxf.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
anddxf.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
anddxf.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.insert¶
Insertion point for clones of a linear dimensions. (3D Point in OCS)
This value translates the content of the associated anonymous block for cloned linear dimensions, similar to the
insert
attribute of theInsert
entity.
- 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
to4.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.
- property dimtype: int¶
dxf.dimtype
without binary flags (32, 62, 128).
- property is_dimensional_constraint: bool¶
Returns
True
if the DIMENSION entity is a dimensional constrains object.
- get_geometry_block() Optional[BlockLayout] ¶
Returns
BlockLayout
of associated anonymous dimension block, which contains the entities that make up the dimension picture. ReturnsNone
if block name is not set or the BLOCK itself does not exist
- get_measurement() Union[float, Vec3] ¶
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.
- override() DimStyleOverride ¶
Returns the
DimStyleOverride
object.
- render() None ¶
Render graphical representation as anonymous block.
- transform(m: Matrix44) Dimension ¶
Transform the DIMENSION entity by transformation matrix m inplace.
Raises
NonUniformScalingError()
for non uniform scaling.
- 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.
- 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 primitives.- Parameters
target_layout – target layout for DXF parts,
None
for same layout as source entity.
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¶
-
- dimstyle_attribs¶
Contains all overridden attributes of
dimension
, as adict
withDimStyle
attribute names as keys.
- __setitem__(key: str, value: Any) None ¶
Set DIMSTYLE attribute key in
dimstyle_attribs
.
- __delitem__(key: str) None ¶
Deletes DIMSTYLE attribute key from
dimstyle_attribs
, ignoresKeyErrors
silently.
- get(attribute: str, default: Optional[Any] = None) Any ¶
Returns DIMSTYLE attribute from override dict
dimstyle_attribs
or baseDimStyle
.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: Optional[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: Optional[str] = None, blk1: Optional[str] = None, blk2: Optional[str] = None, ldrblk: Optional[str] = None, size: Optional[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
blk1 – defines left arrow as name str or as user defined block
blk2 – defines right arrow as name str or as user defined block
ldrblk – defines leader arrow as name str or as user defined block
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: Optional[str] = None, valign: Optional[str] = None, vshift: Optional[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: Optional[float] = None, hfactor: Optional[float] = None, align: Optional[MTextLineAlignment] = None, dec: Optional[int] = None, leading_zeros: Optional[bool] = None, trailing_zeros: Optional[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 enum
ezdxf.enums.MTextLineAlignment
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
Changed in version 0.17.2: argument align as enum
ezdxf.enums.MTextLineAlignment
- set_limits(upper: float, lower: float, hfactor: Optional[float] = None, dec: Optional[int] = None, leading_zeros: Optional[bool] = None, trailing_zeros: Optional[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: Optional[float] = None, dec: Optional[int] = None, sep: Optional[str] = None, leading_zeros: Optional[bool] = None, trailing_zeros: Optional[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: Optional[int] = None, linetype: Optional[str] = None, lineweight: Optional[int] = None, extension: Optional[float] = None, disable1: Optional[bool] = None, disable2: Optional[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: Optional[int] = None, lineweight: Optional[int] = None, extension: Optional[float] = None, offset: Optional[float] = None, fixed_length: Optional[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: Optional[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: Optional[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: UVec, 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: UVec) 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 isNone
.
- 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 tolerated by AutoCAD)
- Returns
Rendering object used to render the DIMENSION entity for analytics
- Return type
BaseDimensionRenderer