DXF Units

The DXF reference has no explicit information how to handle units in DXF, any information in this section is based on experiments with BricsCAD and may differ in other CAD application, BricsCAD tries to be as compatible with AutoCAD as possible. Therefore, this information should also apply to AutoCAD.

Please open an issue on github if you have any corrections or additional information about this topic.

Length Units

Any length or coordinate value in DXF is unitless in the first place, there is no unit information attached to the value. The unit information comes from the context where a DXF entity is used. The document/modelspace get the unit information from the header variable $INSUNITS, paperspace and block layouts get their unit information form the attribute units. The modelspace object has also a units property, but this value do not represent the modelspace units, this value is always set to 0 “unitless”.

Get and set document/modelspace units as enum by the Drawing property units:

import ezdxf
from ezdxf import units

doc = ezdxf.new()
# Set centimeter as document/modelspace units
doc.units = units.CM
# which is a shortcut (including validation) for
doc.header['$INSUNITS'] = units.CM

Block Units

As said each block definition can have independent units, but there is no implicit unit conversion applied, not in CAD applications and not in ezdxf.

When inserting a block reference (INSERT) into the modelspace or another block layout with different units, the scaling factor between these units must be applied explicit as scaling DXF attributes (xscale, …) of the Insert entity, e.g. modelspace in meters and block in centimeters, x-, y- and z-scaling has to be 0.01:

doc.units = units.M
my_block = doc.blocks.new('MYBLOCK')
my_block.units = units.CM
block_ref = msp.add_block_ref('MYBLOCK')
# Set uniform scaling for x-, y- and z-axis
block_ref.set_scale(0.01)

Use helper function conversion_factor() to calculate the scaling factor between units:

factor = units.conversion_factor(doc.units, my_block.units)
# factor = 100 for 1m is 100cm
# scaling factor = 1 / factor
block_ref.set_scale(1.0/factor)

Hint

It is never a good idea to use different measurement system in one document, ask the NASA about their Mars Climate Orbiter from 1999. The same applies for units of the same measurement system, just use one unit like meters or inches.

Angle Units

Angles are always in degrees (360 deg = full circle) and in counter clockwise orientation, unless stated explicit otherwise.

Display Format

How values are shown in the CAD GUI is controlled by the header variables $LUNITS and $AUNITS, but this has no meaning for values stored in DXF files.

$INSUNITS

The most important setting is the header variable $INSUNITS, this variable defines the drawing units for the modelspace and therefore for the DXF document if no further settings are applied.

The modelspace LAYOUT entity has a property units as any layout like object, but it seem to have no meaning for the modelspace, BricsCAD set this property always to 0, which means unitless.

The most common units are 6 for meters and 1 for inches.

doc.header['$INSUNITS'] = 6

0

Unitless

1

Inches, units.IN

2

Feet, units.FT

3

Miles, units.MI

4

Millimeters, units.MM

5

Centimeters, units.CM

6

Meters, units.M

7

Kilometers, units.KM

8

Microinches

9

Mils

10

Yards, units.YD

11

Angstroms

12

Nanometers

13

Microns

14

Decimeters, units.DM

15

Decameters

16

Hectometers

17

Gigameters

18

Astronomical units

19

Light years

20

Parsecs

21

US Survey Feet

22

US Survey Inch

23

US Survey Yard

24

US Survey Mile

$MEASUREMENT

The header variable $MEASUREMENT controls whether the current drawing uses imperial or metric hatch pattern and linetype files, this setting is not applied correct in ezdxf yet, but will be fixed in the future:

This setting is independent from $INSUNITS, it is possible to set the drawing units to inch and use metric linetypes and hatch pattern.

In BricsCAD the base scaling of the linetypes is only depending from the $MEASUREMENT value, is not relevant if $INSUNITS is meter, centimeter, millimeter, … and so on and the same is valid for hatch pattern.

doc.header['$MEASUREMENT'] = 1

0

English

1

Metric

$LUNITS

The header variable $LUNITS defines how CAD applications show linear values in the GUI and has no meaning for ezdxf:

doc.header['$LUNITS'] = 2

1

Scientific

2

Decimal (default)

3

Engineering

4

Architectural

5

Fractional

$AUNITS

The header variable $AUNITS defines how CAD applications show angular values in the GUI and has no meaning for ezdxf, DXF angles are always degrees in counter-clockwise orientation, unless stated explicit otherwise:

doc.header['$AUNITS'] = 0

0

Decimal degrees

1

Degrees/minutes/seconds

2

Grad

3

Radians

Helper Tools

ezdxf.units.conversion_factor(source_units: int, target_units: int) → float

Returns the conversion factor to represent source_units in target_units.

E.g. millimeter in centimeter conversion_factor(MM, CM) returns 0.1, because 1 mm = 0.1 cm