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 applications, 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 from 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 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 project, 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) 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

See also enumeration ezdxf.enums.InsertUnits.

$MEASUREMENT¶

The header variable $MEASUREMENT controls whether the current drawing uses imperial or metric hatch pattern and linetype files:

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 linetypes and hatch pattern is defined by the $MEASUREMENT value, the value of $INSUNITS is ignored.

doc.header['$MEASUREMENT'] = 1

0	English
1	Metric

See also enumeration ezdxf.enums.Measurement

$LUNITS¶

The header variable $LUNITS defines how CAD applications display 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

See also enumeration ezdxf.enums.LengthUnits

$AUNITS¶

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

doc.header['$AUNITS'] = 0

0	Decimal degrees
1	Degrees/minutes/seconds
2	Grad
3	Radians

See also enumeration ezdxf.enums.AngularUnits

Helper Tools¶

ezdxf.units.conversion_factor(source_units: InsertUnits, target_units: InsertUnits) → 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

ezdxf.units.unit_name(enum: int) → str¶: Returns the name of the unit enum.

ezdxf.units.angle_unit_name(enum: int) → str¶: Returns the name of the angle unit enum.