Tutorial for Linear Dimensions

The Dimension entity is the generic entity for all dimension types, but unfortunately AutoCAD is not willing to show a dimension line defined only by this dimension entity, it also needs an anonymous block which contains the dimension line shape constructed by basic DXF entities like LINE and TEXT entities, this representation is called the dimension line rendering in this documentation, beside the fact this is not a real graphical rendering. BricsCAD is a much more friendly CAD application, which do show the dimension entity without the graphical rendering as block, which was very useful for testing, because there is no documentation how to apply all the dimension style variables (more than 80). This seems to be the reason why dimension lines are rendered so differently by many CAD application.

Don’t expect to get the same rendering results by ezdxf as you get from AutoCAD, ezdxf tries to be as close to the results rendered by BricsCAD, but it is not possible to implement all the various combinations of dimension style parameters, which often affect one another.

Note

Ezdxf does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications.

Text rendering is another problem, because ezdxf has no real rendering engine. Some font properties, like the real text width, which is only available to ezdxf if the Matplotlib package is installed and may also vary slightly for different CAD applications. Without access to the Matplotlib package the text properties in ezdxf are based on an abstract monospaced font and are bigger than required by true type fonts.

Not all DIMENSION and DIMSTYLE features are supported by all DXF versions, especially DXF R12 does not support many features, but in this case the required rendering of dimension lines is an advantage, because if the application just shows the rendered block, all features which can be used in DXF R12 are displayed like linetypes, but this features will disappear if the dimension line will be edited in the CAD application. Ezdxf writes only the supported DIMVARS of the used DXF version to avoid invalid DXF files. So it is not that critical to know all the supported features of a DXF version, except for limits and tolerances, ezdxf uses the advanced features of the MTEXT entity to create limits and tolerances and therefore they are not supported (displayed) in DXF R12 files.

See also

Horizontal Dimension

import ezdxf

# Create a DXF R2010 document:
# Use argument setup=True to setup the default dimension styles.
doc = ezdxf.new("R2010", setup=True)

# Add new dimension entities to the modelspace:
msp = doc.modelspace()

# Add a LINE entity for visualization, not required to create the DIMENSION
# entity:
msp.add_line((0, 0), (3, 0))

# Add a horizontal linear DIMENSION entity:
dim = msp.add_linear_dim(
    base=(3, 2),  # location of the dimension line
    p1=(0, 0),  # 1st measurement point
    p2=(3, 0),  # 2nd measurement point
    dimstyle="EZDXF",  # default dimension style
)

# Necessary second step to create the BLOCK entity with the dimension geometry.
# Additional processing of the DIMENSION entity could happen between adding
# the entity and the rendering call.
dim.render()
doc.saveas("dim_linear_horiz.dxf")
../_images/dim_linear_horiz.png

The example above creates a horizontal Dimension entity. The default dimension style “EZDXF” is defined as:

  • 1 drawing unit = 1m
  • measurement text height = 0.25 (drawing scale = 1:100)
  • the length factor dimlfac = 100, which creates a measurement text in cm.
  • arrow is “ARCHTICK”, arrow size dimasz = 0.175

Every dimension style which does not exist will be replaced by the dimension style “Standard” at DXF export by save() or saveas() (e.g. dimension style setup was not initiated).

The base point defines the location of the dimension line, ezdxf accepts any point on the dimension line, the point p1 defines the start point of the first extension line, which also defines the first measurement point and the point p2 defines the start point of the second extension line, which also defines the second measurement point.

The return value dim is not a dimension entity, instead a DimStyleOverride object is returned, the dimension entity is stored as attribute dim.dimension.

Vertical and Rotated Dimension

Argument angle defines the angle of the dimension line in relation to the x-axis of the WCS or UCS, measurement is the distance between first and second measurement point in direction of angle.

# assignment to dim is not necessary, if no additional processing happens
msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0), angle=-30).render()
doc.saveas("dim_linear_rotated.dxf")
../_images/dim_linear_rotated.png

For a vertical dimension set argument angle to 90 degree, but in this example the vertical distance would be 0.

Aligned Dimension

An aligned dimension line is parallel to the line defined by the definition points p1 and p2. The placement of the dimension line is defined by the argument distance, which is the distance between the definition line and the dimension line. The distance of the dimension line is orthogonal to the base line in counter clockwise orientation.

msp.add_line((0, 2), (3, 0))
dim = msp.add_aligned_dim(p1=(0, 2), p2=(3, 0), distance=1)
doc.saveas("dim_linear_aligned.dxf")
../_images/dim_linear_aligned.png

Dimension Style Override

Many dimension styling options are defined by the associated DimStyle entity. But often you wanna change just a few settings without creating a new dimension style, therefore the DXF format has a protocol to store this changed settings in the dimension entity itself. This protocol is supported by ezdxf and every factory function which creates dimension entities supports the override argument. This override argument is a simple Python dictionary (e.g. override = {"dimtad": 4}, place measurement text below dimension line).

The overriding protocol is managed by the DimStyleOverride object, which is returned by the most dimension factory functions.

Placing Measurement Text

The default location of the measurement text depends on various DimStyle parameters and is applied if no user defined text location is defined.

Default Text Locations

“Horizontal direction” means in direction of the dimension line and “vertical direction” means perpendicular to the dimension line direction.

The “horizontal” location of the measurement text is defined by dimjust:

0 Center of dimension line
1 Left side of the dimension line, near first extension line
2 Right side of the dimension line, near second extension line
3 Over first extension line
4 Over second extension line
msp.add_linear_dim(
    base=(3, 2), p1=(0, 0), p2=(3, 0), override={"dimjust": 1}
).render()
../_images/dim_linear_dimjust.png

The “vertical” location of the measurement text relative to the dimension line is defined by dimtad:

0 Center, it is possible to adjust the vertical location by dimtvp
1 Above
2 Outside, handled like Above by ezdxf
3 JIS, handled like Above by ezdxf
4 Below
msp.add_linear_dim(
    base=(3, 2), p1=(0, 0), p2=(3, 0), override={"dimtad": 4}
).render()
../_images/dim_linear_dimtad.png

The distance between text and dimension line is defined by dimgap.

The DimStyleOverride object has a method set_text_align() to set the default text location in an easy way, this is also the reason for the 2 step creation process of dimension entities:

dim = msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0))
dim.set_text_align(halign="left", valign="center")
dim.render()
halign “left”, “right”, “center”, “above1”, “above2”
valign “above”, “center”, “below”

Run function example_for_all_text_placings_R2007() in the example script dimension_linear.py to create a DXF file with all text placings supported by ezdxf.

User Defined Text Locations

Beside the default location, it is possible to locate the measurement text freely.

Location Relative to Origin

The user defined text location can be set by the argument location in most dimension factory functions and always references the midpoint of the measurement text:

msp.add_linear_dim(
    base=(3, 2), p1=(3, 0), p2=(6, 0), location=(4, 4)
).render()
../_images/dim_linear_user_location_absolute.png

The location is relative to origin of the active coordinate system or WCS if no UCS is defined in the render() method, the user defined location can also be set by user_location_override().

Location Relative to Center of Dimension Line

The method set_location() has additional features for linear dimensions. Argument leader = True adds a simple leader from the measurement text to the center of the dimension line and argument relative = True places the measurement text relative to the center of the dimension line.

dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0))
dim.set_location(location=(-1, 1), leader=True, relative=True)
dim.render()
../_images/dim_linear_user_location_relative.png

Location Relative to Default Location

The method shift_text() shifts the measurement text away from the default text location. The shifting directions are aligned to the text direction, which is the direction of the dimension line in most cases, dh (for delta horizontal) shifts the text parallel to the text direction, dv (for delta vertical) shifts the text perpendicular to the text direction. This method does not support leaders.

dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0))
dim.shift_text(dh=1, dv=1)
dim.render()
../_images/dim_linear_user_location_shift.png

Overriding Text Rotation

All factory methods supporting the argument text_rotation can override the measurement text rotation. The user defined rotation is relative to the render UCS x-axis (default is WCS).

Measurement Text Formatting and Styling

Text Properties

DIMVAR Description
dimtxsty Specifies the text style of the dimension as Textstyle name.
dimtxt Text height in drawing units.
dimclrt Measurement text color as AutoCAD Color Index (ACI).
msp.add_linear_dim(
    base=(3, 2),
    p1=(3, 0),
    p2=(6, 0),
    override={
        "dimtxsty": "Standard",
        "dimtxt": 0.35,
        "dimclrt": 1,
    }
).render()
../_images/dim_linear_text.png

Background Filling

Background fillings are supported since DXF R2007, and ezdxf uses the MTEXT entity to implement this feature, so setting background filling in DXF R12 has no effect. The DIMVAR dimtfill defines the kind of background filling and the DIMVAR dimtfillclr defines the fill color.

DIMVAR Description
dimtfill Enables background filling if bigger than 0
dimtfillclr Fill color as AutoCAD Color Index (ACI), if dimtfill is 2
dimtfill Description
0 disabled
1 canvas color
2 color defined by dimtfillclr
msp.add_linear_dim(
    base=(3, 2),
    p1=(3, 0),
    p2=(6, 0),
    override={
        "dimtfill": 2,
        "dimtfillclr": 1,
    }
).render()
../_images/dim_linear_bg_filling.png

Text Formatting

  • decimal places: dimdec defines the number of decimal places displayed for the primary units of a dimension. (DXF R2000)

  • decimal point character: dimdsep defines the decimal point as ASCII code, get the ASCII code by ord('.')

  • rounding: dimrnd, 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 dimrnd is set to 1.0, all distances round to the nearest integer. For more information look at the documentation of the ezdxf.math.xround() function.

  • zero trimming: dimzin, ezdxf supports only a subset of values:

    • 4 to suppress leading zeros
    • 8 to suppress trailing zeros
    • 12 as the combination of both
  • measurement factor: scale measurement by factor dimlfac, e.g. to get the dimensioning text in cm for a DXF file where 1 drawing unit represents 1m, set dimlfac to 100.

  • text template: dimpost, “<>” represents the measurement text, e.g. “~<>cm” produces “~300cm” for measurement in previous example.

To set this values the ezdxf.entities.DimStyle.set_text_format() and ezdxf.entities.DimStyleOverride.set_text_format() methods are very recommended.

Overriding Measurement Text

This feature allows overriding the real measurement text by a custom measurement text, the text is stored as string in the Dimension entity as attribute text. Special values of the text attribute are: one space ” ” to suppress the measurement text at all, an empty string “” or “<>” to display the real measurement.

All factory functions have an explicit text argument, which always replaces the text value in the dxfattribs dict.

msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0), text=">1m").render()
../_images/dim_linear_text_override.png

Dimension Line Properties

The dimension line color is defined by the DIMVAR dimclrd as AutoCAD Color Index (ACI), dimclrd and also defines the color of the arrows. The linetype is defined by dimltype and requires DXF R2007. The lineweight is defined by dimlwd and requires DXF R2000, see also the lineweight reference for valid values. The dimdle is the extension of the dimension line beyond the extension lines, this dimension line extension is not supported for all arrows.

DIMVAR Description
dimclrd dimension line and arrows color as AutoCAD Color Index (ACI)
dimltype linetype of dimension line
dimlwd line weight of dimension line
dimdle extension of dimension line in drawing units
msp.add_linear_dim(
    base=(3, 2),
    p1=(3, 0),
    p2=(6, 0),
    override={
        "dimclrd": 1,  # red
        "dimdle": 0.25,
        "dimltype": "DASHED2",
        "dimlwd": 35,  # 0.35mm line weight
    }
).render()
../_images/dim_linear_dimline_properties.png

DimStyleOverride() method:

dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0))
dim.set_dimline_format(
    color=1, linetype="DASHED2", lineweight=35, extension=0.25
)
dim.render()

Extension Line Properties

The extension line color is defined by the DIMVAR dimclre as AutoCAD Color Index (ACI). The linetype for the first and the second extension line is defined by dimltex1 and dimltex2 and requires DXF R2007. The lineweight is defined by dimlwe and required DXF R2000, see also the lineweight reference for valid values.

The dimexe is the extension of the extension line beyond the dimension line, and dimexo defines the offset of the extension line from the measurement point.

DIMVAR Description
dimclre extension line color as AutoCAD Color Index (ACI)
dimltex1 linetype of first extension line
dimltex2 linetype of second extension line
dimlwe line weight of extension line
dimexe extension beyond dimension line in drawing units
dimexo offset of extension line from measurement point
dimfxlon set to 1 to enable fixed length extension line
dimfxl length of fixed length extension line in drawing units
dimse1 suppress first extension line if 1
dimse2 suppress second extension line if 1
msp.add_linear_dim(
    base=(3, 2),
    p1=(3, 0),
    p2=(6, 0),
    override={
        "dimclre": 1,   # red
        "dimltex1": "DASHED2",
        "dimltex2": "CENTER2",
        "dimlwe": 35,   # 0.35mm line weight
        "dimexe": 0.3,  # length above dimension line
        "dimexo": 0.1,  # offset from measurement point
    }
).render()
../_images/dim_linear_extline_properties.png

DimStyleOverride() methods:

dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0))
dim.set_extline_format(color=1, lineweight=35, extension=0.3, offset=0.1)
dim.set_extline1(linetype="DASHED2")
dim.set_extline2(linetype="CENTER2")
dim.render()

Fixed length extension lines are supported in DXF R2007, set dimfxlon to 1 and dimfxl defines the length of the extension line starting at the dimension line.

msp.add_linear_dim(
    base=(3, 2),
    p1=(3, 0),
    p2=(6, 0),
    override={
        "dimfxlon": 1,  # fixed length extension lines
        "dimexe": 0.2,  # length above dimension line
        "dimfxl": 0.4,  # length below dimension line
    }
).render()
../_images/dim_linear_extline_dimfxl.png

DimStyleOverride() method:

dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0))
dim.set_extline_format(extension=0.2, fixed_length=0.4)
dim.render()

To suppress extension lines set dimse1 to 1 to suppress the first extension line and dimse2 to 1 to suppress the second extension line.

msp.add_linear_dim(
    base=(3, 2),
    p1=(3, 0),
    p2=(6, 0),
    override={
        "dimse1": 1,  # suppress first extension line
        "dimse2": 1,  # suppress second extension line
        "dimblk": ezdxf.ARROWS.closed_filled,  # arrows just looks better
    }
).render()
../_images/dim_linear_extline_suppress.png

DimStyleOverride() methods:

dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0))
dim.set_arrows(blk=ezdxf.ARROWS.closed_filled)
dim.set_extline1(disable=True)
dim.set_extline2(disable=True)
dim.render()

Arrows

“Arrows” mark then beginning and the end of a dimension line, and most of them do not look like arrows.

DXF distinguish between the simple tick (a slanted line) and arrows as blocks.

To use a simple tick as “arrow” set dimtsz to a value greater than 0, this also disables arrow blocks as side effect:

dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0))
dim.set_tick(size=0.25)
dim.render()

Ezdxf uses the “ARCHTICK” block at double size to render the tick (AutoCAD and BricsCad just draw a simple line), so there is no advantage of using the tick instead of an arrow.

Using arrows:

dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0))
dim.set_arrow(blk="OPEN_30", size=0.25)
dim.render()
DIMVAR Description
dimtsz tick size in drawing units, set to 0 to use arrows
dimblk set both arrow block names at once
dimblk1 first arrow block name
dimblk2 second arrow block name
dimasz arrow size in drawing units
msp.add_linear_dim(
    base=(3, 2),
    p1=(3, 0),
    p2=(6, 0),
    override={
        "dimtsz": 0,  # set tick size to 0 to enable arrow usage
        "dimasz": 0.25,  # arrow size in drawing units
        "dimblk": "OPEN_30",  # arrow block name
    }
).render()

The dimension line extension (dimdle) works only for a few arrow blocks and the simple tick:

  • “ARCHTICK”
  • “OBLIQUE”
  • “NONE”
  • “SMALL”
  • “DOTSMALL”
  • “INTEGRAL”

Arrow Shapes

../_images/all_arrows.png

Arrow Names

The arrow names are stored as attributes in the ezdxf.ARROWS object.

closed_filled “” (empty string)
dot “DOT”
dot_small “DOTSMALL”
dot_blank “DOTBLANK”
origin_indicator “ORIGIN”
origin_indicator_2 “ORIGIN2”
open “OPEN”
right_angle “OPEN90”
open_30 “OPEN30”
closed “CLOSED”
dot_smallblank “SMALL”
none “NONE”
oblique “OBLIQUE”
box_filled “BOXFILLED”
box “BOXBLANK”
closed_blank “CLOSEDBLANK”
datum_triangle_filled “DATUMFILLED”
datum_triangle “DATUMBLANK”
integral “INTEGRAL”
architectural_tick “ARCHTICK”
ez_arrow “EZ_ARROW”
ez_arrow_blank “EZ_ARROW_BLANK”
ez_arrow_filled “EZ_ARROW_FILLED”

Tolerances and Limits

The tolerances and limits features are implemented by using inline codes for the MText entity, therefore DXF R2000 is required. It is not possible to use both tolerances and limits at the same time.

Tolerances

Geometrical tolerances are shown as additional text appended to the measurement text. It is recommend to use set_tolerance() method in DimStyleOverride or DimStyle.

The attribute dimtp defines the upper tolerance value, dimtm defines the lower tolerance value if present, else the lower tolerance value is the same as the upper tolerance value. Tolerance values are shown as given!

Same upper and lower tolerance value:

dim = msp.add_linear_dim(base=(0, 3), p1=(3, 0), p2=(6.5, 0))
dim.set_tolerance(.1, hfactor=.4, align="top", dec=2)
dim.render()
../_images/dim_linear_tol.png

Different upper and lower tolerance values:

dim = msp.add_linear_dim(base=(0, 3), p1=(3, 0), p2=(6.5, 0))
dim.set_tolerance(upper=.1, lower=.15, hfactor=.4, align="middle", dec=2)
dim.render()
../_images/dim_linear_tol_upr_lwr.png

The attribute dimtfac specifies a scale factor for the text height of limits and tolerance values relative to the dimension text height, as set by dimtxt. For example, if dimtfac is set to 1.0, the text height of fractions and tolerances is the same height as the dimension text. If dimtxt is set to 0.75, the text height of limits and tolerances is three-quarters the size of dimension text.

Vertical justification for tolerances is specified by dimtolj:

dimtolj Description
0 Align with bottom line of dimension text
1 Align vertical centered to dimension text
2 Align with top line of dimension text
DIMVAR Description
dimtol set to 1 to enable tolerances
dimtp set the maximum (or upper) tolerance limit for dimension text
dimtm set the minimum (or lower) tolerance limit for dimension text
dimtfac specifies a scale factor for the text height of limits and tolerance values relative to the dimension text height, as set by dimtxt.
dimtzin 4 to suppress leading zeros, 8 to suppress trailing zeros or 12 to suppress both, like dimzin for dimension text, see also Text Formatting
dimtolj set the vertical justification for tolerance values relative to the nominal dimension text.
dimtdec set the number of decimal places to display in tolerance values

Limits

The geometrical limits are shown as upper and lower measurement limit and replaces the usual measurement text. It is recommend to use set_limits() method in DimStyleOverride or DimStyle.

For limits the tolerance values are drawing units scaled by measurement factor dimlfac, the upper limit is scaled measurement value + dimtp and the lower limit is scaled measurement value - dimtm.

The attributes dimtfac, dimtzin and dimtdec have the same meaning for limits as for tolerances.

dim = msp.add_linear_dim(base=(0, 3), p1=(3, 0), p2=(6.5, 0))
dim.set_limits(upper=.1, lower=.15, hfactor=.4, dec=2)
dim.render()
../_images/dim_linear_limits.png
DIMVAR Description
dimlim set to 1 to enable limits

Alternative Units

Alternative units are not supported.