What is ezdxf

ezdxf is a Python interface to the DXF (drawing interchange file) format developed by Autodesk, ezdxf allows developers to read and modify existing DXF drawings or create new DXF drawings.

The main objective in the development of ezdxf was to hide complex DXF details from the programmer but still support most capabilities of the DXF format. Nevertheless, a basic understanding of the DXF format is required, also to understand which tasks and goals are possible to accomplish by using the DXF format.

Not all DXF features are supported yet, but additional features will be added in the future gradually.

ezdxf is also a replacement for my dxfwrite and my dxfgrabber packages but with different APIs, for more information see also: What is the Relationship between ezdxf, dxfwrite and dxfgrabber?

What ezdxf can’t do

Supported Python Versions

ezdxf requires at least Python 3.7 and will be tested with the latest stable CPython version and the latest stable release of pypy3 during development.

ezdxf is written in pure Python with optional Cython implementations of some low level math classes and requires only pyparser and typing_extensions as additional library beside the Python Standard Library. pytest is required to run the unit and integration tests. Data to run the stress and audit test can not be provided, because I don’t have the rights for publishing this DXF files.

Supported Operating Systems

ezdxf is OS independent and runs on all platforms which provide an appropriate Python interpreter (>=3.7).

Supported DXF Versions

ezdxf also reads older DXF versions but saves it as DXF R12.

Embedded DXF Information of 3rd Party Applications

The DXF format allows third-party applications to embed application-specific information. ezdxf manages DXF data in a structure-preserving form, but for the price of large memory requirement. Because of this, processing of DXF information of third-party applications is possible and will retained on rewriting.

License

ezdxf is licensed under the very liberal MIT-License.

Basic Installation

The most common case is the installation by pip3 including the optional C-extensions from PyPI as binary wheels:

pip3 install ezdxf

Installation with Extras

To use all features of the drawing add-on, add the [draw] tag:

pip3 install ezdxf[draw]

Binary Wheels

Ezdxf includes some C-extensions, which will be deployed automatically at each release to PyPI as binary wheels to PyPI:

The wheels are created by the continuous integration (CI) service provided by GitHub and the build container cibuildwheel provided by PyPA the Python Packaging Authority. The workflows are kept short and simple, so my future me will understand what’s going on and they are maybe also helpful for other developers which do not touch CI services every day.

The C-extensions are disabled for pypy3, because the JIT compiled code of pypy is much faster than the compiled C-extensions for pypy.

Disable C-Extensions

It is possible to disable the C-Extensions by setting the environment variable EZDXF_DISABLE_C_EXT to 1 or true:

set EZDXF_DISABLE_C_EXT=1

or on Linux:

export EZDXF_DISABLE_C_EXT=1

This is has to be done before anything from ezdxf is imported! If you are working in an interactive environment, you have to restart the interpreter.

Installation from GitHub

Install the latest development version by pip3 from GitHub:

pip3 install git+https://github.com/mozman/ezdxf.git@master

Build and Install from Source

This is only required if you want the compiled C-extensions, the ezdxf installation by pip from the source code package works without the C-extension but is slower. There are many binary wheels including the compiles C-extensions available on PyPi.

Windows 10

Make a build directory and a virtual environment:

mkdir build
cd build
py -m venv py310
py310/Scripts/activate.bat

A working C++ compiler setup is required to compile the C-extensions from source code. Windows users need the build tools from Microsoft: https://visualstudio.microsoft.com/de/downloads/

Download and install the required Visual Studio Installer of the community edition and choose the option: Visual Studio Build Tools 20..

Install required packages to build and install ezdxf with C-extensions:

pip3 install setuptools wheel cython

Clone the GitHub repository:

git clone https://github.com/mozman/ezdxf.git

Build and install ezdxf from source code:

cd ezdxf
pip3 install .

Check if the installation was successful:

python3 -m ezdxf -V

The ezdxf command should run without a preceding python3 -m, but calling the launcher through the interpreter guarantees to call the version which was installed in the venv if there exist a global installation of ezdxf like in my case.

The output should look like this:

ezdxf 0.17.2b4 from D:\Source\build\py310\lib\site-packages\ezdxf
Python version: 3.10.1 (tags/v3.10.1:2cd268a, Dec  6 2021, 19:10:37) [MSC v.1929 64 bit (AMD64)]
using C-extensions: yes
using Matplotlib: no

To install optional packages go to section: Install Optional Packages

To run the included tests go to section: Run the Tests

WSL & Ubuntu

I use sometimes the Windows Subsystem for Linux (WSL) with Ubuntu 20.04 LTS for some tests (how to install WSL).

By doing as fresh install on WSL & Ubuntu, I encountered an additional requirement, the build-essential package adds the required C++ support:

sudo apt install build-essential

The system Python 3 interpreter has the version 3.8, but I will show in a later section how to install an additional newer Python version from the source code:

cd ~
mkdir build
cd build
python3 -m venv py38
source py38/bin/activate

Install Cython and wheel in the venv to get the C-extensions compiled:

pip3 install cython wheel

Clone the GitHub repository:

git clone https://github.com/mozman/ezdxf.git

Build and install ezdxf from source code:

cd ezdxf
pip3 install .

Check if the installation was successful:

python3 -m ezdxf -V

The output should look like this:

ezdxf 0.17.2b4 from /home/mozman/src/py38/lib/python3.8/site-packages/ezdxf
Python version: 3.8.10 (default, Nov 26 2021, 20:14:08)
[GCC 9.3.0]
using C-extensions: yes
using Matplotlib: no

To install optional packages go to section: Install Optional Packages

To run the included tests go to section: Run the Tests

Raspberry Pi OS

Testing platform is a Raspberry Pi 400 and the OS is the Raspberry Pi OS which runs on 64bit hardware but is a 32bit OS. The system Python 3 interpreter comes in version 3.7, but I will show in a later section how to install an additional newer Python version from the source code.

Install the build requirements, Matplotlib and the PyQt5 bindings from the distribution repository:

sudo apt install python3-pip python3-matplotlib python3-pyqt5

Installing Matplotlib and the PyQt5 bindings by pip from piwheels in the venv worked, but the packages showed errors at import, seems to be an packaging error in the required numpy package. PySide6 is the preferred Qt binding but wasn’t available on Raspberry Pi OS at the time of writing this - PyQt5 is supported as fallback.

Create the venv with access to the system site-packages for using Matplotlib and the Qt bindings from the system installation:

cd ~
mkdir build
cd build
python3 -m venv --system-site-packages py37
source py37/bin/activate

Install Cython and wheel in the venv to get the C-extensions compiled:

pip3 install cython wheel

Clone the GitHub repository:

git clone https://github.com/mozman/ezdxf.git

Build and install ezdxf from source code:

cd ezdxf
pip3 install .

Check if the installation was successful:

python3 -m ezdxf -V

The output should look like this:

ezdxf 0.17.2b4 from /home/pi/src/py37/lib/python3.7/site-packages/ezdxf
Python version: 3.7.3 (default, Jan 22 2021, 20:04:44)
[GCC 8.3.0]
using C-extensions: yes
using Matplotlib: yes

To run the included tests go to section: Run the Tests

Manjaro on Raspberry Pi

Because the (very well working) Raspberry Pi OS is only a 32bit OS, I searched for a 64bit alternative like Ubuntu, which just switched to version 21.10 and always freezes at the installation process! So I tried Manjaro as rolling release, which I used prior in a virtual machine and wasn’t really happy, because there is always something to update. Anyway the distribution looks really nice and has Python 3.9.9 installed.

Install build requirements and optional packages by the system packager pacman:

sudo pacman -S python-pip python-matplotlib python-pyqt5

Create and activate the venv:

cd ~
mkdir build
cd build
python3 -m venv --system-site-packages py39
source py39/bin/activate

The rest is the same procedure as for the Raspberry Pi OS:

pip3 install cython wheel
git clone https://github.com/mozman/ezdxf.git
cd ezdxf
pip3 install .
python3 -m ezdxf -V

To run the included tests go to section: Run the Tests

Ubuntu Server 21.10 on Raspberry Pi

I gave the Ubuntu Server 21.10 a chance after the desktop version failed to install by a nasty bug and it worked well. The distribution comes with Python 3.9.4 and after installing some requirements:

sudo apt install build-essential python3-pip python3.9-venv

The remaining process is like on WSL & Ubuntu except for the newer Python version. Installing Matplotlib by pip works as expected and is maybe useful even on a headless server OS to create SVG and PNG from DXF files. PySide6 is not available by pip and the installation of PyQt5 starts from the source code package which I stopped because this already didn’t finished on Manjaro, but the installation of the PyQt5 bindings by apt works:

sudo apt install python3-pyqt5

Use the --system-site-packages option for creating the venv to get access to the PyQt5 package.

Install Optional Packages

Install the optional dependencies by pip only for Windows 10 and WSL & Ubuntu, for Raspberry Pi OS and Manjaro on Raspberry Pi install these packages by the system packager:

pip3 install matplotlib PySide6

Run the Tests

This is the same procedure for all systems, assuming you are still in the build directory build/ezdxf and ezdxf is now installed in the venv.

Install the test dependencies and run the tests:

pip3 install pytest geomdl
python3 -m pytest tests integration_tests

Build Documentation

Assuming you are still in the build directory build/ezdxf of the previous section.

Install Sphinx:

pip3 install Sphinx sphinx-rtd-theme

Build the HTML documentation:

cd docs
make html

The output is located in build/ezdxf/docs/build/html.

Python from Source

Debian based systems have often very outdated software installed and sometimes there is no easy way to install a newer Python version. This is a brief summery how I installed Python 3.9.9 on the Raspberry Pi OS, for more information go to the source of the recipe: Real Python

Install build requirements:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \


   libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \


   libncurses5-dev libncursesw5-dev xz-utils tk-dev

Make a build directory:

cd ~
mkdir build
cd build

Download and unpack the source code from Python.org, replace 3.9.9 by your desired version:

wget https://www.python.org/ftp/python/3.9.9/Python-3.9.9.tgz
tar -xvzf Python-3.9.9.tgz
cd Python-3.9.9/

Configure the build process, use a prefix to the directory where the interpreter should be installed:

./configure --prefix=/opt/python3.9.9 --enable-optimizations

Build & install the Python interpreter. The -j option simply tells make to split the building into parallel steps to speed up the compilation, my Raspberry Pi 400 has 4 cores so 4 seems to be a good choice:

make -j 4
sudo make install

The building time was ~25min and the new Python 3.9.9 interpreter is now installed as /opt/python3.9.9/bin/python3.

At the time there were no system packages for Matplotlib and PyQt5 for this new Python version available, so there is no benefit of using the option --system-site-packages for building the venv:

cd ~/build
/opt/python3.9.9/bin/python3 -m venv py39
source py39/bin/activate

I have not tried to build Matplotlib and PyQt5 by myself and the installation by pip from piwheels did not work, in this case you don’t get Matplotlib support for better font measuring and the drawing add-on will not work.

Proceed with the ezdxf installation from source as shown for the Raspberry Pi OS.

Loading DXF Files

ezdxf supports loading ASCII and binary DXF files from a file:

doc = ezdxf.readfile(filename)

or from a zip-file:

doc = ezdxf.readzip(zipfilename[, filename])

Which loads the DXF file filename from the zip-file zipfilename or the first DXF file in the zip-file if filename is absent.

It is also possible to read a DXF file from a stream by the ezdxf.read() function, but this is a more advanced feature, because this requires detection of the file encoding in advance.

This works well with DXF files from trusted sources like AutoCAD or BricsCAD, for loading DXF files with minor or major flaws look at the ezdxf.recover module.

SEE ALSO:

Saving DXF Files

Save the DXF document with a new name:

doc.saveas("new_name.dxf")

or with the same name as loaded:

doc.save()

SEE ALSO:

Create a New DXF File

Create new file for the latest supported DXF version:

doc = ezdxf.new()

Create a new DXF file for a specific DXF version, e.g for DXF R12:

doc = ezdxf.new("R12")

To setup some basic DXF resources use the setup argument:

doc = ezdxf.new(setup=True)

SEE ALSO:

Layouts and Blocks

Layouts are containers for DXF entities like LINE or CIRCLE. The most important layout is the modelspace labeled as “Model” in CAD applications which represents the “world” work space. Paperspace layouts represents plottable sheets which contains often the framing and the tile block of a drawing and VIEWPORT entities as scaled and clipped “windows” into the modelspace.

The modelspace is always present and can not be deleted. The active paperspace is also always present in a new DXF document but can be deleted, in that case another paperspace layout gets the new active paperspace, but you can not delete the last paperspace layout.

Getting the modelspace of a DXF document:

msp = doc.modelspace()

Getting a paperspace layout by the name as shown in the tab of a CAD application:

psp = doc.layout("Layout1")

A block is just another kind of entity space, which can be inserted multiple times into other layouts and blocks by the INSERT entity also called block references, this is a very powerful and important concept of the DXF format.

Getting a block layout by the block name:

blk = doc.blocks.get("NAME")

All these layouts have factory functions to create graphical DXF entities for their entity space, for more information about creating entities see section: Create new DXF Entities

Create New Blocks

The block definitions of a DXF document are managed by the BlocksSection object:

my_block = doc.blocks.new("MyBlock")

SEE ALSO:

Query DXF Entities

As said in the Layouts and Blocks section, all graphical DXF entities are stored in layouts, all these layouts can be iterated and support the index operator e.g. layout[-1] returns the last entity.

The main difference between iteration and index access is, that iteration filters destroyed entities, but the index operator returns also destroyed entities until these entities are purged by layout.purge() more about this topic in section: Delete Entities.

There are two advanced query methods: query() and groupby().

Get all lines of layer "MyLayer":

lines = msp.query('LINE[layer=="MyLayer"]')

This returns an EntityQuery container, which also provides the same query() and groupby() methods.

Get all lines categorized by a DXF attribute like color:

all_lines_by_color = msp.query("LINE").groupby("color")
lines_with_color_1 = all_lines_by_color.get(1, [])

The groupby() method returns a regular Python dict with colors as key and a regular Python list of entities as values (not an EntityQuery container).

SEE ALSO:

Examine DXF Entities

Each DXF entity has a dxf namespace attribute, which stores the named DXF attributes, some DXF attributes are only indirect available like the vertices in the LWPOLYLINE entity. More information about the DXF attributes of each entity can found in the documentation of the ezdxf.entities module.

Get some basic DXF attributes:

layer = entity.dxf.layer  # default is "0"
color = entity.dxf.color  # default is 256 = BYLAYER

Most DXF attributes have a default value, which will be returned if the DXF attribute is not present, for DXF attributes without a default value you can check in the attribute really exist:

entity.dxf.hasattr("true_color")

or use the get() method and a default value:

entity.dxf.get("true_color", 0)

SEE ALSO:

Create New DXF Entities

The factory methods for creating new graphical DXF entities are located in the BaseLayout class. This means this factory methods are available for all entity containers:

The usage is simple:

msp = doc.modelspace()
msp.add_line((0, 0), (1, 0), dxfattribs={"layer": "MyLayer"})

SEE ALSO:

A few important or required DXF attributes are explicit method arguments, most additional and optional DXF attributes are gives as a regular Python dict object. The supported DXF attributes can be found in the documentation of the ezdxf.entities module.

WARNING:

Create Block References

A block reference is just another DXF entity called INSERT, but the term “Block Reference” is a better choice and so the Insert entity is created by the factory function: add_blockref():

msp.add_blockref("MyBlock", (0, 0))

SEE ALSO:

Create New Layers

A layer is not an entity container, a layer is just another DXF attribute stored in the entity and this entity can inherit some properties from this Layer object. Layer objects are stored in the layer table which is available as attribute doc.layers.

You can create your own layers:

my_layer = doc.layer.add("MyLayer")

The layer object also controls the visibility of entities which references this layer, the on/off state of the layer is unfortunately stored as positive or negative color value which make the raw DXF attribute of layers useless, to change the color of a layer use the property Layer.color

my_layer.color = 1

To change the state of a layer use the provided methods of the Layer object, like on(), off(), freeze() or thaw():

my_layer.off()

SEE ALSO:

Delete Entities

The safest way to delete entities is to delete the entity from the layout containing that entity:

line = msp.add_line((0, 0), (1, 0))
msp.delete_entity(line)

This removes the entity immediately from the layout and destroys the entity. The property is_alive returns False for a destroyed entity and all Python attributes are deleted, so line.dxf.color will raise an AttributeError exception, because line does not have a dxf attribute anymore.

Ezdxf also supports also destruction of entities by calling method destroy() manually:

line.destroy()

Manually destroyed entities are not removed immediately from entities containers like Modelspace or EntityQuery, but iterating such a container will filter destroyed entities automatically, so a for e in msp: ... loop will never yield destroyed entities. The index operator and the len() function do not filter deleted entities, to avoid getting deleted entities call the purge() method of the container manually to remove deleted entities.

Further Information

What is DXF?

The common assumption is also the cite of Wikipedia:

The more precise cite from the DXF reference itself:

No mention of interoperability between AutoCAD and other applications.

In reality the DXF format was designed to ensure AutoCAD cross-platform compatibility in the early days when different hardware platforms with different binary data formats were used. The name DXF (Drawing eXchange Format) may suggest an universal exchange format, but it is not. It is based on the infrastructure installed by Autodesk products (fonts) and the implementation details of AutoCAD (MTEXT) or on licensed third party technologies (embedded ACIS entities).

For more information about the AutoCAD history see the document: The Autodesk File - Bits of History, Words of Experience by John Walker, founder of Autodesk, Inc. and co-author of AutoCAD.

DXF Reference Quality

The DXF reference is by far no specification nor a standard like the W3C standard for SVG or the ISO standard for PDF.

The reference describes many but not all DXF entities and some basic concepts like the tag structure or the arbitrary axis algorithm. But the existing documentation (reference) is incomplete and partly misleading or wrong. Also missing from the reference are some important parts like the complex relationship between the entities to create higher order structures like block definitions, layouts (model space & paper space) or dynamic blocks to name a few.

Reliable CAD Applications

Because of the suboptimal quality of the DXF reference not all DXF viewers, creators or processors are of equal quality. I consider a CAD application as a reliable CAD application when the application creates valid DXF documents in the meaning and interpretation of Autodesk and a reliable DXF viewer when the result matches in most parts the result of the free Trueview viewer provided by Autodesk.

These are some applications which do fit the criteria of a reliable CAD application:

Unfortunately, I cannot recommend any open source applications because everyone I know has serious shortcomings, at least as a DXF viewer, and I don’t trust them as a DXF creator either. To be clear, not even ezdxf (which is not a CAD application) is a reliable library in this sense - it just keeps getting better, but is far from reliable.

BTW: Don’t send bug reports based on LibreCAD or QCAD, I won’t waste my time on them.

AutoCAD Color Index (ACI)

The color attribute represents an ACI (AutoCAD Color Index). AutoCAD and many other CAD application provides a default color table, but pen table would be the more correct term. Each ACI entry defines the color value, the line weight and some other attributes to use for the pen. This pen table can be edited by the user or loaded from an CTB or STB file. Ezdxf provides functions to create (new()) or modify (ezdxf.acadctb.load()) plot styles files.

DXF R12 and prior are not good in preserving the layout of a drawing, because of the lack of a standard color table defined by the DXF reference and missing DXF structures to define these color tables in the DXF file. So if a CAD user redefined an ACI and do not provide a CTB or STB file, you have no ability to determine which color or lineweight was used. This is better in later DXF versions by providing additional DXF attributes like lineweight and true_color.

SEE ALSO:

Layer Concept

Every object has a layer as one of its properties. You may be familiar with layers - independent drawing spaces that stack on top of each other to create an overall image - from using drawing programs. Most CAD programs use layers as the primary organizing principle for all the objects that you draw. You use layers to organize objects into logical groups of things that belong together; for example, walls, furniture, and text notes usually belong on three separate layers, for a couple of reasons:

Create a layer table entry Layer by Drawing.layers.new(), assign the layer properties such as color and linetype. Then assign those layers to other DXF entities by setting the DXF attribute layer to the layer name as string.

It is possible to use layers without a layer definition but not recommend, just use a layer name without a layer definition, the layer has the default linetype 'Continuous' and the default color is 7.

The advantage of assigning a linetype and a color to a layer is that entities on this layer can inherit this properties by using 'BYLAYER' as linetype string and 256 as color, both values are default values for new entities.

SEE ALSO:

Linetypes

The linetype defines the pattern of a line. The linetype of an entity can be specified by the DXF attribute linetype, this can be an explicit named linetype or the entity can inherit its line type from the assigned layer by setting linetype to 'BYLAYER', which is also the default value. CONTINUOUS is the default line type for layers with unspecified line type.

ezdxf creates several standard linetypes, if the argument setup is True at calling new(), this simple line types are supported by all DXF versions:

doc = ezdxf.new('R2007', setup=True)

In DXF R13 Autodesk introduced complex linetypes, containing TEXT or SHAPES in linetypes. ezdxf v0.8.4 and later supports complex linetypes.

SEE ALSO:

Linetype Scaling

Global linetype scaling can be changed by setting the header variable doc.header['$LTSCALE'] = 2, which stretches the line pattern by factor 2.

To change the linetype scaling for single entities set scaling factor by DXF attribute ltscale, which is supported since DXF version R2000.

Lineweights

The lineweight attribute represents the lineweight as integer value in millimeters * 100, e.g. 0.25mm = 25, independently from the unit system used in the DXF document. The lineweight attribute is supported by DXF version R2000 and newer.

Only certain values are valid, they are stored in ezdxf.lldxf.const.VALID_DXF_LINEWEIGHTS: 0, 5, 9, 13, 15, 18, 20, 25, 30, 35, 40, 50, 53, 60, 70, 80, 90, 100, 106, 120, 140, 158, 200, 211.

Values < 0 have a special meaning and can be imported as constants from ezdxf.lldxf.const

The validator function: ezdxf.lldxf.validator.is_valid_lineweight() returns True for valid lineweight values otherwise False.

Sample file which shows all valid lineweights: valid_lineweights.dxf

You have to enable the option to show lineweights in your CAD application or viewer to see the effect on screen, which is often disabled by default, the same has to be done in the page setup options for plotting lineweights.

Setting the HEADER variable $LWDISPLAY to 1 may activate support for showing lineweights on screen and $LWDISPSCALE may scale the lineweight on screen:

# activate on screen lineweight display
doc.header["$LWDISPLAY"] = 1
# lineweight scaling factor for on screen display
doc.header["$LWDISPSCALE"] = 0.55

The lineweight value can be overridden by CTB or STB files.

Coordinate Systems

AutoLISP Reference to Coordinate Systems provided by Autodesk.

To brush up you knowledge about vectors, watch the YouTube tutorials of 3Blue1Brown about Linear Algebra.

WCS

World coordinate system - the reference coordinate system. All other coordinate systems are defined relative to the WCS, which never changes. Values measured relative to the WCS are stable across changes to other coordinate systems.

UCS

User coordinate system - the working coordinate system defined by the user to make drawing tasks easier. All points passed to AutoCAD commands, including those returned from AutoLISP routines and external functions, are points in the current UCS. As far as I know, all coordinates stored in DXF files are always WCS or OCS never UCS.

User defined coordinate systems are not just helpful for interactive CAD, therefore ezdxf provides a converter class UCS to translate coordinates from UCS into WCS and vice versa, but always remember: store only WCS or OCS coordinates in DXF files, because there is no method to determine which UCS was active or used to create UCS coordinates.

SEE ALSO:

OCS

Object coordinate system - coordinates relative to the object itself. These points are usually converted into the WCS, current UCS, or current DCS, according to the intended use of the object. Conversely, points must be translated into an OCS before they are written to the database. This is also known as the entity coordinate system.

Because ezdxf is just an interface to DXF, it does not automatically convert OCS into WCS, this is the domain of the user/application. And further more, the main goal of OCS is to place 2D elements in 3D space, this maybe was useful in the early years of CAD, I think nowadays this is an not often used feature, but I am not an AutoCAD user.

OCS differ from WCS only if extrusion != (0, 0, 1), convert OCS into WCS:

# circle is an DXF entity with extrusion != (0, 0, 1)
ocs = circle.ocs()
wcs_center = ocs.to_wcs(circle.dxf.center)

SEE ALSO:

DCS

Display coordinate system - the coordinate system into which objects are transformed before they are displayed. The origin of the DCS is the point stored in the AutoCAD system variable TARGET, and its z-axis is the viewing direction. In other words, a viewport is always a plan view of its DCS. These coordinates can be used to determine where something will be displayed to the AutoCAD user.

Object Coordinate System (OCS)

The points associated with each entity are expressed in terms of the entity’s own object coordinate system (OCS). The OCS was referred to as ECS in previous releases of AutoCAD.

With OCS, the only additional information needed to describe the entity’s position in 3D space is the 3D vector describing the z-axis of the OCS (often referenced as extrusion vector), and the elevation value, which is the distance of the entity xy-plane to the WCS/OCS origin.

For a given z-axis (extrusion) direction, there are an infinite number of coordinate systems, defined by translating the origin in 3D space and by rotating the x- and y-axis around the z-axis. However, for the same z-axis direction, there is only one OCS. It has the following properties:

The following entities do not lie in a particular plane. All points are expressed in world coordinates. Of these entities, only lines and points can be extruded. Their extrusion direction can differ from the world z-axis.

These entities are planar in nature. All points are expressed in object coordinates. All of these entities can be extruded. Their extrusion direction can differ from the world z-axis.

Some of a Dimension’s points are expressed in WCS and some in OCS.

Elevation

Elevation group code 38:

Exists only in output from versions prior to R11. Otherwise, Z coordinates are supplied as part of each of the entity’s defining points.

Arbitrary Axis Algorithm

The arbitrary axis algorithm is used by AutoCAD internally to implement the arbitrary but consistent generation of object coordinate systems for all entities that use object coordinates.

Given a unit-length vector to be used as the z-axis of a coordinate system, the arbitrary axis algorithm generates a corresponding x-axis for the coordinate system. The y-axis follows by application of the right-hand rule.

We are looking for the arbitrary x- and y-axis to go with the normal Az (the arbitrary z-axis). They will be called Ax and Ay (using Vec3):

Az = Vec3(entity.dxf.extrusion).normalize()  # normal (extrusion) vector
if (abs(Az.x) < 1/64.) and (abs(Az.y) < 1/64.):


     Ax = Vec3(0, 1, 0).cross(Az).normalize()  # the cross-product operator
else:


     Ax = Vec3(0, 0, 1).cross(Az).normalize()  # the cross-product operator
Ay = Az.cross(Ax).normalize()

WCS to OCS

def wcs_to_ocs(point):


    px, py, pz = Vec3(point)  # point in WCS


    x = px * Ax.x + py * Ax.y + pz * Ax.z


    y = px * Ay.x + py * Ay.y + pz * Ay.z


    z = px * Az.x + py * Az.y + pz * Az.z


    return Vec3(x, y, z)

OCS to WCS

Wx = wcs_to_ocs((1, 0, 0))
Wy = wcs_to_ocs((0, 1, 0))
Wz = wcs_to_ocs((0, 0, 1))
def ocs_to_wcs(point):


    px, py, pz = Vec3(point)  # point in OCS


    x = px * Wx.x + py * Wx.y + pz * Wx.z


    y = px * Wy.x + py * Wy.y + pz * Wy.z


    z = px * Wz.x + py * Wz.y + pz * Wz.z


    return Vec3(x, y, z)

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:

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.

Changed in version 0.17.2: added an enumeration ezdxf.enums.InsertUnits

doc.header['$INSUNITS'] = 6

$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.

Changed in version 0.17.2: added an enumeration ezdxf.enums.Measurement

doc.header['$MEASUREMENT'] = 1

$LUNITS

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

Changed in version 0.17.2: added an enumeration ezdxf.enums.LengthUnits

doc.header['$LUNITS'] = 2

$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:

Changed in version 0.17.2: added an enumeration ezdxf.enums.AngularUnits

doc.header['$AUNITS'] = 0

Helper Tools

Layout Extents and Limits

The extents and limits of an layout represents borders which can be referenced by the ZOOM command or read from some header variables from the HeaderSection, if the creator application maintains these values – ezdxf does it not automatically.

Extents

The extents of an layout are determined by the maximum extents of all DXF entities that are in this layout. The command:

ZOOM extents

sets the current viewport to the extents of the currently selected layout.

A paper space layout in an arbitrary zoom state: [image]

The same layout after the ZOOM extents command: [image]

Limits

Sets an invisible rectangular boundary in the drawing area that can limit the grid display and limit clicking or entering point locations. The default limits for paper space layouts is defined by the paper size.

The layout from above after the ZOOM all command: [image]

SEE ALSO:

Read Stored Values

The extents of the model space (the tab called “Model”) are stored in the header variable $EXTMIN and $EXTMAX. The default values of $EXTMIN is (+1e20, +1e20, +1e20) and $EXTMAX is (-1e20, -1e20, -1e20), which do not describe real borders. These values are copies of the extents attributes of the Layout object as Layout.dxf.extmin and Layout.dxf.extmax.

The limits of the modelspace are stored in the header variables $LIMMIN and $LIMMAX and have default values of (0, 0) and (420, 297), the default paper size of ezdxf in drawing units. These are copies of the Layout attributes Layout.dxf.extmin and Layout.dxf.extmax.

The extents and the limits of the actual paper space layout, which is the last activated paper space layout tab, stored in the header variable $PEXTMIN, $PEXTMAX, $PLIMMIN and $PLIMMAX.

Each paper space layout has its own values stored in the Layout attributes Layout.dxf.extmin, Layout.dxf.extmax, Layout.dxf.limmin and Layout.dxf.limmax.

Setting Extents and Limits

Since v0.16 ezdxf it is sufficient to define the attributes for extents and limits (Layout.dxf.extmax, Layout.dxf.limmin and Layout.dxf.limmax) of Layout object. The header variables are synchronized when the document is saved.

The extents of a layout are not calculated automatically by ezdxf, as this can take a long time for large documents and correct values are not required to create a valid DXF document.

SEE ALSO:

Font Resources

DXF relies on the infrastructure installed by AutoCAD like the included SHX files or True Type fonts. There is no simple way to store additional information about a used fonts beside the plain file system name like "arial.ttf". The CAD application or viewer which opens the DXF file has to have access to the specified fonts used in your DXF document or it has to use an appropriate replacement font, which is not that easy in the age of unicode. Later DXF versions can store font family names in the XDATA of the STYLE entity but not all CAD application use this information.

Tutorial for getting data from DXF files

In this tutorial I show you how to get data from an existing DXF drawing. If you are a new ezdxf user, read also the tutorial Usage for Beginners.

Loading the DXF file:

import sys
import ezdxf
try:


    doc = ezdxf.readfile("your_dxf_file.dxf")
except IOError:


    print(f"Not a DXF file or a generic I/O error.")


    sys.exit(1)
except ezdxf.DXFStructureError:


    print(f"Invalid or corrupted DXF file.")


    sys.exit(2)

This works well for DXF files from trusted sources like AutoCAD or BricsCAD, for loading DXF files with minor or major flaws look at the ezdxf.recover module.

SEE ALSO:

Layouts

I use the term layout as synonym for an arbitrary entity space which can contain DXF entities like LINE, CIRCLE, TEXT and so on. Every DXF entity can only reside in exact one layout.

There are three different layout types:

A DXF drawing consist of exact one modelspace and at least of one paperspace. DXF R12 has only one unnamed paperspace the later DXF versions support more than one paperspace and each paperspace has a name.

Getting the modelspace layout

The modelspace contains the “real” world representation of the drawing subjects in real world units. The modelspace has the fixed name “Model” and the DXF document has a special getter method modelspace().

msp = doc.modelspace()

Iterate over DXF entities of a layout

Iterate over all DXF entities in modelspace. Although this is a possible way to retrieve DXF entities, I would like to point out that entity queries are the better way.

# helper function
def print_entity(e):


    print("LINE on layer: %s\n" % e.dxf.layer)


    print("start point: %s\n" % e.dxf.start)


    print("end point: %s\n" % e.dxf.end)
# iterate over all entities in modelspace
msp = doc.modelspace()
for e in msp:


    if e.dxftype() == "LINE":


        print_entity(e)
# entity query for all LINE entities in modelspace
for e in msp.query("LINE"):


    print_entity(e)

All layout objects supports the standard Python iterator protocol and the in operator.

Access DXF attributes of an entity

Check the type of an DXF entity by e.dxftype(). The DXF type is always uppercase. All DXF attributes of an entity are grouped in the namespace attribute dxf:

e.dxf.layer  # layer of the entity as string
e.dxf.color  # color of the entity as integer

See Common graphical DXF attributes

If a DXF attribute is not set (a valid DXF attribute has no value), a DXFValueError will be raised. To avoid this use the get_dxf_attrib() method with a default value:

# If DXF attribute 'paperspace' does not exist, the entity defaults
# to modelspace:
p = e.get_dxf_attrib("paperspace", 0)

An unsupported DXF attribute raises an DXFAttributeError.

Getting a paperspace layout

paperspace = doc.layout("layout0")

Retrieves the paperspace named layout0, the usage of the Layout object is the same as of the modelspace object. DXF R12 provides only one paperspace, therefore the paperspace name in the method call doc.layout("layout0") is ignored or can be left off. For newer DXF versions you can get a list of the available layout names by the methods layout_names() and layout_names_in_taborder().

Retrieve entities by query language

ezdxf provides a flexible query language for DXF entities. All layout types have a query() method to start an entity query or use the ezdxf.query.new() function.

The query string is the combination of two queries, first the required entity query and second the optional attribute query, enclosed in square brackets: "EntityQuery[AttributeQuery]"

The entity query is a whitespace separated list of DXF entity names or the special name *. Where * means all DXF entities, all other DXF names have to be uppercase. The * search can exclude entity types by adding the entity name with a presceding ! (e.g. * !LINE, search all entities except lines).

The attribute query is used to select DXF entities by its DXF attributes. The attribute query is an addition to the entity query and matches only if the entity already match the entity query. The attribute query is a boolean expression, supported operators: and, or, !.

SEE ALSO:

Get all LINE entities from the modelspace:

msp = doc.modelspace()
lines = msp.query("LINE")

The result container EntityQuery also provides the query() method, get all LINE entities at layer construction:

construction_lines = lines.query('*[layer=="construction"]')

The * is a wildcard for all DXF types, in this case you could also use LINE instead of *, * works here because lines just contains entities of DXF type LINE.

All together as one query:

lines = msp.query('LINE[layer=="construction"]')

The ENTITIES section also supports the query() method:

lines_and_circles = doc.entities.query('LINE CIRCLE[layer=="construction"]')

Get all modelspace entities at layer construction, but excluding entities with linetype DASHED:

not_dashed_entities = msp.query('*[layer=="construction" and linetype!="DASHED"]')

Retrieve entities by groupby() function

Search and group entities by a user defined criteria. As example let’s group all entities from modelspace by layer, the result will be a dict with layer names as dict-key and a list of all entities from modelspace matching this layer as dict-value. Usage as dedicated function call:

from ezdxf.groupby import groupby
group = groupby(entities=msp, dxfattrib="layer")

The entities argument can be any container or generator which yields DXFEntity or inherited objects. Shorter and simpler to use as method of BaseLayout (modelspace, paperspace layouts, blocks) and query results as EntityQuery objects:

group = msp.groupby(dxfattrib="layer")
for layer, entities in group.items():


    print(f'Layer "{layer}" contains following entities:')


    for entity in entities:


        print(f"    {entity}")


    print("-"*40)

The previous example shows how to group entities by a single DXF attribute, but it is also possible to group entities by a custom key, to do so create a custom key function, which accepts a DXF entity as argument and returns a hashable value as dict-key or None to exclude the entity. The following example shows how to group entities by layer and color, so each result entry has a tuple (layer, color) as key and a list of entities with matching DXF attributes as values:

def layer_and_color_key(entity):


    # return None to exclude entities from result container


    if entity.dxf.layer == "0":  # exclude entities from default layer "0"


        return None


    else:


        return entity.dxf.layer, entity.dxf.color
group = msp.groupby(key=layer_and_color_key)
for key, entities in group.items():


    print(f'Grouping criteria "{key}" matches following entities:')


    for entity in entities:


        print(f"    {entity}")


    print("-"*40)

To exclude entities from the result container the key function should return None. The groupby() function catches DXFAttributeError exceptions while processing entities and excludes this entities from the result container. So there is no need to worry about DXF entities which do not support certain attributes, they will be excluded automatically.

SEE ALSO:

Tutorial for creating simple DXF drawings

r12writer - create simple DXF R12 drawings with a restricted entities set: LINE, CIRCLE, ARC, TEXT, POINT, SOLID, 3DFACE and POLYLINE. Advantage of the r12writer is the speed and the low memory footprint, all entities are written direct to the file/stream without building a drawing data structure in memory.

SEE ALSO:

Create a new DXF drawing with ezdxf.new() to use all available DXF entities:

import ezdxf
# Create a new DXF R2010 drawing, official DXF version name: "AC1024"
doc = ezdxf.new('R2010')
# Add new entities to the modelspace:
msp = doc.modelspace()
# Add a LINE entity
msp.add_line((0, 0), (10, 0))
doc.saveas('line.dxf')

New entities are always added to layouts, a layout can be the model space, a paper space layout or a block layout.

SEE ALSO:

Tutorial for Layers

If you are not familiar with the concept of layers, please read this first: Layer Concept

Create a Layer Definition

import ezdxf
doc = ezdxf.new(setup=True)  # setup required line types
msp = doc.modelspace()
doc.layers.add(name="MyLines", color=7, linetype="DASHED")

The advantage of assigning a linetype and a color to a layer is that entities on this layer can inherit this properties by using "BYLAYER" as linetype string and 256 as color, both values are default values for new entities so you can leave off these assignments:

msp.add_line((0, 0), (10, 0), dxfattribs={"layer": "MyLines"})

The new created line will be drawn with color 7 and linetype "DASHED".

Changing Layer State

Get the layer definition object:

my_lines = doc.layers.get('MyLines')

Check the state of the layer:

my_lines.is_off()  # True if layer is off
my_lines.is_on()   # True if layer is on
my_lines.is_locked()  # True if layer is locked
layer_name = my_lines.dxf.name  # get the layer name

Change the state of the layer:

# switch layer off, entities at this layer will not shown in CAD applications/viewers
my_lines.off()
# lock layer, entities at this layer are not editable in CAD applications
my_lines.lock()

Get/set default color of a layer by property Layer.color, because the DXF attribute Layer.dxf.color is misused for switching the layer on and off, layer is off if the color value is negative.

Changing the default layer values:

my_lines.dxf.linetype = "DOTTED"
my_lines.color = 13  # preserves on/off state of layer

SEE ALSO:

Check Available Layers

The layers object supports some standard Python protocols:

# iteration
for layer in doc.layers:


    if layer.dxf.name != "0":


        layer.off()  # switch all layers off except layer "0"
# check for existing layer definition
if "MyLines" in doc.layers:


    layer = doc.layers.get("MyLines")
layer_count = len(doc.layers) # total count of layer definitions

Deleting a Layer

Delete a layer definition:

doc.layers.remove("MyLines")

This just deletes the layer definition, all DXF entities with the DXF attribute layer set to "MyLines" are still there, but if they inherit color and/or linetype from the layer definition they will be drawn now with linetype "Continuous" and color 1.

Tutorial for Blocks

What are Blocks?

Blocks are collections of DXF entities which can be placed multiple times as block references in different layouts and other block definitions. The block reference (Insert) can be rotated, scaled, placed in 3D space by OCS and arranged in a grid like manner, each Insert entity can have individual attributes (Attrib) attached.

Create a Block

Blocks are managed as BlockLayout objects by the BlocksSection object, every drawing has only one blocks section stored in the attribute: Drawing.blocks.

import ezdxf
import random  # needed for random placing points
def get_random_point():


    """Returns random x, y coordinates."""


    x = random.randint(-100, 100)


    y = random.randint(-100, 100)


    return x, y
# Create a new drawing in the DXF format of AutoCAD 2010
doc = ezdxf.new('R2010')
# Create a block with the name 'FLAG'
flag = doc.blocks.new(name='FLAG')
# Add DXF entities to the block 'FLAG'.
# The default base point (= insertion point) of the block is (0, 0).
flag.add_lwpolyline([(0, 0), (0, 5), (4, 3), (0, 3)])  # the flag symbol as 2D polyline
flag.add_circle((0, 0), .4, dxfattribs={'color': 2})  # mark the base point with a circle

Block References (Insert)

A block reference is a DXF Insert entity and can be placed in any layout: Modelspace, any Paperspace or BlockLayout (which enables nested block references). Every block reference can be placed, scaled and rotated individually. Scaling by negative values is mirroring.

Lets insert some random flags into the modelspace:

# Get the modelspace of the drawing.
msp = doc.modelspace()
# Get 50 random placing points.
placing_points = [get_random_point() for _ in range(50)]
for point in placing_points:


    # Every flag has a different scaling and a rotation of -15 deg.


    random_scale = 0.5 + random.random() * 2.0


    # Add a block reference to the block named 'FLAG' at the coordinates 'point'.


    msp.add_blockref('FLAG', point, dxfattribs={


        'xscale': random_scale,


        'yscale': random_scale,


        'rotation': -15


    })
# Save the drawing.
doc.saveas("blockref_tutorial.dxf")

Query all block references of block FLAG:

for flag_ref in msp.query('INSERT[name=="FLAG"]'):


    print(str(flag_ref))

When inserting a block reference into the modelspace or another block layout with different units, the scaling factor between these units should be applied as scaling attributes (xscale, …) e.g. modelspace in meters and block in centimeters, xscale has to be 0.01.

What are Attributes?

An attribute (Attrib) is a text annotation attached to a block reference with an associated tag. Attributes are often used to add information to blocks which can be evaluated and exported by CAD programs. An attribute can be visible or hidden. The simple way to use attributes is just to add an attribute to a block reference by Insert.add_attrib(), but the attribute is geometrically not related to the block reference, so you have to calculate the insertion point, rotation and scaling of the attribute by yourself.

Using Attribute Definitions

The second way to use attributes in block references is a two step process, first step is to create an attribute definition (template) in the block definition, the second step is adding the block reference by Layout.add_blockref() and attach and fill attribute automatically by the add_auto_attribs() method to the block reference. The advantage of this method is that all attributes are placed relative to the block base point with the same rotation and scaling as the block, but has the disadvantage that non uniform scaling is not handled very well. The method Layout.add_auto_blockref() handles non uniform scaling better by wrapping the block reference and its attributes into an anonymous block and let the CAD application do the transformation work which will create correct graphical representations at least by AutoCAD and BricsCAD. This method has the disadvantage of a more complex evaluation of attached attributes

Using attribute definitions (Attdef):

# Define some attributes for the block 'FLAG', placed relative
# to the base point, (0, 0) in this case.
flag.add_attdef('NAME', (0.5, -0.5), dxfattribs={'height': 0.5, 'color': 3})
flag.add_attdef('XPOS', (0.5, -1.0), dxfattribs={'height': 0.25, 'color': 4})
flag.add_attdef('YPOS', (0.5, -1.5), dxfattribs={'height': 0.25, 'color': 4})
# Get another 50 random placing points.
placing_points = [get_random_point() for _ in range(50)]
for number, point in enumerate(placing_points):


    # values is a dict with the attribute tag as item-key and


    # the attribute text content as item-value.


    values = {


        'NAME': "P(%d)" % (number + 1),


        'XPOS': "x = %.3f" % point[0],


        'YPOS': "y = %.3f" % point[1]


    }


    # Every flag has a different scaling and a rotation of +15 deg.


    random_scale = 0.5 + random.random() * 2.0


    blockref = msp.add_blockref('FLAG', point, dxfattribs={


        'rotation': 15


    }).set_scale(random_scale)


    blockref.add_auto_attribs(values)
# Save the drawing.
doc.saveas("auto_blockref_tutorial.dxf")

Get/Set Attributes of Existing Block References

See the howto: Get/Set Block Reference Attributes

Evaluate Wrapped Block References

As mentioned above evaluation of block references wrapped into anonymous blocks is complex:

# Collect all anonymous block references starting with '*U'
anonymous_block_refs = modelspace.query('INSERT[name ? "^\*U.+"]')
# Collect real references to 'FLAG'
flag_refs = []
for block_ref in anonymous_block_refs:


    # Get the block layout of the anonymous block


    block = doc.blocks.get(block_ref.dxf.name)


    # Find all block references to 'FLAG' in the anonymous block


    flag_refs.extend(block.query('INSERT[name=="FLAG"]'))
# Evaluation example: collect all flag names.
flag_numbers = [


    flag.get_attrib_text("NAME")


    for flag in flag_refs


    if flag.has_attrib("NAME")
]
print(flag_numbers)

Exploding Block References

This is an advanced feature and because ezdxf is still not a CAD application, the results may no be perfect. Non uniform scaling lead to incorrect results for text entities (TEXT, MTEXT, ATTRIB) and some other entities like HATCH with arc or ellipse path segments.

By default the “exploded” entities are added to the same layout as the block reference is located.

for flag_ref in msp.query('INSERT[name=="FLAG"]'):


    flag_ref.explode()

Examine Entities of Block References

If you just want to examine the entities of a block reference use the virtual_entities() method. This methods yields “virtual” entities with attributes identical to “exploded” entities but they are not stored in the entity database, have no handle and are not assigned to any layout.

for flag_ref in msp.query('INSERT[name=="FLAG"]'):


    for entity in flag_ref.virtual_entities():


        if entity.dxftype() == "LWPOLYLINE":


            print(f"Found {str(entity)}.")

Tutorial for LWPolyline

The LWPolyline is defined as a single graphic entity, which differs from the old-style Polyline entity, which is defined as a group of sub-entities. LWPolyline display faster (in AutoCAD) and consume less disk space, it is a planar element, therefore all points in OCS as (x, y) tuples (LWPolyline.dxf.elevation is the z-axis value).

Create a simple polyline:

import ezdxf
doc = ezdxf.new("R2000")
msp = doc.modelspace()
points = [(0, 0), (3, 0), (6, 3), (6, 6)]
msp.add_lwpolyline(points)
doc.saveas("lwpolyline1.dxf")

Append multiple points to a polyline:

doc = ezdxf.readfile("lwpolyline1.dxf")
msp = doc.modelspace()
line = msp.query("LWPOLYLINE").first
if line is not None:


    line.append_points([(8, 7), (10, 7)])
doc.saveas("lwpolyline2.dxf")

The LWPOLYLINE entity always returns polyline points as 5-tuple (x, y, start_width, end_width, bulge), the start_width, end_width and bulge values are 0 if not present:

first_point = line[0]
x, y, start_width, end_width, bulge = first_point

Use the method points() as context manager to edit polyline points, this method was introduced because accessing single points was very slow in early versions of ezdxf, but now direct access by the index operator [] is very fast and using the context manager is not required anymore. The advantage of the context manager is the ability to use a user defined point format:

doc = ezdxf.readfile("lwpolyline2.dxf")
msp = doc.modelspace()
line = msp.query("LWPOLYLINE").first
with line.points("xyseb") as points:


    # points is a standard Python list


    # existing points are 5-tuples, but new points can be


    # set as (x, y, [start_width, [end_width, [bulge]]]) tuple


    # set start_width, end_width to 0 to be ignored (x, y, 0, 0, bulge).


    # delete last 2 points


    del points[-2:]


    # adding two points


    points.extend([(4, 7), (0, 7)])
doc.saveas("lwpolyline3.dxf")

Each line segment can have a different start- and end-width, if omitted start- and end-width is 0:

doc = ezdxf.new("R2000")
msp = doc.modelspace()
# point format = (x, y, [start_width, [end_width, [bulge]]])
# set start_width, end_width to 0 to be ignored (x, y, 0, 0, bulge).
points = [(0, 0, .1, .15), (3, 0, .2, .25), (6, 3, .3, .35), (6, 6)]
msp.add_lwpolyline(points)
doc.saveas("lwpolyline4.dxf")

The first point carries the start- and end-width of the first segment, the second point of the second segment and so on, the start- and end-width value of the last point is used for the closing segment if the polyline is closed else these values are ignored. Start- and end-width only works if the DXF attribute dxf.const_width is unset, to be sure delete it:

# no exception will be raised if const_width is already unset:
del line.dxf.const_width

LWPolyline can also have curved elements, they are defined by the Bulge value:

doc = ezdxf.new("R2000")
msp = doc.modelspace()
# point format = (x, y, [start_width, [end_width, [bulge]]])
# set start_width, end_width to 0 to be ignored (x, y, 0, 0, bulge).
points = [(0, 0, 0, .05), (3, 0, .1, .2, -.5), (6, 0, .1, .05), (9, 0)]
msp.add_lwpolyline(points)
doc.saveas("lwpolyline5.dxf")

The curved segment is drawn from the point which defines the bulge value to the following point, the curved segment is always an arc. The bulge value defines the ratio of the arc sagitta (segment height h) to half line segment length (point distance), a bulge value of 1 defines a semicircle. The curve is on the right side of the line for a bulge value > 0, and on the left side of the line for a bulge value < 0.

The user defined point format, default is xyseb:

msp.add_lwpolyline([(0, 0, 0), (10, 0, 1), (20, 0, 0)], format="xyb")
msp.add_lwpolyline([(0, 10, 0), (10, 10, .5), (20, 10, 0)], format="xyb")

Tutorial for Text

Add a simple one line text entity by factory function add_text().

import ezdxf
# TEXT is a basic entity and is supported by every DXF version.
# Argument setup=True for adding standard linetypes and text styles.
doc = ezdxf.new('R12', setup=True)
msp = doc.modelspace()
# use set_pos() for proper TEXT alignment:
# The relations between DXF attributes 'halign', 'valign',
# 'insert' and 'align_point' are tricky.
msp.add_text("A Simple Text").set_pos((2, 3), align='MIDDLE_RIGHT')
# Using a text style
msp.add_text("Text Style Example: Liberation Serif",


             dxfattribs={


                 'style': 'LiberationSerif',


                 'height': 0.35}


             ).set_pos((2, 6), align='LEFT')
doc.saveas("simple_text.dxf")

Valid text alignments for argument align in Text.set_pos():

Special alignments are ALIGNED and FIT, they require a second alignment point, the text is justified with the vertical alignment Baseline on the virtual line between these two points.

Standard Text Styles

Setup some standard text styles and linetypes by argument setup=True:

doc = ezdxf.new('R12', setup=True)

Replaced all proprietary font declarations in setup_styles() (ARIAL, ARIAL_NARROW, ISOCPEUR and TIMES) by open source fonts, this is also the style name (e.g. {'style': 'OpenSans-Italic'}): [image]

New Text Style

Creating a new text style is simple:

doc.styles.new('myStandard', dxfattribs={'font' : 'OpenSans-Regular.ttf'})

But getting the correct font name is often not that simple, especially on Windows. This shows the required steps to get the font name for Open Sans:

The style name has to be unique in the DXF document, else ezdxf will raise an DXFTableEntryError exception. To replace an existing entry, delete the existing entry by doc.styles.remove(name), and add the replacement entry.

3D Text

It is possible to place the 2D Text entity into 3D space by using the OCS, for further information see: Tutorial for OCS/UCS Usage.

Tutorial for MText and MTextEditor

The MText entity is a multi line entity with extended formatting possibilities and requires at least DXF version R2000, to use all features (e.g. background fill) DXF R2007 is required.

Prolog code:

import ezdxf
doc = ezdxf.new("R2007", setup=True)
msp = doc.modelspace()
lorem_ipsum = """
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.
"""

Adding a MText entity

The MText entity can be added to any layout (modelspace, paperspace or block) by the add_mtext() function.

# store MText entity for additional manipulations
mtext = msp.add_mtext(lorem_ipsum, dxfattribs={"style": "OpenSans"})

This adds a MText entity with text style “OpenSans”. The MText content can be accessed by the text attribute, this attribute can be edited like any Python string:

mtext.text += "Append additional text to the MText entity."
# even shorter with __iadd__() support:
mtext += "Append additional text to the MText entity."

IMPORTANT:

Text placement

The location of the MText entity is defined by the MText.dxf.insert and the MText.dxf.attachment_point attributes. The attachment_point defines the text alignment relative to the insert location, default value is 1.

Attachment point constants defined in ezdxf.lldxf.const:

The MText entity has a method for setting insert, attachment_point and rotation attributes by one call: set_location()

Character height

The character height is defined by the DXF attribute MText.dxf.char_height in drawing units, which has also consequences for the line spacing of the MText entity:

mtext.dxf.char_height = 0.5

The character height can be changed inline, see also MText formatting and MText Inline Codes.

Text rotation (direction)

The MText.dxf.rotation attribute defines the text rotation as angle between the x-axis and the horizontal direction of the text in degrees. The MText.dxf.text_direction attribute defines the horizontal direction of MText as vector in WCS or OCS, if an OCS is defined. Both attributes can be present at the same entity, in this case the MText.dxf.text_direction attribute has the higher priority.

The MText entity has two methods to get/set rotation: get_rotation() returns the rotation angle in degrees independent from definition as angle or direction, and set_rotation() set the rotation attribute and removes the text_direction attribute if present.

Defining a wrapping border

The wrapping border limits the text width and forces a line break for text beyond this border. Without attribute dxf.width (or setting 0) the lines are wrapped only at the regular line endings ” \P” or “\n”, setting the reference column width forces additional line wrappings at the given width. The text height can not be limited, the text always occupies as much space as needed.

mtext.dxf.width = 60

MText formatting

MText supports inline formatting by special codes: MText Inline Codes

mtext.text = "{\\C1;red text} - {\\C3;green text} - {\\C5;blue text}"

See also new section for the new support class MTextEditor in ezdxf v0.17.

Stacked text

MText also supports stacked text:

# the space ' ' in front of 'Lower' and the ';' behind 'Lower' are necessary
# combined with vertical center alignment
mtext.text = "\\A1;\\SUpper^ Lower; - \\SUpper/ Lower;} - \\SUpper# Lower;"

See also new section for the new support class MTextEditor in ezdxf v0.17.

Background color (filling)

The MText entity can have a background filling:

Because of the complex dependencies ezdxf provides a method to set all required DXF attributes at once:

mtext.set_bg_color(2, scale=1.5)

The parameter scale determines how much border there is around the text, the value is based on the text height, and should be in the range of 1 - 5, where 1 fits exact the MText entity. [image]

MTextEditor

New in version 0.17.

WARNING:

The MTextEditor class provides a floating interface to build MText content in an easy way.

This example only shows the connection between MText and the MTextEditor, and shows no additional features to the first example of this tutorial:

Init Editor

import ezdxf
from ezdxf.tools.text import MTextEditor
doc = ezdxf.new("R2007", setup=True)
msp = doc.modelspace()
lorem_ipsum = """
Lorem ipsum dolor sit amet, consectetur adipiscing elit, ... see prolog code
"""
# create a new editor object with an initial text:
editor = MTextEditor(lorem_ipsum)
# get the MTEXT content string from the editor by the str() function:
mtext = msp.add_mtext(str(editor), dxfattribs={"style": "OpenSans"})

Tutorial Prolog:

# use constants defined in MTextEditor:
NP = MTextEditor.NEW_PARAGRAPH
ATTRIBS = {


    "char_height": 0.7,


    "style": "OpenSans",


    "width": 10,
}
editor = MTextEditor("using colors:" + NP)

Set Text Color

There are three ways to change the color inline:

# RED: set color by name - red, green, blue, yellow, cyan, magenta, white
editor.color("red").append("RED" + NP)
# RED: the color stays the same until the next change
editor.append("also RED" + NP)
# GREEN: change color by ACI (AutoCAD Color Index)
editor.aci(3).append("GREEN" + NP)
# BLUE: change color by RGB tuples
editor.rgb((0, 0, 255)).append("BLUE" + NP)
# add the MTEXT entity to the model space:
msp.add_mtext(str(editor), attribs)

Changing Text Height

The MtextEditor.height() method set the text height as absolute value in drawing units (text height = cap height):

attribs = dict(ATTRIBS)
attribs["width"] = 40.0
editor = MTextEditor("changing text height absolute: default height is 0.7" + NP)
# doubling the default height = 1.4
editor.height(1.4)
editor.append("text height: 1.4" + NP)
editor.height(3.5).append("text height: 3.5" + NP)
editor.height(0.7).append("back to default height: 0.7" + NP)
msp.add_mtext(str(editor), attribs)

The MtextEditor.scale_height() method set the text height by a relative factor, the MtextEditor object does not keep track of current text height, you have to do this by yourself. The initial text height is MText.dxf.char_height:

attribs = dict(ATTRIBS)
attribs["width"] = 40.0
editor = MTextEditor("changing text height relative: default height is 0.7" + NP)
# this is the default text height in the beginning:
current_height = attribs["char_height"]
# The text height can only be changed by a factor:
editor.scale_height(2)  # scale by 2 = 1.4
# keep track of the actual height:
current_height *= 2
editor.append("text height: 1.4" + NP)
# to set an absolute height, calculate the required factor:
desired_height = 3.5
factor = desired_height / current_height
editor.scale_height(factor).append("text height: 3.5" + NP)
current_height = desired_height
# and back to 0.7
editor.scale_height(0.7 / current_height).append("back to default height: 0.7" + NP)
msp.add_mtext(str(editor), attribs).set_location(insert=location)

Changing Font

The font name for changing MText fonts inline is the font family name! The font family name is the name shown in font selection widgets in desktop applications: “Arial”, “Times New Roman”, “Comic Sans MS”. The font has to be installed at the target system, else then CAD default font will be used, in AutoCAD/BricsCAD is this the font defined for the text style “Standard”.

IMPORTANT:

attribs = dict(ATTRIBS)
attribs["width"] = 15.0
editor = MTextEditor("changing fonts:" + NP)
editor.append("Default: Hello World!" + NP)
editor.append("SimSun: ")
# change font in a group to revert back to the default font at the end:
simsun_editor = MTextEditor().font("SimSun").append("你好，世界" + NP)
# reverts the font back at the end of the group:
editor.group(str(simsun_editor))
# back to default font OpenSans:
editor.append("Times New Roman: ")
# change font outside of a group until next font change:
editor.font("Times New Roman").append("Привет мир!" + NP)
# If the font does not exist, a replacement font will be used:
editor.font("Does not exist").append("This is the replacement font!")
msp.add_mtext(str(editor), attribs)

Set Paragraph Properties

The paragraph properties are set by the paragraph() method and a ParagraphProperties object, which bundles all paragraph properties in a named tuple.

Each paragraph can have its own properties for:

Indentation and tabulator stops are multiples of the default MText text height stored in MText.dxf.char_height. Calculate the drawing units for indentation and tabulator stops, by multiplying the indentation value by the char_height value.

Mtext paragraphs are separated by new paragraph “\P” characters.

# import support classes:
from ezdxf.tools.text import ParagraphProperties, MTextParagraphAlignment
attribs = dict(ATTRIBS)
attribs["char_height"] = 0.25
attribs["width"] = 7.5
editor = MTextEditor("Indent the first line:" + NP)
props = ParagraphProperties(


    indent=1,  # indent first line = 1x0.25 drawing units


    align=MTextParagraphAlignment.JUSTIFIED
)
editor.paragraph(props)
editor.append(lorem_ipsum)
msp.add_mtext(str(editor), attribs)

The first line indentation “indent” is relative to the “left” indentation.

# import support classes:
from ezdxf.tools.text import ParagraphProperties, MTextParagraphAlignment
attribs = dict(ATTRIBS)
attribs["char_height"] = 0.25
attribs["width"] = 7.5
editor = MTextEditor("Indent left paragraph side:" + NP)
indent = 0.7  # 0.7 * 0.25 = 0.175 drawing units
props = ParagraphProperties(


    # first line indentation is relative to "left", this reverses the


    # left indentation:


    indent=-indent,  # first line


    # indent left paragraph side:


    left=indent,


    align=MTextParagraphAlignment.JUSTIFIED
)
editor.paragraph(props)
editor.append(" ".join(lorem_ipsum(100)))
msp.add_mtext(str(editor), attribs).set_location(insert=location)

Bullet List

There are no special commands to build bullet list, the list is build of indentation and a tabulator stop. Each list item needs a marker as an arbitrary string. For more information about paragraph indentation and tabulator stops see also chapter Set Paragraph Properties.

attribs = dict(ATTRIBS)
attribs["char_height"] = 0.25
attribs["width"] = 7.5
bullet = "•"  # alt + numpad 7
editor = MTextEditor("Bullet List:" + NP)
editor.bullet_list(


    indent=1,


    bullets=[bullet] * 3,  # each list item needs a marker


    content=[


        "First item",


        "Second item",


        " ".join(lorem_ipsum(30)),


    ])
msp.add_mtext(str(editor), attribs)

Numbered List

There are no special commands to build numbered list, the list is build of indentation and a tabulator stop. There is no automatic numbering, but therefore the absolute freedom for using any string as list marker. For more information about paragraph indentation and tabulator stops see also chapter Set Paragraph Properties.

attribs = dict(ATTRIBS)
attribs["char_height"] = 0.25
attribs["width"] = 7.5
editor = MTextEditor("Numbered List:" + NP)
editor.bullet_list(


    indent=1,


    bullets=["1.", "2.", "3."],


    content=[


        "First item",


        "Second item",


        " ".join(lorem_ipsum(30)),


    ])
msp.add_mtext(str(editor), attribs)

Stacked Text

MText supports stacked text (fractions) as a single inline code, which means it is not possible to change any property inside the fraction. This example shows a fraction with scaled down text height, placed in a group to revert the text height afterwards:

editor = MTextEditor("Stacked text:" + NP)
stack = MTextEditor().scale_height(0.6).stack("1", "2", "^")
editor.append("over: ").group(str(stack)).append(NP)
stack = MTextEditor().scale_height(0.6).stack("1", "2", "/")
editor.append("fraction: ").group(str(stack)).append(NP)
stack = MTextEditor().scale_height(0.6).stack("1", "2", "#")
editor.append("slanted: ").group(str(stack)).append(NP)
# Additional formatting in numerator and denominator is not supported
# by AutoCAD or BricsCAD, switching the color inside the stacked text
# to red does not work:
numerator = MTextEditor().color("red").append("1")
stack = MTextEditor().scale_height(0.6).stack(str(numerator), "2", "#")
editor.append("color red: ").group(str(stack)).append(NP)
msp.add_mtext(str(editor), attribs)

SEE ALSO:

Tutorial for Spline

Background information about B-spline at Wikipedia.

Splines from fit points

Splines can be defined by fit points only, this means the curve goes through all given fit points. AutoCAD and BricsCAD generates required control points and knot values by itself, if only fit points are present.

Create a simple spline:

doc = ezdxf.new('R2000')
fit_points = [(0, 0, 0), (750, 500, 0), (1750, 500, 0), (2250, 1250, 0)]
msp = doc.modelspace()
spline = msp.add_spline(fit_points)

Append a fit point to a spline:

# fit_points, control_points, knots and weights are list-like containers:
spline.fit_points.append((2250, 2500, 0))

You can set additional control points, but if they do not fit the auto-generated AutoCAD values, they will be ignored and don’t mess around with knot values.

Solve problems of incorrect values after editing a spline generated by AutoCAD:

doc = ezdxf.readfile("AutoCAD_generated.dxf")
msp = doc.modelspace()
spline = msp.query('SPLINE').first
# fit_points, control_points, knots and weights are list-like objects:
spline.fit_points.append((2250, 2500, 0))

As far as I have tested, this approach works without complaints from AutoCAD, but for the case of problems remove invalid data:

# current control points do not match spline defined by fit points
spline.control_points = []
# count of knots is not correct:
# count of knots = count of control points + degree + 1
spline.knots = []
# same for weights, count of weights == count of control points
spline.weights = []

Splines by control points

To create splines from fit points is the easiest way to create splines, but this method is also the least accurate, because a spline is defined by control points and knot values, which are generated for the case of a definition by fit points, and the worst fact is that for every given set of fit points exist an infinite number of possible splines as solution.

AutoCAD (and BricsCAD also) uses an proprietary algorithm to generate control points and knot values from fit points, which differs from the well documented Global Curve Interpolation. Therefore splines generated from fit points by ezdxf do not match splines generated by AutoCAD (BricsCAD).

To ensure the same spline geometry for all CAD applications, the spline has to be defined by control points. The method add_spline_control_frame() adds a spline through fit points by calculating the control points by the Global Curve Interpolation algorithm. There is also a low level function ezdxf.math.global_bspline_interpolation() which calculates the control points from fit points.

msp.add_spline_control_frame(fit_points, method='uniform', dxfattribs={'color': 1})
msp.add_spline_control_frame(fit_points, method='chord', dxfattribs={'color': 3})
msp.add_spline_control_frame(fit_points, method='centripetal', dxfattribs={'color': 5})

Open Spline

Add and open (clamped) spline defined by control points with the method add_open_spline(). If no knot values are given, an open uniform knot vector will be generated. A clamped B-spline starts at the first control point and ends at the last control point.

control_points = [(0, 0, 0), (1250, 1560, 0), (3130, 610, 0), (2250, 1250, 0)]
msp.add_open_spline(control_points)

Rational Spline

Rational B-splines have a weight for every control point, which can raise or lower the influence of the control point, default weight = 1, to lower the influence set a weight < 1 to raise the influence set a weight > 1. The count of weights has to be always equal to the count of control points.

Example to raise the influence of the first control point:

msp.add_closed_rational_spline(control_points, weights=[3, 1, 1, 1])

Spline properties

Check if spline is a closed curve or close/open spline, for a closed spline the last point is connected to the first point:

if spline.closed:


    # this spline is closed


    pass
# close spline
spline.closed = True
# open spline
spline.closed = False

Set start- and end tangent for splines defined by fit points:

spline.dxf.start_tangent = (0, 1, 0)  # in y-axis
spline.dxf.end_tangent = (1, 0, 0)  # in x-axis

Get data count as stored in DXF file:

count = spline.dxf.n_fit_points
count = spline.dxf.n_control_points
count = spline.dxf.n_knots

Get data count of real existing data:

count = spline.fit_point_count
count = spline.control_point_count
count = spline.knot_count

Tutorial for Polyface

The Polyface entity represents a 3D mesh build of vertices and faces and is just an extended POLYLINE entity with a complex VERTEX structure. The Polyface entity was used in DXF R12 and older DXF versions and is still supported by newer DXF versions. The new Mesh entity stores the same data much more efficient but requires DXF R2000 or newer. The Polyface entity supports only triangles and quadrilaterals as faces the Mesh entity supports n-gons.

Its recommended to use the MeshBuilder objects to create 3D meshes and render them as POLYFACE entities by the render_polymesh() method into a layout:

import ezdxf
from ezdxf import colors
from ezdxf.gfxattribs import GfxAttribs
from ezdxf.render import forms
cube = forms.cube().scale_uniform(10).subdivide(2)
red = GfxAttribs(color=colors.RED)
green = GfxAttribs(color=colors.GREEN)
blue = GfxAttribs(color=colors.BLUE)
doc = ezdxf.new()
msp = doc.modelspace()
# render as MESH entity
cube.render(msp, dxfattribs=red)
cube.translate(20)
# render as POLYFACE a.k.a. POLYLINE entity
cube.render_polyface(msp, dxfattribs=green)
cube.translate(20)
# render as unconnected 3DFACE entities
cube.render_3dfaces(msp, dxfattribs=blue)
doc.saveas("meshes.dxf")

WARNING:

The usage of the MeshBuilder object is also recommended for inspecting Polyface entities:

import ezdxf
from ezdxf.render import MeshBuilder
def process(mesh):


    # vertices is a sequence of 3D points


    vertices = mses.vertices


    # a face is a sequence of indices into the vertices sequence


    faces = mesh.faces


    ...
doc = ezdxf.readfile("meshes.dxf")
msp = doc.modelspace()
for polyline in msp.query("POLYLINE"):


    if polyline.is_poly_face_mesh:


        mesh = MeshBuilder.from_polyface(polyline)


        process(mesh)

Tutorial for Mesh

Create a cube mesh by direct access to base data structures:

import ezdxf
# 8 corner vertices
cube_vertices = [


    (0, 0, 0),


    (1, 0, 0),


    (1, 1, 0),


    (0, 1, 0),


    (0, 0, 1),


    (1, 0, 1),


    (1, 1, 1),


    (0, 1, 1),
]
# 6 cube faces
cube_faces = [


    [0, 1, 2, 3],


    [4, 5, 6, 7],


    [0, 1, 5, 4],


    [1, 2, 6, 5],


    [3, 2, 6, 7],


    [0, 3, 7, 4]
]
# MESH requires DXF R2000 or later
doc = ezdxf.new("R2000")
msp = doc.modelspace()
mesh = msp.add_mesh()
# do not subdivide cube, 0 is the default value
mesh.dxf.subdivision_levels = 0
with mesh.edit_data() as mesh_data:


    mesh_data.vertices = cube_vertices


    mesh_data.faces = cube_faces
doc.saveas("cube_mesh_1.dxf")

Create a cube mesh by assembling single faces and the edit_data() context manager of the Mesh class, using the helper class MeshData:

import ezdxf
# 8 corner vertices
p = [


    (0, 0, 0),


    (1, 0, 0),


    (1, 1, 0),


    (0, 1, 0),


    (0, 0, 1),


    (1, 0, 1),


    (1, 1, 1),


    (0, 1, 1),
]
# MESH requires DXF R2000 or later
doc = ezdxf.new("R2000")
msp = doc.modelspace()
mesh = msp.add_mesh()
with mesh.edit_data() as mesh_data:


    mesh_data.add_face([p[0], p[1], p[2], p[3]])


    mesh_data.add_face([p[4], p[5], p[6], p[7]])


    mesh_data.add_face([p[0], p[1], p[5], p[4]])


    mesh_data.add_face([p[1], p[2], p[6], p[5]])


    mesh_data.add_face([p[3], p[2], p[6], p[7]])


    mesh_data.add_face([p[0], p[3], p[7], p[4]])


    # optional call optimize(): minimizes the vertex count


    mesh_data.optimize()
doc.saveas("cube_mesh_2.dxf")

Tutorial for Hatch

Create hatches with one boundary path

The simplest form of the Hatch entity has one polyline path with only straight lines as boundary path:

import ezdxf
# hatch requires DXF R2000 or later
doc = ezdxf.new("R2000")
msp = doc.modelspace()
# by default a solid fill hatch with fill color=7 (white/black)
hatch = msp.add_hatch(color=2)
# every boundary path is a 2D element
# vertex format for the polyline path is: (x, y[, bulge])
# there are no bulge values in this example
hatch.paths.add_polyline_path(


    [(0, 0), (10, 0), (10, 10), (0, 10)], is_closed=True
)
doc.saveas("solid_hatch_polyline_path.dxf")

But like all polyline entities the polyline path can also have bulge values:

import ezdxf
# hatch requires the DXF R2000 or later
doc = ezdxf.new("R2000")
msp = doc.modelspace()
# by default a solid fill hatch with fill color=7 (white/black)
hatch = msp.add_hatch(color=2)
# every boundary path is a 2D element
# vertex format for the polyline path is: (x, y[, bulge])
# bulge value 1 = an arc with diameter=10 (= distance to next vertex * bulge value)
# bulge value > 0 ... arc is right of line
# bulge value < 0 ... arc is left of line
hatch.paths.add_polyline_path(


    [(0, 0, 1), (10, 0), (10, 10, -0.5), (0, 10)], is_closed=True
)
doc.saveas("solid_hatch_polyline_path_with_bulge.dxf")

The most flexible way to define a boundary path is the edge path. An edge path can have multiple edges and each edge can be one of the following elements:

Create a solid hatch with an edge path (ellipse) as boundary path:

import ezdxf
# hatch requires the DXF R2000 or later
doc = ezdxf.new("R2000")
msp = doc.modelspace()
# important: major axis >= minor axis (ratio <= 1.)
# minor axis length = major axis length * ratio
msp.add_ellipse((0, 0), major_axis=(0, 10), ratio=0.5)
# by default a solid fill hatch with fill color=7 (white/black)
hatch = msp.add_hatch(color=2)
# every boundary path is a 2D element
edge_path = hatch.paths.add_edge_path()
# each edge path can contain line, arc, ellipse and spline elements
# important: major axis >= minor axis (ratio <= 1.)
edge_path.add_ellipse((0, 0), major_axis=(0, 10), ratio=0.5)
doc.saveas("solid_hatch_ellipse.dxf")

Create hatches with multiple boundary paths (islands)

The DXF attribute hatch_style defines the island detection style:

hatch = msp.add_hatch(


    color=1,


    dxfattribs={


        "hatch_style": ezdxf.const.HATCH_STYLE_NESTED,


        # 0 = nested: ezdxf.const.HATCH_STYLE_NESTED


        # 1 = outer: ezdxf.const.HATCH_STYLE_OUTERMOST


        # 2 = ignore: ezdxf.const.HATCH_STYLE_IGNORE


    },
)
# The first path has to set flag: 1 = external
# flag const.BOUNDARY_PATH_POLYLINE is added (OR) automatically
hatch.paths.add_polyline_path(


    [(0, 0), (10, 0), (10, 10), (0, 10)],


    is_closed=True,


    flags=ezdxf.const.BOUNDARY_PATH_EXTERNAL,
)

This is also the result for all 4 paths and hatch_style set to 2 (ignore). [image]

# The second path has to set flag: 16 = outermost
hatch.paths.add_polyline_path(


    [(1, 1), (9, 1), (9, 9), (1, 9)],


    is_closed=True,


    flags=ezdxf.const.BOUNDARY_PATH_OUTERMOST,
)

This is also the result for all 4 paths and hatch_style set to 1 (outer). [image]

# The third path has to set flag: 0 = default
hatch.paths.add_polyline_path(


    [(2, 2), (8, 2), (8, 8), (2, 8)],


    is_closed=True,


    flags=ezdxf.const.BOUNDARY_PATH_DEFAULT,
)

# The forth path has to set flag: 0 = default, and so on
hatch.paths.add_polyline_path(


    [(3, 3), (7, 3), (7, 7), (3, 7)],


    is_closed=True,


    flags=ezdxf.const.BOUNDARY_PATH_DEFAULT,
)
doc.saveas(OUTDIR / "solid_hatch_islands_04.dxf")

The expected result of combinations of various hatch_style values and paths flags, or the handling of overlapping paths is not documented by the DXF reference, so don’t ask me, ask Autodesk or just try it by yourself and post your experience in the forum.

Example for Edge Path Boundary

hatch = msp.add_hatch(color=1)
# 1. polyline path
hatch.paths.add_polyline_path(


    [


        (240, 210, 0),


        (0, 210, 0),


        (0, 0, 0.0),


        (240, 0, 0),


    ],


    is_closed=1,


    flags=ezdxf.const.BOUNDARY_PATH_EXTERNAL,
)
# 2. edge path
edge_path = hatch.paths.add_edge_path(flags=ezdxf.const.BOUNDARY_PATH_OUTERMOST)
edge_path.add_spline(


    control_points=[


        (126.658105895725, 177.0823706957212),


        (141.5497003747484, 187.8907860433995),


        (205.8997365206943, 154.7946313459515),


        (113.0168862297068, 117.8189380884978),


        (202.9816918983783, 63.17222935389572),


        (157.363511042264, 26.4621294342132),


        (144.8204003260554, 28.4383294369643),


    ],


    knot_values=[


        0.0,


        0.0,


        0.0,


        0.0,


        55.20174685732758,


        98.33239645153571,


        175.1126541251052,


        213.2061566683142,


        213.2061566683142,


        213.2061566683142,


        213.2061566683142,


    ],
)
edge_path.add_arc(


    center=(152.6378550678883, 128.3209356351659),


    radius=100.1880612627354,


    start_angle=94.4752130054052,


    end_angle=177.1345242028005,
)
edge_path.add_line(


    (52.57506282464041, 123.3124200796114),


    (126.658105895725, 177.0823706957212),
)

[image]

Associative Boundary Paths

A HATCH entity can be associative to a base geometry, which means if the base geometry is edited in a CAD application the HATCH get the same modification. Because ezdxf is not a CAD application, this association is not maintained nor verified by ezdxf, so if you modify the base geometry afterwards the geometry of the boundary path is not updated and no verification is done to check if the associated geometry matches the boundary path, this opens many possibilities to create invalid DXF files: USE WITH CARE.

This example associates a LWPOLYLINE entity to the hatch created from the LWPOLYLINE vertices:

# Create base geometry
lwpolyline = msp.add_lwpolyline(


    [(0, 0, 0), (10, 0, 0.5), (10, 10, 0), (0, 10, 0)],


    format="xyb",


    close=True,
)
hatch = msp.add_hatch(color=1)
path = hatch.paths.add_polyline_path(


    # get path vertices from associated LWPOLYLINE entity


    lwpolyline.get_points(format="xyb"),


    # get closed state also from associated LWPOLYLINE entity


    is_closed=lwpolyline.closed,
)
# Set association between boundary path and LWPOLYLINE
hatch.associate(path, [lwpolyline])

An EdgePath needs associations to all geometry entities forming the boundary path.

Predefined Hatch Pattern

Use predefined hatch pattern by name:

hatch.set_pattern_fill("ANSI31", scale=0.5)

Create hatches with gradient fill

TODO

Tutorial for Hatch Pattern Definition

TODO

Tutorial for Image and ImageDef

Insert a raster image into a DXF document, the raster image is NOT embedded in the DXF file:

import ezdxf
# The IMAGE entity requires the DXF R2000 format or later.
doc = ezdxf.new("R2000")
# The IMAGEDEF entity is like a block definition, it just defines the image.
my_image_def = doc.add_image_def(


    filename="mycat.jpg", size_in_pixel=(640, 360)
)
msp = doc.modelspace()
# The IMAGE entity is like the INSERT entity, it's just an image reference,
# and there can be multiple references to the same picture in a DXF document.
# 1st image reference
msp.add_image(


    insert=(2, 1),


    size_in_units=(6.4, 3.6),


    image_def=my_image_def,


    rotation=0
)
# 2nd image reference
msp.add_image(


    insert=(4, 5),


    size_in_units=(3.2, 1.8),


    image_def=my_image_def,


    rotation=30
)
# Get existing image definitions from the OBJECTS section:
image_defs = doc.objects.query("IMAGEDEF")
doc.saveas("dxf_with_cat.dxf")

Tutorial for Underlay and UnderlayDefinition

Insert a PDF, DWF, DWFx or DGN file as drawing underlay, the underlay file is NOT embedded into the DXF file:

import ezdxf
doc = ezdxf.new('AC1015')  # underlay requires the DXF R2000 format or later
my_underlay_def = doc.add_underlay_def(filename='my_underlay.pdf', name='1')
# The (PDF)DEFINITION entity is like a block definition, it just defines the underlay
# 'name' is misleading, because it defines the page/sheet to be displayed
# PDF: name is the page number to display
# DGN: name='default' ???
# DWF: ????
msp = doc.modelspace()
# add first underlay
msp.add_underlay(my_underlay_def, insert=(2, 1, 0), scale=0.05)
# The (PDF)UNDERLAY entity is like the INSERT entity, it creates an underlay reference,
# and there can be multiple references to the same underlay in a drawing.
msp.add_underlay(my_underlay_def, insert=(4, 5, 0), scale=.5, rotation=30)
# get existing underlay definitions, Important: UNDERLAYDEFs resides in the objects section
pdf_defs = doc.objects.query('PDFDEFINITION')  # get all pdf underlay defs in drawing
doc.saveas("dxf_with_underlay.dxf")

Tutorial for Linetypes

Simple line type example: [image]

You can define your own linetypes. A linetype definition has a name, a description and line pattern elements:

elements = [total_pattern_length, elem1, elem2, ...]

Create a new linetype definition:

import ezdxf
from ezdxf.tools.standards import linetypes  # some predefined linetypes
doc = ezdxf.new()
msp = doc.modelspace()
my_line_types = [


    (


        "DOTTED",


        "Dotted .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .",


        [0.2, 0.0, -0.2],


    ),


    (


        "DOTTEDX2",


        "Dotted (2x) .    .    .    .    .    .    .    . ",


        [0.4, 0.0, -0.4],


    ),


    (


        "DOTTED2",


        "Dotted (.5) . . . . . . . . . . . . . . . . . . . ",


        [0.1, 0.0, -0.1],


    ),
]
for name, desc, pattern in my_line_types:


    if name not in doc.linetypes:


        doc.linetypes.add(


            name=name,


            pattern=pattern,


            description=desc,


        )

Setup some predefined linetypes:

for name, desc, pattern in linetypes():


    if name not in doc.linetypes:


        doc.linetypes.add(


            name=name,


            pattern= pattern,


            description=desc,


        )

Check Available Linetypes

The linetypes object supports some standard Python protocols:

# iteration
print("available linetypes:")
for lt in doc.linetypes:


    print(f"{lt.dxf.name}: {lt.dxf.description}")
# check for existing linetype
if "DOTTED" in doc.linetypes:


    pass
count = len(doc.linetypes) # total count of linetypes

Removing Linetypes

WARNING:

You can delete a linetype:

doc.layers.remove("DASHED")

This just removes the linetype definition, the linetype attribute of DXF entities may still refer the reoved linetype definition “DASHED” and AutoCAD will not open DXF files including undefined linetypes.

Tutorial for Complex Linetypes

In DXF R13 Autodesk introduced complex linetypes, containing TEXT or SHAPES in line types.

Complex linetype example with text: [image]

Complex line type example with shapes: [image]

For easy usage the pattern string for complex line types is mostly the same string as the pattern definition strings in AutoCAD “.lin” files.

Example for complex line type TEXT:

doc = ezdxf.new("R2018")  # DXF R13 or later is required
doc.linetypes.add(


    name="GASLEITUNG2",


    # linetype definition string from acad.lin:


    pattern='A,.5,-.2,["GAS",STANDARD,S=.1,U=0.0,X=-0.1,Y=-.05],-.25',


    description= "Gasleitung2 ----GAS----GAS----GAS----GAS----GAS----",


    length=1,  # required for complex line types
})

The pattern always starts with an “A”, the following float values have the same meaning as for simple linetypes, a value > 0 is a line, a value < 0 is a gap, and a 0 is a point, the opening square bracket “[” starts the complex part of the linetype pattern.

The text after the “[” defines the complex linetype:

For complex TEXT linetypes the second parameter is the text style, for complex SHAPE linetypes the second parameter is the shape file name, the shape file has to be in the same directory as the DXF file or in one of the CAD application support paths.

The meaning of the following comple linetype parameters are shown in the table below:

These parameters are case insensitive and the closing square bracket “]” ends the complex part of the linetype pattern.

The fine tuning of this parameters is a try an error process, for complex TEXT linetypes the scaling factor (e.g. the STANDARD text style) sets the text height (e.g. “S=0.1” sets the text height to 0.1 units), by shifting in y-direction by half of the scaling factor, the text is vertically centered to the line. For the x-direction it seems to be a good practice to place a gap in front of the text and after the text, find x shifting value and gap sizes by try and error. The overall length is at least the sum of all line and gap definitions (absolute values).

Example for complex line type SHAPE:

doc.linetypes.add("GRENZE2",


    # linetype definition in acad.lin:


    # A,.25,-.1,[BOX,ltypeshp.shx,x=-.1,s=.1],-.1,1


    # replacing BOX by shape index 132 (got index from an AutoCAD file),


    # ezdxf can't get shape index from ltypeshp.shx


    pattern="A,.25,-.1,[132,ltypeshp.shx,x=-.1,s=.1],-.1,1",


    description="Grenze eckig ----[]-----[]----[]-----[]----[]--",


    length= 1.45,  # required for complex line types
})

Complex line types with shapes only work if the associated shape file (e. g. ltypeshp.shx) and the DXF file are in the same directory or the shape file is placed in one of the CAD application support folders.

Tutorial for OCS/UCS Usage

For OCS/UCS usage is a basic understanding of vectors required, for a brush up, watch the YouTube tutorials of 3Blue1Brown about Linear Algebra.

Second read the Coordinate Systems introduction please.

SEE ALSO:

For WCS there is not much to say as, it is what it is: the main world coordinate system, and a drawing unit can have any real world unit you want. Autodesk added some mechanism to define a scale for dimension and text entities, but because I am not an AutoCAD user, I am not familiar with it, and further more I think this is more an AutoCAD topic than a DXF topic.

Object Coordinate System (OCS)

The OCS is used to place planar 2D entities in 3D space. ALL points of a planar entity lay in the same plane, this is also true if the plane is located in 3D space by an OCS. There are three basic DXF attributes that gives a 2D entity its spatial form.

Extrusion

The extrusion vector defines the OCS, it is a normal vector to the base plane of a planar entity. This base plane is always located in the origin of the WCS. But there are some entities like Ellipse, which have an extrusion vector, but do not establish an OCS. For this entities the extrusion vector defines only the extrusion direction and thickness defines the extrusion distance, but all other points in WCS.

Elevation

The elevation value defines the z-axis value for all points of a planar entity, this is an OCS value, and defines the distance of the entity plane from the base plane.

This value exists only in output from DXF versions prior to R11 as separated DXF attribute (group code 38). In DXF R12 and later, the elevation value is supplied as z-axis value of each point. But as always in DXF, this simple rule does not apply to all entities: LWPolyline and Hatch have an DXF attribute elevation, where the z-axis of this point is the elevation height and the x-axis = y-axis = 0.

Thickness

Defines the extrusion distance for an entity.

NOTE:

Placing 2D Circle in 3D Space

The colors for axis follow the AutoCAD standard:

import ezdxf
from ezdxf.math import OCS
doc = ezdxf.new('R2010')
msp = doc.modelspace()
# For this example the OCS is rotated around x-axis about 45 degree
# OCS z-axis: x=0, y=1, z=1
# extrusion vector must not normalized here
ocs = OCS((0, 1, 1))
msp.add_circle(


    # You can place the 2D circle in 3D space


    # but you have to convert WCS into OCS


    center=ocs.from_wcs((0, 2, 2)),


    # center in OCS: (0.0, 0.0, 2.82842712474619)


    radius=1,


    dxfattribs={


        # here the extrusion vector should be normalized,


        # which is granted by using the ocs.uz


        'extrusion': ocs.uz,


        'color': 1,


    })
# mark center point of circle in WCS
msp.add_point((0, 2, 2), dxfattribs={'color': 1})

The following image shows the 2D circle in 3D space in AutoCAD Left and Front view. The blue line shows the OCS z-axis (extrusion direction), elevation is the distance from the origin to the center of the circle in this case 2.828, and you see that the x- and y-axis of OCS and WCS are not aligned. [image: circle in ocs as side view] [image] [image: circle in ocs as front view] [image]

Placing LWPolyline in 3D Space

For simplicity of calculation I use the UCS class in this example to place a 2D pentagon in 3D space.

# The center of the pentagon should be (0, 2, 2), and the shape is
# rotated around x-axis about 45 degree, to accomplish this I use an
# UCS with z-axis (0, 1, 1) and an x-axis parallel to WCS x-axis.
ucs = UCS(


    origin=(0, 2, 2),  # center of pentagon


    ux=(1, 0, 0),  # x-axis parallel to WCS x-axis


    uz=(0, 1, 1),  # z-axis
)
# calculating corner points in local (UCS) coordinates
points = [Vec3.from_deg_angle((360 / 5) * n) for n in range(5)]
# converting UCS into OCS coordinates
ocs_points = list(ucs.points_to_ocs(points))
# LWPOLYLINE accepts only 2D points and has an separated DXF attribute elevation.
# All points have the same z-axis (elevation) in OCS!
elevation = ocs_points[0].z
msp.add_lwpolyline(


    points=ocs_points,


    format='xy',  # ignore z-axis


    close=True,


    dxfattribs={


        'elevation': elevation,


        'extrusion': ucs.uz,


        'color': 1,


    })

The following image shows the 2D pentagon in 3D space in AutoCAD Left, Front and Top view. The three lines from the center of the pentagon show the UCS, the three colored lines in the origin show the OCS the white lines in the origin show the WCS.

The z-axis of the UCS and the OCS show the same direction (extrusion direction), and the x-axis of the UCS and the WCS show the same direction. The elevation is the distance from the origin to the center of the pentagon and all points of the pentagon have the same elevation, and you see that the y- axis of UCS, OCS and WCS are not aligned. [image: pentagon in ucs as side view] [image] [image: pentagon in ucs as front view] [image]

Using UCS to Place 3D Polyline

It is much simpler to use a 3D Polyline to create the 3D pentagon. The UCS class is handy for this example and all kind of 3D operations.

# Using an UCS simplifies 3D operations, but UCS definition can happen later
# calculating corner points in local (UCS) coordinates without Vec3 class
angle = math.radians(360 / 5)
corners_ucs = [(math.cos(angle * n), math.sin(angle * n), 0) for n in range(5)]
# let's do some transformations
tmatrix = Matrix44.chain(  # creating a transformation matrix


    Matrix44.z_rotate(math.radians(15)),  # 1. rotation around z-axis


    Matrix44.translate(0, .333, .333),  # 2. translation
)
transformed_corners_ucs = tmatrix.transform_vertices(corners_ucs)
# transform UCS into WCS
ucs = UCS(


    origin=(0, 2, 2),  # center of pentagon


    ux=(1, 0, 0),  # x-axis parallel to WCS x-axis


    uz=(0, 1, 1),  # z-axis
)
corners_wcs = list(ucs.points_to_wcs(transformed_corners_ucs))
msp.add_polyline3d(


    points=corners_wcs,


    close=True,
)
# add lines from center to corners
center_wcs = ucs.to_wcs((0, .333, .333))
for corner in corners_wcs:


    msp.add_line(center_wcs, corner, dxfattribs={'color': 1})
ucs.render_axis(msp)

Placing 2D Text in 3D Space

The problem by placing text in 3D space is the text rotation, which is always counter clockwise around the OCS z-axis, and 0 degree is in direction of the positive OCS x-axis, and the OCS x-axis is calculated by the Arbitrary Axis Algorithm.

Calculate the OCS rotation angle by converting the TEXT rotation angle (in UCS or WCS) into a vector or begin with text direction as vector, transform this direction vector into OCS and convert the OCS vector back into an angle in the OCS xy-plane (see example), this procedure is available as UCS.to_ocs_angle_deg() or UCS.to_ocs_angle_rad().

AutoCAD supports thickness for the TEXT entity only for .shx fonts and not for true type fonts.

# Thickness for text works only with shx fonts not with true type fonts
doc.styles.new('TXT', dxfattribs={'font': 'romans.shx'})
ucs = UCS(origin=(0, 2, 2), ux=(1, 0, 0), uz=(0, 1, 1))
# calculation of text direction as angle in OCS:
# convert text rotation in degree into a vector in UCS
text_direction = Vec3.from_deg_angle(-45)
# transform vector into OCS and get angle of vector in xy-plane
rotation = ucs.to_ocs(text_direction).angle_deg
text = msp.add_text(


    text="TEXT",


    dxfattribs={


        # text rotation angle in degrees in OCS


        'rotation': rotation,


        'extrusion': ucs.uz,


        'thickness': .333,


        'color': 1,


        'style': 'TXT',


    })
# set text position in OCS
text.set_pos(ucs.to_ocs((0, 0, 0)), align='MIDDLE_CENTER')

HINT:

Placing 2D Arc in 3D Space

Here we have the same problem as for placing text, you need the start and end angle of the arc in degrees in OCS, and this example also shows a shortcut for calculating the OCS angles.

ucs = UCS(origin=(0, 2, 2), ux=(1, 0, 0), uz=(0, 1, 1))
msp.add_arc(


    center=ucs.to_ocs((0, 0)),


    radius=1,


    start_angle=ucs.to_ocs_angle_deg(45),


    end_angle=ucs.to_ocs_angle_deg(270),


    dxfattribs={


        'extrusion': ucs.uz,


        'color': 1,


    })
center = ucs.to_wcs((0, 0))
msp.add_line(


    start=center,


    end=ucs.to_wcs(Vec3.from_deg_angle(45)),


    dxfattribs={'color': 1},
)
msp.add_line(


    start=center,


    end=ucs.to_wcs(Vec3.from_deg_angle(270)),


    dxfattribs={'color': 1},
)

Placing Block References in 3D Space

Despite the fact that block references (Insert) can contain true 3D entities like Line or Mesh, the Insert entity uses the same placing principe as Text or Arc shown in the previous chapters.

Simple placing by OCS and rotation about the z-axis, can be achieved the same way as for generic 2D entity types. The DXF attribute Insert.dxf.rotation rotates a block reference around the block z-axis, which is located in the Block.dxf.base_point. To rotate the block reference around the WCS x-axis, a transformation of the block z-axis into the WCS x-axis is required by rotating the block z-axis 90 degree counter clockwise around y-axis by using an UCS:

This is just an excerpt of the important parts, see the whole code of insert.py at github.

# rotate UCS around an arbitrary axis:
def ucs_rotation(ucs: UCS, axis: Vec3, angle: float):


    # new in ezdxf v0.11: UCS.rotate(axis, angle)


    t = Matrix44.axis_rotate(axis, math.radians(angle))


    ux, uy, uz = t.transform_vertices([ucs.ux, ucs.uy, ucs.uz])


    return UCS(origin=ucs.origin, ux=ux, uy=uy, uz=uz)
doc = ezdxf.new('R2010', setup=True)
blk = doc.blocks.new('CSYS')
setup_csys(blk)
msp = doc.modelspace()
ucs = ucs_rotation(UCS(), axis=Y_AXIS, angle=90)
# transform insert location to OCS
insert = ucs.to_ocs((0, 0, 0))
# rotation angle about the z-axis (= WCS x-axis)
rotation = ucs.to_ocs_angle_deg(15)
msp.add_blockref('CSYS', insert, dxfattribs={


   'extrusion': ucs.uz,


   'rotation': rotation,
})

To rotate a block reference around another axis than the block z-axis, you have to find the rotated z-axis (extrusion vector) of the rotated block reference, following example rotates the block reference around the block x-axis by 15 degrees:

# t is a transformation matrix to rotate 15 degree around the x-axis
t = Matrix44.axis_rotate(axis=X_AXIS, angle=math.radians(15))
# transform block z-axis into new UCS z-axis (= extrusion vector)
uz = Vec3(t.transform(Z_AXIS))
# create new UCS at the insertion point, because we are rotating around the x-axis,
# ux is the same as the WCS x-axis and uz is the rotated z-axis.
ucs = UCS(origin=(1, 2, 0), ux=X_AXIS, uz=uz)
# transform insert location to OCS, block base_point=(0, 0, 0)
insert = ucs.to_ocs((0, 0, 0))
# for this case a rotation around the z-axis is not required
rotation = 0
blockref = msp.add_blockref('CSYS', insert, dxfattribs={


    'extrusion': ucs.uz,


    'rotation': rotation,
})

The next example shows how to translate a block references with an already established OCS:

# translate a block references with an established OCS
translation = Vec3(-3, -1, 1)
# get established OCS
ocs = blockref.ocs()
# get insert location in WCS
actual_wcs_location = ocs.to_wcs(blockref.dxf.insert)
# translate location
new_wcs_location = actual_wcs_location + translation
# convert WCS location to OCS location
blockref.dxf.insert = ocs.from_wcs(new_wcs_location)

Setting a new insert location is the same procedure without adding a translation vector, just transform the new insert location into the OCS. [image] [image]

The next operation is to rotate a block reference with an established OCS, rotation axis is the block y-axis, rotation angle is -90 degrees. First transform block y-axis (rotation axis) and block z-axis (extrusion vector) from OCS into WCS:

# rotate a block references with an established OCS around the block y-axis about 90 degree
ocs = blockref.ocs()
# convert block y-axis (= rotation axis) into WCS vector
rotation_axis = ocs.to_wcs((0, 1, 0))
# convert local z-axis (=extrusion vector) into WCS vector
local_z_axis = ocs.to_wcs((0, 0, 1))

Build transformation matrix and transform extrusion vector and build new UCS:

# build transformation matrix
t = Matrix44.axis_rotate(axis=rotation_axis, angle=math.radians(-90))
uz = t.transform(local_z_axis)
uy = rotation_axis
# the block reference origin stays at the same location, no rotation needed
wcs_insert = ocs.to_wcs(blockref.dxf.insert)
# build new UCS to convert WCS locations and angles into OCS
ucs = UCS(origin=wcs_insert, uy=uy, uz=uz)

Set new OCS attributes, we also have to set the rotation attribute even though we do not rotate the block reference around the local z-axis, the new block x-axis (0 deg) differs from OCS x-axis and has to be adjusted:

# set new OCS
blockref.dxf.extrusion = ucs.uz
# set new insert
blockref.dxf.insert = ucs.to_ocs((0, 0, 0))
# set new rotation: we do not rotate the block reference around the local z-axis,
# but the new block x-axis (0 deg) differs from OCS x-axis and has to be adjusted
blockref.dxf.rotation = ucs.to_ocs_angle_deg(0)

And here is the point, where my math knowledge ends, for more advanced CAD operation you have to look elsewhere.

Tutorial for UCS Based Transformations

With ezdxf v0.11 a new feature for entity transformation was introduced, which makes working with OCS/UCS much easier, this is a new edition of the older Tutorial for OCS/UCS Usage. For the basic information read the old tutorial please. In ezdxf v0.13 the transform_to_wcs() interface was replaced by the general transformation interface: transform().

For this tutorial we don’t have to worry about the OCS and the extrusion vector, this is done automatically by the transform() method of each DXF entity.

Placing 2D Circle in 3D Space

To recreate the situation of the old tutorial instantiate a new UCS and rotate it around the local x-axis. Use UCS coordinates to place the 2D CIRCLE in 3D space, and transform the UCS coordinates to the WCS.

import math
import ezdxf
from ezdxf.math import UCS
doc = ezdxf.new('R2010')
msp = doc.modelspace()
ucs = UCS()  # New default UCS
# All rotation angles in radians, and rotation
# methods always return a new UCS.
ucs = ucs.rotate_local_x(math.radians(-45))
circle = msp.add_circle(


    # Use UCS coordinates to place the 2d circle in 3d space


    center=(0, 0, 2),


    radius=1,


    dxfattribs={'color': 1}
)
circle.transform(ucs.matrix)
# mark center point of circle in WCS
msp.add_point((0, 0, 2), dxfattribs={'color': 1}).transform(ucs.matrix)

Placing LWPolyline in 3D Space

Simplified LWPOLYLINE example:

# The center of the pentagon should be (0, 2, 2), and the shape is
# rotated around x-axis about -45 degree
ucs = UCS(origin=(0, 2, 2)).rotate_local_x(math.radians(-45))
msp.add_lwpolyline(


    # calculating corner points in UCS coordinates


    points=(Vec3.from_deg_angle((360 / 5) * n) for n in range(5)),


    format='xy',  # ignore z-axis


    close=True,


    dxfattribs={


        'color': 1,


    }

The 2D pentagon in 3D space in BricsCAD Left and Front view. [image: pentagon in ucs as side view] [image] [image: pentagon in ucs as front view] [image]

Using UCS to Place 3D Polyline

Simplified POLYLINE example: Using a first UCS to transform the POLYLINE and a second UCS to place the POLYLINE in 3D space.

# using an UCS simplifies 3D operations, but UCS definition can happen later
# calculating corner points in local (UCS) coordinates without Vec3 class
angle = math.radians(360 / 5)
corners_ucs = [(math.cos(angle * n), math.sin(angle * n), 0) for n in range(5)]
# let's do some transformations by UCS
transformation_ucs = UCS().rotate_local_z(math.radians(15))  # 1. rotation around z-axis
transformation_ucs.shift((0, .333, .333))  # 2. translation (inplace)
corners_ucs = list(transformation_ucs.points_to_wcs(corners_ucs))
location_ucs = UCS(origin=(0, 2, 2)).rotate_local_x(math.radians(-45))
msp.add_polyline3d(


    points=corners_ucs,


    close=True,


    dxfattribs={


        'color': 1,


    }
).transform(location_ucs.matrix)
# Add lines from the center of the POLYLINE to the corners
center_ucs = transformation_ucs.to_wcs((0, 0, 0))
for corner in corners_ucs:


    msp.add_line(


        center_ucs, corner, dxfattribs={'color': 1}


    ).transform(location_ucs.matrix)

Placing 2D Text in 3D Space

The problem with the text rotation in the old tutorial disappears (or better it is hidden in transform()) with the new UCS based transformation method:

AutoCAD supports thickness for the TEXT entity only for .shx fonts and not for true type fonts.

# thickness for text works only with shx fonts not with true type fonts
doc.styles.new('TXT', dxfattribs={'font': 'romans.shx'})
ucs = UCS(origin=(0, 2, 2)).rotate_local_x(math.radians(-45))
text = msp.add_text(


    text="TEXT",


    dxfattribs={


        # text rotation angle in degrees in UCS


        'rotation': -45,


        'thickness': .333,


        'color': 1,


        'style': 'TXT',


    }
)
# set text position in UCS
text.set_pos((0, 0, 0), align='MIDDLE_CENTER')
text.transform(ucs.matrix)

Placing 2D Arc in 3D Space

Same as for the text example, OCS angle transformation can be ignored:

ucs = UCS(origin=(0, 2, 2)).rotate_local_x(math.radians(-45))
CENTER = (0, 0)
START_ANGLE = 45
END_ANGLE = 270
msp.add_arc(


    center=CENTER,


    radius=1,


    start_angle=START_ANGLE,


    end_angle=END_ANGLE,


    dxfattribs={'color': 6},
).transform(ucs.matrix)
msp.add_line(


    start=CENTER,


    end=Vec3.from_deg_angle(START_ANGLE),


    dxfattribs={'color': 6},
).transform(ucs.matrix)
msp.add_line(


    start=CENTER,


    end=Vec3.from_deg_angle(END_ANGLE),


    dxfattribs={'color': 6},
).transform(ucs.matrix)

Placing Block References in 3D Space

Despite the fact that block references (INSERT) can contain true 3D entities like LINE or MESH, the INSERT entity uses the same placing principe as TEXT or ARC shown in the previous chapters.

To rotate the block reference 15 degrees around the WCS x-axis, we place the block reference in the origin of the UCS, and rotate the UCS 90 degrees around its local y-axis, to align the UCS z-axis with the WCS x-axis:

This is just an excerpt of the important parts, see the whole code of insert.py at github.

doc = ezdxf.new('R2010', setup=True)
blk = doc.blocks.new('CSYS')
setup_csys(blk)
msp = doc.modelspace()
ucs = UCS().rotate_local_y(angle=math.radians(90))
msp.add_blockref(


    'CSYS',


    insert=(0, 0),


    # rotation around the block z-axis (= WCS x-axis)


    dxfattribs={'rotation': 15},
).transform(ucs.matrix)

A more simple approach is to ignore the rotate attribute at all and just rotate the UCS. To rotate a block reference around any axis rather than the block z-axis, rotate the UCS into the desired position. Following example rotates the block reference around the block x-axis by 15 degrees:

ucs = UCS(origin=(1, 2, 0)).rotate_local_x(math.radians(15))
blockref = msp.add_blockref('CSYS', insert=(0, 0, 0))
blockref.transform(ucs.matrix)

The next example shows how to translate a block references with an already established OCS:

# New UCS at the translated location, axis aligned to the WCS
ucs = UCS((-3, -1, 1))
# Transform an already placed block reference, including
# the transformation of the established OCS.
blockref.transform(ucs.matrix)

The next operation is to rotate a block reference with an established OCS, rotation axis is the block y-axis, rotation angle is -90 degrees. The idea is to create an UCS in the origin of the already placed block reference, UCS axis aligned to the block axis and resetting the block reference parameters for a new WCS transformation.

# Get UCS at the block reference insert location, UCS axis aligned
# to the block axis.
ucs = blockref.ucs()
# Rotate UCS around the local y-axis.
ucs = ucs.rotate_local_y(math.radians(-90))

Reset block reference parameters, this places the block reference in the UCS origin and aligns the block axis to the UCS axis, now we do a new transformation from UCS to WCS:

# Reset block reference parameters to place block reference in
# UCS origin, without any rotation and OCS.
blockref.reset_transformation()
# Transform block reference from UCS to WCS
blockref.transform(ucs.matrix)

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:

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")

[image]

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

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")

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")

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:

msp.add_linear_dim(


    base=(3, 2), p1=(0, 0), p2=(3, 0), override={"dimjust": 1}
).render()

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

msp.add_linear_dim(


    base=(3, 2), p1=(0, 0), p2=(3, 0), override={"dimtad": 4}
).render()

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()

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()

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()

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()

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

msp.add_linear_dim(


    base=(3, 2),


    p1=(3, 0),


    p2=(6, 0),


    override={


        "dimtxsty": "Standard",


        "dimtxt": 0.35,


        "dimclrt": 1,


    }
).render()

[image]

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.

msp.add_linear_dim(


    base=(3, 2),


    p1=(3, 0),


    p2=(6, 0),


    override={


        "dimtfill": 2,


        "dimtfillclr": 1,


    }
).render()

[image]

Text Formatting

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()

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.

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()

[image]

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.

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()

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()

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()

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()

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:

Arrow Shapes

[image]

Arrow Names

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

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()

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()

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:

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()

Alternative Units

Alternative units are not supported.

Tutorial for Radius Dimensions

Please read the Tutorial for Linear Dimensions before, if you haven’t.

NOTE:

import ezdxf
# DXF R2010 drawing, official DXF version name: 'AC1024',
# setup=True setups the default dimension styles
doc = ezdxf.new("R2010", setup=True)
msp = doc.modelspace()  # add new dimension entities to the modelspace
msp.add_circle((0, 0), radius=3)  # add a CIRCLE entity, not required
# add default radius dimension, measurement text is located outside
dim = msp.add_radius_dim(


    center=(0, 0), radius=3, angle=45, dimstyle="EZ_RADIUS"
)
# necessary second step, to create the BLOCK entity with the dimension geometry.
dim.render()
doc.saveas("radius_dimension.dxf")

The example above creates a 45 degrees slanted radius Dimension entity, the default dimension style “EZ_RADIUS” is defined as 1 drawing unit = 1m, drawing scale = 1:100 and the length factor = 100, which creates a measurement text in cm, the default location for the measurement text is outside of the circle.

The center point defines the center of the circle but there doesn’t have to exist a circle entity, radius defines the circle radius, which is also the measurement, and angle defines the slope of the dimension line, it is also possible to define the circle by a measurement point mpoint on the circle.

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

Placing Measurement Text

There are different predefined DIMSTYLES to achieve various text placing locations.

The basic DIMSTYLE “EZ_RADIUS” settings are:

NOTE:

SEE ALSO:

Default Text Locations Outside

Advanced “EZ_RADIUS” settings for placing the text outside of the circle:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS"
)
dim.render()  # always required, but not shown in the following examples

[image]

To force text outside horizontal set dimtoh to 1:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS",


    override={"dimtoh": 1}
)

Default Text Locations Inside

DIMSTYLE “EZ_RADIUS_INSIDE” can be used to place the dimension text inside the circle at a default location.

The basic DIMSTYLE “EZ_RADIUS_INSIDE” settings are:

Advanced “EZ_RADIUS_INSIDE” settings to place (force) the text inside of the circle:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS_INSIDE"
)

To force text inside horizontal set dimtih to 1:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS_INSIDE",


    override={"dimtih": 1}
)

User Defined Text Locations

Beside the default location it is always possible to override the text location by a user defined location. This location also determines the angle of the dimension line and overrides the argument angle. For user defined locations it is not necessary to force text inside (dimtix=1), because the location of the text is explicit given, therefore the DIMSTYLE “EZ_RADIUS” can be used for all this examples.

User defined location outside of the circle:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    location=(4, 4),


    dimstyle="EZ_RADIUS"
)

User defined location outside of the circle and forced horizontal text:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    location=(4, 4),


    dimstyle="EZ_RADIUS",


    override={"dimtoh": 1}
)

User defined location inside of the circle:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    location=(1, 1),


    dimstyle="EZ_RADIUS"
)

User defined location inside of the circle and forced horizontal text:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    location=(1, 1),


    dimstyle="EZ_RADIUS",


    override={"dimtih": 1},
)

Center Mark/Lines

Center mark/lines are controlled by dimcen, default value is 0 for predefined dimstyles “EZ_RADIUS” and “EZ_RADIUS_INSIDE”:

dim = msp.add_radius_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS",


    override={"dimcen": 0.25},
)

[image]

Overriding Measurement Text

See Linear Dimension Tutorial: Overriding Measurement Text

Measurement Text Formatting and Styling

See Linear Dimension Tutorial: Measurement Text Formatting and Styling

Tutorial for Diameter Dimensions

Please read the Tutorial for Radius Dimensions before, if you haven’t.

NOTE:

This is a repetition of the radius tutorial, just with diameter dimensions.

import ezdxf
# setup=True setups the default dimension styles
doc = ezdxf.new("R2010", setup=True)
msp = doc.modelspace()  # add new dimension entities to the modelspace
msp.add_circle((0, 0), radius=3)  # add a CIRCLE entity, not required
# add default diameter dimension, measurement text is located outside
dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=3,


    angle=45,


    dimstyle="EZ_RADIUS"
)
dim.render()
doc.saveas("diameter_dimension.dxf")

The example above creates a 45 degrees slanted diameter Dimension entity, the default dimension style “EZ_RADIUS” (same as for radius dimensions) is defined as 1 drawing unit = 1m, drawing scale = 1:100 and the length factor = 100, which creates a measurement text in cm, the default location for the measurement text is outside of the circle.

The center point defines the center of the circle but there doesn’t have to exist a circle entity, radius defines the circle radius and angle defines the slope of the dimension line, it is also possible to define the circle by a measurement point mpoint on the circle.

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

Placing Measurement Text

There are different predefined DIMSTYLES to achieve various text placing locations.

The basic DIMSTYLE “EZ_RADIUS” settings are:

NOTE:

SEE ALSO:

Default Text Locations Outside

“EZ_RADIUS” default settings for to place text outside:

dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS"
)
dim.render()  # always required, but not shown in the following examples

[image]

To force text outside horizontal set dimtoh to 1:

dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS",


    override={"dimtoh": 1}
)

Default Text Locations Inside

DIMSTYLE “EZ_RADIUS_INSIDE” can be used to place the dimension text inside the circle at a default location.

The basic DIMSTYLE settings are:

Advanced “EZ_RADIUS_INSIDE” settings to place (force) the text inside of the circle:

dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS_INSIDE"
)

To force text inside horizontal set dimtih to 1:

dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=2.5,


    angle=45,


    dimstyle="EZ_RADIUS_INSIDE",


    override={"dimtih": 1}
)

User Defined Text Locations

Beside the default location it is always possible to override the text location by a user defined location. This location also determines the angle of the dimension line and overrides the argument angle. For user defined locations it is not necessary to force text inside (dimtix=1), because the location of the text is explicit given, therefore the DIMSTYLE “EZ_RADIUS” can be used for all this examples.

User defined location outside of the circle:

dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=2.5,


    location=(4, 4),


    dimstyle="EZ_RADIUS"
)

User defined location outside of the circle and forced horizontal text:

dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=2.5,


    location=(4, 4),


    dimstyle="EZ_RADIUS",


    override={"dimtoh": 1}
)

User defined location inside of the circle:

dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=2.5,


    location=(1, 1),


    dimstyle="EZ_RADIUS"
)

User defined location inside of the circle and forced horizontal text:

dim = msp.add_diameter_dim(


    center=(0, 0),


    radius=2.5,


    location=(1, 1),


    dimstyle="EZ_RADIUS",


    override={"dimtih": 1},
)

Center Mark/Lines

See Radius Dimension Tutorial: Center Mark/Lines

Overriding Measurement Text

See Linear Dimension Tutorial: Overriding Measurement Text

Measurement Text Formatting and Styling

See Linear Dimension Tutorial: Measurement Text Formatting and Styling

Tutorial for Angular Dimensions

Please read the Tutorial for Linear Dimensions before, if you haven’t.

NOTE:

Dimension Style “EZ_CURVED”

All factory methods to create angular dimensions uses the dimension style “EZ_CURVED” for curved dimension lines which is defined as:

This DIMENSION style only exist if the argument setup is True for creating a new DXF document by ezdxf.new(). 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).

Add all ezdxf specific resources (line types, text- and dimension styles) to an existing DXF document:

import ezdxf
from ezdxf.tools.standards import setup_drawing
doc = ezdxf.readfile("your.dxf")
setup_drawing(doc, topics="all")

Factory Methods to Create Angular Dimensions

Defined by Center, Radius and Angles

The first example shows an angular dimension defined by the center point, radius, start- and end angles:

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 entities to the modelspace:
msp = doc.modelspace()
# Add an angular DIMENSION defined by the center point, start- and end angles,
# the measurement text is placed at the default location above the dimension
# line:
dim = msp.add_angular_dim_cra(


    center=(5, 5),  # center point of the angle


    radius= 7,  # distance from center point to the start of the extension lines


    start_angle=60,  # start angle in degrees


    end_angle=120,  # end angle in degrees


    distance=3,  # distance from start of the extension lines to the dimension line


    dimstyle="EZ_CURVED",  # default angular 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("angular_dimension_cra.dxf")

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

Angle by 2 Lines

The next example shows an angular dimension for an angle defined by two lines:

import ezdxf
doc = ezdxf.new(setup=True)
msp = doc.modelspace()
# Setup the geometric parameters for the DIMENSION entity:
base = (5.8833, -6.3408)  # location of the dimension line
p1 = (2.0101, -7.5156)  # start point of 1st leg
p2 = (2.7865, -10.4133)  # end point of 1st leg
p3 = (6.7054, -7.5156)  # start point of 2nd leg
p4 = (5.9289, -10.4133)  # end point of 2nd leg
# Draw the lines for visualization, not required to create the
# DIMENSION entity:
msp.add_line(p1, p2)
msp.add_line(p3, p4)
# Add an angular DIMENSION defined by two lines, the measurement text is
# placed at the default location above the dimension line:
dim = msp.add_angular_dim_2l(


    base=base,  # defines the location of the dimension line


    line1=(p1, p2),  # start leg of the angle


    line2=(p3, p4),  # end leg of the angle


    dimstyle="EZ_CURVED",  # default angular dimension style
)
# Necessary second step to create the dimension line geometry:
dim.render()
doc.saveas("angular_dimension_2l.dxf")

The example above creates an angular Dimension entity to measures the angle between two lines (line1 and line2).

The base point defines the location of the dimension line (arc), any point on the dimension line is valid. The points p1 and p2 define the first leg of the angle, p1 also defines the start point of the first extension line. The points p3 and p4 define the second leg of the angle and point p3 also defines the start point of the second extension line.

The measurement of the DIMENSION entity is the angle enclosed by the first and the second leg and where the dimension line passes the base point. [image]

Angle by 3 Points

The next example shows an angular dimension defined by three points, a center point and the two end points of the angle legs:

import ezdxf
doc = ezdxf.new(setup=True)
msp = doc.modelspace()
msp.add_angular_dim_3p(


    base=(0, 7),  # location of the dimension line


    center=(0, 0),  # center point


    p1=(-3, 5),  # end point of 1st leg = start angle


    p2=(3, 5),  # end point of 2nd leg = end angle
).render()

Angle from ConstructionArc

The ezdxf.math.ConstructionArc provides various class methods for creating arcs and the construction tool can be created from an ARC entity.

Add an angular dimension to an ARC entity:

import ezdxf
doc = ezdxf.new(setup=True)
msp = doc.modelspace()
arc = msp.add_arc(


    center=(0, 0),


    radius=5,


    start_angle = 60,


    end_angle = 120,
)
msp.add_angular_dim_arc(


    arc.construction_tool(),


    distance=2,
).render()

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.

NOTE:

SEE ALSO:

Default Text Locations

The DIMSTYLE “EZ_CURVED” places the measurement text in the center of the angle above the dimension line. The first examples above show the measurement text at the default text location.

The text direction angle is always perpendicular to the line from the text center to the center point of the angle unless this angle is manually overridden.

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

msp.add_angular_dim_cra(


    center=(3, 3),


    radius=3,


    distance=1,


    start_angle=60,


    end_angle=120,


    override={


        "dimtad": 1,  # 0=center; 1=above; 4=below;


    },
).render()

Arrows and measurement text are placed “outside” automatically if the available space between the extension lines isn’t sufficient. This overrides the dimtad value by 1 (“above”). Ezdxf follows its own rules, ignores the dimatfit attribute and works similar to dimatfit = 1, move arrows first, then text: [image]

Shift Text From Default Location

The method shift_text() shifts the measurement text away from the default location. The shifting direction is aligned to the text rotation of the default measurement text.

dim = msp.add_angular_dim_cra(


    center=(3, 3),


    radius=3,


    distance=1,


    start_angle=60,


    end_angle=120,
)
# shift text from default text location:
dim.shift_text(0.5, 1.0)
dim.render()

This is just a rendering effect, editing the dimension line in a CAD application resets the text to the default location.

User Defined Text Locations

Beside the default location it is always possible to override the text location by a user defined location.

The coordinates of user locations are located in the rendering UCS and the default rendering UCS is the WCS.

Absolute User Location

Absolute placing of the measurement text means relative to the origin of the render UCS. The user location is stored in the DIMENSION entity, which means editing the dimension line in a CAD application does not alter the text location. This location also determines the rotation of the measurement text.

dim = msp.add_angular_dim_cra(


    center=(3, 3),


    radius=3,


    distance=1,


    start_angle=60,


    end_angle=120,


    location=(5, 8),  # user defined measurement text location
)
dim.render()

Relative User Location

Relative placing of the measurement text means relative to the middle of the dimension line. This is only possible by calling the set_location() method, and the argument relative has to be True. The user location is stored in the DIMENSION entity, which means editing the dimension line in a CAD application does not alter the text location. This location also determines the rotation of the measurement text.

dim = msp.add_angular_dim_cra(


    center=(3, 3),


    radius=3,


    distance=1,


    start_angle=60,


    end_angle=120,
)
dim.set_location((1, 2), relative=True)
dim.render()

Adding a Leader

The method set_location() has the option to add a leader line to the measurement text. This also aligns the text rotation to the render UCS x-axis, this means in the default case the measurement text is horizontal. The leader line can be “below” the text or start at the “left” or “right” center of the text, this location is defined by the dimtad attribute, 0 means “center” and any value != 0 means “below”.

for dimtad, x in [(0, 0), (4, 6)]:


    dim = msp.add_angular_dim_cra(


        center=(3 + x, 3),


        radius=3,


        distance=1,


        start_angle=60,


        end_angle=120,


        override={"dimtad": dimtad}  # "center" == 0; "below" != 0;


    )


    dim.set_location((1, 2), relative=True, leader=True)


    dim.render()

Advanced version which calculates the relative text location: The user location vector has a length 2 and the orientation is defined by center_angle pointing away from the center of the angle.

import ezdxf
from ezdxf.math import Vec3
doc = ezdxf.new(setup=True)
msp = doc.modelspace()
for dimtad, y, leader in [


    [0, 0, False],


    [0, 7, True],


    [4, 14, True],
]:


    for x, center_angle in [


        (0, 0), (7, 45), (14, 90), (21, 135), (26, 225), (29, 270)


    ]:


        dim = msp.add_angular_dim_cra(


            center=(x, y),


            radius=3.0,


            distance=1.0,


            start_angle=center_angle - 15.0,


            end_angle=center_angle + 15.0,


            override={"dimtad": dimtad},


        )


        # The user location is relative to the center of the dimension line:


        usr_location = Vec3.from_deg_angle(angle=center_angle, length=2.0)


        dim.set_location(usr_location, leader=leader, relative=True)


        dim.render()

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).

This example uses a relative text location without a leader and forces the text rotation to 90 degrees:

for x, center_angle in [(7, 45), (14, 90), (21, 135)]:


    dim = msp.add_angular_dim_cra(


        center=(x, 0),


        radius=3.0,


        distance=1.0,


        start_angle=center_angle - 15.0,


        end_angle=center_angle + 15.0,


        text_rotation=90,  # vertical text


    )


    usr_location = Vec3.from_deg_angle(angle=center_angle, length=1.0)


    dim.set_location(usr_location, leader=False, relative=True)


    dim.render()

Angular Units

Angular units are set by dimaunit:

d1 = 15
d2 = 15.59031944
for x, (dimaunit, dimadec) in enumerate(


    [


        (0, 4),


        (1, 7),


        (2, 4),


        (3, 4),


    ]
):


    dim = msp.add_angular_dim_cra(


        center=(x * 4.0, 0.0),


        radius=3.0,


        distance=1.0,


        start_angle=90.0 - d1,


        end_angle=90.0 + d2,


        override={


            "dimaunit": dimaunit,


            "dimadec": dimadec,


        },


    )


    dim.render()

[image] [image]

Overriding Measurement Text

See Linear Dimension Tutorial: Overriding Measurement Text

Measurement Text Formatting and Styling

See Linear Dimension Tutorial: Measurement Text Formatting and Styling

Tolerances and Limits

See Linear Dimension Tutorial: Tolerances and Limits

Tutorial for Arc Dimensions

Please read the Tutorial for Linear Dimensions before, if you haven’t. This is a repetition of the Tutorial for Angular Dimensions, because ezdxf reuses the angular dimension to render arc dimensions. This approach is very different to CAD applications, but also much less work.

NOTE:

Dimension Style “EZ_CURVED”

All factory methods to create arc dimensions uses the dimension style “EZ_CURVED” for curved dimension lines which is defined as:

For more information go to: Dimension Style “EZ_CURVED”

Factory Methods to Create Arc Dimensions

Defined by Center, Radius and Angles

The first example shows an arc dimension defined by the center point, radius, start- and end angles:

import ezdxf
# Use argument setup=True to setup the default dimension styles.
doc = ezdxf.new(setup=True)
# Add new entities to the modelspace:
msp = doc.modelspace()
# Add an arc DIMENSION defined by the center point, start- and end angles,
# the measurement text is placed at the default location above the dimension
# line:
dim = msp.add_arc_dim_cra(


    center=(5, 5),  # center point of the angle


    radius=5,  # distance from center point to the start of the extension lines


    start_angle=60,  # start angle in degrees


    end_angle=120,  # end angle in degrees


    distance=2,  # distance from start of the extension lines to the dimension line


    dimstyle="EZ_CURVED",  # default angular 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("arc_dimension_cra.dxf")

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

Arc by 3 Points

The next example shows an angular dimension defined by three points, a center point and the two end points of the angle legs, the first point defines the radius, the second point defines only the end angle, the distance from the center point is not relevant:

import ezdxf
doc = ezdxf.new(setup=True)
msp = doc.modelspace()
msp.add_arc_dim_3p(


    base=(0, 7),  # location of the dimension line


    center=(0, 0),  # center point


    p1=(2.5, 4.330127018922193),  # 1st point of arc defines start angle and radius


    p2=(-2.5, 4.330127018922194),  # 2nd point defines the end angle
).render()

Angle from ConstructionArc

The ezdxf.math.ConstructionArc provides various class methods for creating arcs and the construction tool can be created from an ARC entity.

Add an angular dimension to an ARC entity:

import ezdxf
doc = ezdxf.new(setup=True)
msp = doc.modelspace()
arc = msp.add_arc(


    center=(0, 0),


    radius=5,


    start_angle = 60,


    end_angle = 120,
)
msp.add_arc_dim_arc(


    arc.construction_tool(),


    distance=2,
).render()

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.

NOTE:

SEE ALSO:

Default Text Locations

The DIMSTYLE “EZ_CURVED” places the measurement text in the center of the angle above the dimension line. The first examples above show the measurement text at the default text location.

The text direction angle is always perpendicular to the line from the text center to the center point of the angle unless this angle is manually overridden.

Arrows and measurement text are placed “outside” automatically if the available space between the extension lines isn’t sufficient.

For more information go to: Default Text Locations

Shift Text From Default Location

The method shift_text() shifts the measurement text away from the default location. The shifting direction is aligned to the text rotation of the default measurement text.

For more information go to: Shift Text From Default Location

User Defined Text Locations

Beside the default location it is always possible to override the text location by a user defined location.

The coordinates of user locations are located in the rendering UCS and the default rendering UCS is the WCS.

For more information go to: User Defined Text Locations

Absolute User Location

Absolute placing of the measurement text means relative to the origin of the render UCS.

For more information go to: User Defined Text Locations

Relative User Location

Relative placing of the measurement text means relative to the middle of the dimension line.

For more information go to: User Defined Text Locations

Adding a Leader

Add a leader line to the measurement text and set the text rotation to “horizontal”.

For more information go to: User Defined Text Locations

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).

For more information go to: User Defined Text Locations

Overriding Measurement Text

See Linear Dimension Tutorial: Overriding Text Rotation

Measurement Text Formatting and Styling

See Linear Dimension Tutorial: Measurement Text Formatting and Styling

Tolerances and Limits

See Linear Dimension Tutorial: Tolerances and Limits

Tutorial for Ordinate Dimensions

Please read the Tutorial for Linear Dimensions before, if you haven’t.

NOTE:

Local Coordinate System

Ordinate dimensioning is used when the x- and the y-coordinates from a location (feature), are the only dimensions necessary. The dimensions to each feature, originate from one datum location, called “origin” in this tutorial.

The local coordinate system (LCS) in which the measurement is done, is defined by the origin and the rotation angle around the z-axis in the rendering UCS, which is the WCS by default.

Factory Methods to Create Ordinate Dimensions

All factory methods for creating ordinate dimensions expect global coordinates to define the feature location.

Global Feature Location

The first example shows ordinate dimensions defined in the render UCS, in this example the WCS, this is how the DIMENSION entity expects the coordinates of the feature location:

import ezdxf
from ezdxf.math import Vec3
from ezdxf.render import forms
# Use argument setup=True to setup the default dimension styles.
doc = ezdxf.new(setup=True)
# Add new entities to the modelspace:
msp = doc.modelspace()
# Add a rectangle: width=4, height = 2.5, lower left corner is WCS(x=2, y=3)
origin = Vec3(2, 3)
msp.add_lwpolyline(


    forms.translate(forms.box(4, 2.5), origin),


    close=True
)
# Add an x-type ordinate DIMENSION with global feature locations:
msp.add_ordinate_x_dim(


    # lower left corner


    feature_location=origin + (0, 0),  # feature location in the WCS


    offset=(0, -2),  # end of leader, relative to the feature location


    origin=origin,
).render()
msp.add_ordinate_x_dim(


    # lower right corner


    feature_location=origin + (4, 0),  # feature location in the WCS


    offset=(0, -2),


    origin=origin,
).render()
# Add an y-type ordinate DIMENSION with global feature locations:
msp.add_ordinate_y_dim(


    # lower right corner


    feature_location=origin + (4, 0),  # feature location in the WCS


    offset=(2, 0),


    origin=origin,
).render()
msp.add_ordinate_y_dim(


    # upper right corner


    feature_location=origin + (4, 2.5),  # feature location in the WCS


    offset=(2, 0),


    origin=origin,
).render()
# 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.
doc.saveas("ord_global_features.dxf")

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

Local Feature Location

The previous examples shows that the calculation of the global feature location is cumbersome and it gets even more complicated for a rotated LCS.

This example shows how to use a render UCS for using locale coordinates to define the feature locations:

import ezdxf
from ezdxf.math import Vec3, UCS
from ezdxf.render import forms
doc = ezdxf.new(setup=True)
msp = doc.modelspace()
# Create a special DIMSTYLE for "vertical" centered measurement text:
dimstyle = doc.dimstyles.duplicate_entry("EZDXF", "ORD_CENTER")
dimstyle.dxf.dimtad = 0  # "vertical" centered measurement text
# Add a rectangle: width=4, height = 2.5, lower left corner is WCS(x=2, y=3),
# rotated about 30 degrees:
origin = Vec3(2, 3)
msp.add_lwpolyline(


    forms.translate(forms.rotate(forms.box(4, 2.5), 30), origin),


    close=True
)
# Define the rotated local render UCS.
# The origin is the lower-left corner of the rectangle and the axis are
# aligned to the rectangle edges:
# The y-axis "uy" is calculated automatically by the right-hand rule.
ucs = UCS(origin, ux=Vec3.from_deg_angle(30), uz=(0, 0, 1))
# Add a x-type ordinate DIMENSION with local feature locations:
# the origin is now the origin of the UCS, which is (0, 0) the default value of
# "origin" and the feature coordinates are located in the UCS:
msp.add_ordinate_x_dim(


    # lower left corner


    feature_location=(0, 0),  # feature location in the UCS


    offset=(0.25, -2),  # # leader with a "knee"


    dimstyle="ORD_CENTER",
).render(ucs=ucs)  # Important when using a render UCS!
msp.add_ordinate_x_dim(


    # lower right corner


    feature_location=(4, 0),  # feature location in the UCS


    offset=(0.25, -2),  # leader with a "knee"


    dimstyle="ORD_CENTER",
).render(ucs=ucs)  # Important when using a render UCS!
# Add a y-type ordinate DIMENSION with local feature coordinates:
msp.add_ordinate_y_dim(


    # lower right corner


    feature_location=(4, 0),  # feature location in the UCS


    offset=(2, 0.25),  # leader with a "knee"


    dimstyle="ORD_CENTER",
).render(ucs=ucs)  # Important when using a render UCS!
msp.add_ordinate_y_dim(


    # upper right corner


    feature_location=(4, 2.5),  # feature location in the UCS


    offset=(2, 0.25),  # leader with a "knee"


    dimstyle="ORD_CENTER",
).render(ucs=ucs)  # Important when using a render UCS!
doc.saveas("ord_local_features.dxf")

Placing Measurement Text

The ezdxf ordinate DIMENSION renderer places the measurement text always at the default location, because the location of the leader end point is given by the argument offset in the factory methods, which provides a flexible way to place the measurement text, overriding the text location by an explicit user location is not supported, also the user text rotation is not supported, the text is always aligned to the local coordinate system x- and y-axis.

SEE ALSO:

Overriding Measurement Text

See Linear Dimension Tutorial: Overriding Text Rotation

Measurement Text Formatting and Styling

See Linear Dimension Tutorial: Measurement Text Formatting and Styling

Tolerances and Limits

See Linear Dimension Tutorial: Tolerances and Limits

Tutorial for the Geo Add-on

This tutorial shows how to load a GPS track into a geo located DXF file and also the inverse operation, exporting geo located DXF entities as GeoJSON files.

Please read the section Intended Usage in the documentation of the ezdxf.addons.geo module first.

WARNING:

The complete source code and test data for this tutorial are available in the github repository:

https://github.com/mozman/ezdxf/tree/master/docs/source/tutorials/src/geo

Setup Geo Location Reference

The first step is setting up the geo location reference, which is not doable with ezdxf yet - this feature may come in the future - but for now you have to use a CAD application to do this. If the DXF file has no geo location reference the projected 2D coordinates are most likely far away from the WCS origin (0, 0), use the CAD command “ZOOM EXTENDS” to find the data.

Load GPX Data

The GPX format stores GPS data in a XML format, use the ElementTree class to load the data:

def load_gpx_track(p: Path) -> Iterable[Tuple[float, float]]:


    """Load all track points from all track segments at once."""


    gpx = ET.parse(p)


    root = gpx.getroot()


    for track_point in root.findall(".//gpx:trkpt", GPX_NS):


        data = track_point.attrib


        # Elevation is not supported by the geo add-on.


        yield float(data["lon"]), float(data["lat"])

The loaded GPS data has a WSG84 EPSG:4326 projection as longitude and latitude in decimal degrees. The next step is to create a GeoProxy object from this data, the GeoProxy.parse() method accepts a __geo_interface__ mapping or a Python object with a __geo_interface__ attribute/property. In this case as simple “LineString” object for all GPS points is sufficient:

def add_gpx_track(msp, track_data, layer: str):


    geo_mapping = {


        "type": "LineString",


        "coordinates": track_data,


    }


    geo_track = geo.GeoProxy.parse(geo_mapping)

Transform the data from the polar representation EPSG:4326 into a 2D cartesian map representation EPSG:3395 called “World Mercator”, this is the only projection supported by the add-on, without the need to write a custom transformation function:

    geo_track.globe_to_map()

The data is now transformed into 2D cartesian coordinates in meters and most likely far away from origin (0, 0), the data stored in the GEODATA entity helps to transform the data into the DXF WCS in modelspace units, if the DXF file has no geo location reference you have to stick with the large coordinates:

    # Load geo data information from the DXF file:


    geo_data = msp.get_geodata()


    if geo_data:


        # Get the transformation matrix and epsg code:


        m, epsg = geo_data.get_crs_transformation()


    else:


        # Identity matrix for DXF files without a geo location reference:


        m = Matrix44()


        epsg = 3395


    # Check for compatible projection:


    if epsg == 3395:


        # Transform CRS coordinates into DXF WCS:


        geo_track.crs_to_wcs(m)


        # Create DXF entities (LWPOLYLINE)


        for entity in geo_track.to_dxf_entities(dxfattribs={"layer": layer}):


            # Add entity to the modelspace:


            msp.add_entity(entity)


    else:


        print(f"Incompatible CRS EPSG:{epsg}")

We are ready to save the final DXF file:

doc.saveas(str(out_path))

In BricsCAD the result looks like this, the underlying images were added by the BricsCAD command MAPCONNECT and such a feature is not planned for the add-on: [image]

Export DXF Entities as GeoJSON

This will only work with a proper geo location reference, the code shown accepts also WCS data from DXF files without a GEODATA object, but the result is just unusable - but in valid GeoJSON notation.

First get epsg code and the CRS transformation matrix:

    # Get the geo location information from the DXF file:


    geo_data = msp.get_geodata()


    if geo_data:


        # Get transformation matrix and epsg code:


        m, epsg = geo_data.get_crs_transformation()


    else:


        # Identity matrix for DXF files without geo reference data:


        m = Matrix44()

Query the DXF entities to export:

    for track in msp.query("LWPOLYLINE"):


        export_geojson(track, m)

Create a GeoProxy object from the DXF entity:

def export_geojson(entity, m):


    # Convert DXF entity into a GeoProxy object:


    geo_proxy = geo.proxy(entity)

Transform DXF WCS coordinates in modelspace units into the CRS coordinate system by the transformation matrix m:

    # Transform DXF WCS coordinates into CRS coordinates:


    geo_proxy.wcs_to_crs(m)

The next step assumes a EPSG:3395 projection, everything else needs a custom transformation function:

    # Transform 2D map projection EPSG:3395 into globe (polar)


    # representation EPSG:4326


    geo_proxy.map_to_globe()

Use the json module from the Python standard library to write the GeoJSON data, provided by the GeoProxy.__geo_interface__ property:

    # Export GeoJSON data:


    name = entity.dxf.layer + ".geojson"


    with open(TRACK_DATA / name, "wt", encoding="utf8") as fp:


        json.dump(geo_proxy.__geo_interface__, fp, indent=2)

The content of the GeoJSON file looks like this:

{


  "type": "LineString",


  "coordinates": [


    [


      15.430999,


      47.06503


    ],


    [


      15.431039,


      47.064797


    ],


    [


      15.431206,


      47.064582


    ],


    [


      15.431283,


      47.064342


    ],


    ...
}

Custom Transformation Function

This sections shows how to use the GDAL package to write a custom transformation function. The example reimplements the builtin transformation from unprojected WGS84 coordinates to 2D map coordinates EPSG:3395 “World Mercator”:

from osgeo import osr
from ezdxf.math import Vec3
# GPS track in WGS84, load_gpx_track() code see above
gpx_points = list(load_gpx_track('track1.gpx'))
# Create source coordinate system:
src_datum = osr.SpatialReference()
src_datum.SetWellKnownGeoCS('WGS84')
# Create target coordinate system:
target_datum = osr.SpatialReference()
target_datum.SetWellKnownGeoCS('EPSG:3395')
# Create transformation object:
ct = osr.CoordinateTransform(src_datum, target_datum)
# Create GeoProxy() object:
geo_proxy = GeoProxy.parse({


    'type': 'LineString',


    'coordinates': gpx_points
})
# Apply a custom transformation function to all coordinates:
geo_proxy.apply(lambda v: Vec3(ct.TransformPoint(v.x, v.y)))

The same example with the pyproj package:

from pyproj import Transformer
from ezdxf.math import Vec3
# GPS track in WGS84, load_gpx_track() code see above
gpx_points = list(load_gpx_track('track1.gpx'))
# Create transformation object:
ct = Transformer.from_crs('EPSG:4326', 'EPSG:3395')
# Create GeoProxy() object:
geo_proxy = GeoProxy.parse({


    'type': 'LineString',


    'coordinates': gpx_points
})
# Apply a custom transformation function to all coordinates:
geo_proxy.apply(lambda v: Vec3(ct.transform(v.x, v.y)))

Polygon Validation by Shapely

Ezdxf tries to avoid to create invalid polygons from HATCH entities like a hole in another hole, but not all problems are detected by ezdxf, especially overlapping polygons. For a reliable and robust result use the Shapely package to check for valid polygons:

import ezdxf
from ezdxf.addons import geo
from shapley.geometry import shape
# Load DXF document including HATCH entities.
doc = ezdxf.readfile('hatch.dxf')
msp = doc.modelspace()
# Test a single entity
# Get the first DXF hatch entity:
hatch_entity = msp.query('HATCH').first
# Create GeoProxy() object:
hatch_proxy = geo.proxy(hatch_entity)
# Shapely supports the __geo_interface__
shapley_polygon = shape(hatch_proxy)
if shapely_polygon.is_valid:


    ...
else:


    print(f'Invalid Polygon from {str(hatch_entity)}.')
# Remove invalid entities by a filter function
def validate(geo_proxy: geo.GeoProxy) -> bool:


    # Multi-entities are divided into single entities:


    # e.g. MultiPolygon is verified as multiple single Polygon entities.


    if geo_proxy.geotype == 'Polygon':


        return shape(geo_proxy).is_valid


    return True
# The gfilter() function let only pass compatible DXF entities
msp_proxy = geo.GeoProxy.from_dxf_entities(geo.gfilter(msp))
# remove all mappings for which validate() returns False
msp_proxy.filter(validate)

Interface to GDAL/OGR

The GDAL/OGR package has no direct support for the __geo_interface__, but has builtin support for the GeoJSON format:

from osgeo import ogr
from ezdxf.addons import geo
from ezdxf.render import random_2d_path
import json
p = geo.GeoProxy({'type': 'LineString', 'coordinates': list(random_2d_path(20))})
# Create a GeoJSON string from the __geo_interface__ object by the json
# module and feed the result into ogr:
line_string = ogr.CreateGeometryFromJson(json.dumps(p.__geo_interface__))
# Parse the GeoJSON string from ogr by the json module and feed the result
# into a GeoProxy() object:
p2 = geo.GeoProxy.parse(json.loads(line_string.ExportToJson()))

Storing Custom Data in DXF Files

This tutorial describes how to store custom data in DXF files using standard DXF features.

Saving data in comments is not covered in this section, because comments are not a reliable way to store information in DXF files and ezdxf does not support adding comments to DXF files. Comments are also ignored by ezdxf and many other DXF libraries when loading DXF files, but there is a ezdxf.comments module to load comments from DXF files.

The DXF data format is a very versatile and flexible data format and supports various ways to store custom data. This starts by setting special header variables, storing XData, AppData and extension dictionaries in DXF entities and objects, storing XRecords in the OBJECTS section and ends by using proxy entities or even extending the DXF format by user defined entities and objects.

This is the common prolog for all Python code examples shown in this tutorial:

import ezdxf
doc = ezdxf.new()
msp = doc.modelspace()

Retrieving User Data

Retrieving the is a simple task by ezdxf, but often not possible in CAD applications without using the scripting features (AutoLISP) or even the SDK.

AutoLISP Resources

WARNING:

Header Section

The HEADER section has tow ways to store custom data.

Predefined User Variables

There are ten predefined user variables, five 16-bit integer variables called $USERI1 up to $USERI5 and five floating point variables (reals) called $USERR1 up to $USERR5. This is very limited and the data maybe will be overwritten by the next application which opens and saves the DXF file. Advantage of this methods is, it works for all supported DXF versions starting at R12.

Settings the data:

doc.header["$USERI1"] = 4711
doc.header["$USERR1"] = 3.141592

Getting the data by ezdxf:

i1 = doc.header["$USERI1"]
r1 = doc.header["$USERR1"]

Getting the data in BricsCAD at the command line:

: USERI1
New current value for USERI1 (-32768 to 32767) <4711>:

Getting the data by AutoLISP:

: (getvar 'USERI1)
4711

Setting the value by AutoLISP:

: (setvar 'USERI1 1234)
1234

Custom Document Properties

This method defines custom document properties, but requires at least DXF R2004. The custom document properties are stored in a CustomVars instance in the custom_vars attribute of the HeaderSection object and supports only string values.

Settings the data:

doc.header.custom_vars.append("MyFirstVar", "First Value")

Getting the data by ezdxf:

my_first_var = doc.header.custom_vars.get("MyFirstVar", "Default Value")

The document property MyFirstVar is available in BricsCAD as FIELD variable: [image]

AutoLISP script for getting the custom document properties:

(defun C:CUSTOMDOCPROPS (/ Info Num Index Custom)


  (vl-load-com)


  (setq acadObject (vlax-get-acad-object))


  (setq acadDocument (vla-get-ActiveDocument acadObject))


  ;;Get the SummaryInfo


  (setq Info (vlax-get-Property acadDocument 'SummaryInfo))


  (setq Num (vla-NumCustomInfo Info))


  (setq Index 0)


  (repeat Num


    (vla-getCustomByIndex Info Index 'ID 'Value)


    (setq Custom (cons (cons ID Value) Custom))


    (setq Index (1+ Index))


  )  ;repeat


  (if Custom (reverse Custom))
)

Running the script in BricsCAD:

: (load "customdocprops.lsp")
C:CUSTOMDOCPROPS
: CUSTOMDOCPROPS
(("MyFirstVar" . "First Value"))

Meta Data

Starting with version v0.16.4 ezdxf stores some meta data in the DXF file and the AppID EZDXF will be created. Two entries will be added to the MetaData instance, the CREATED_BY_EZDXF for DXF documents created by ezdxf and the entry WRITTEN_BY_EZDXF if the DXF document will be saved by ezdxf. The marker string looks like this "0.17b0 @ 2021-09-18T05:14:37.921826+00:00" and contains the ezdxf version and an UTC timestamp in ISO format.

You can add your own data to the MetaData instance as a string with a maximum of 254 characters and choose a good name which may never be used by ezdxf in the future.

metadata = doc.ezdxf_metadata()
metadata["MY_UNIQUE_KEY"] = "my additional meta data"
print(metadata.get("CREATED_BY_EZDXF"))
print(metadata.get("MY_UNIQUE_KEY"))

The data is stored as XDATA in then BLOCK entity of the model space for DXF R12 and for DXF R2000 and later as a DXF Dictionary in the root dictionary by the key EZDXF_META. See following chapters for accessing such data by AutoLISP.

XDATA

Extended Data (XDATA) is a way to attach arbitrary data to DXF entities. Each application needs a unique AppID registered in the AppID table to add XDATA to an entity. The AppID ACAD is reserved and by using ezdxf the AppID EZDXF is also registered automatically. The total size of XDATA for a single DXF entity is limited to 16kB for AutoCAD. XDATA is supported by all DXF versions and is accessible by AutoLISP.

The valid group codes for extended data are limited to the following values, see also the internals of Extended Data:

Group codes are not unique in the XDATA section and can be repeated, therefore tag order matters.

# register your appid
APPID = "YOUR_UNIQUE_ID"
doc.appids.add(APPID)
# create a DXF entity
line = msp.add_line((0, 0), (1, 0))
# setting the data
line.set_xdata(APPID, [


    # basic types


    (1000, "custom text"),


    (1040, 3.141592),


    (1070, 4711),  # 16bit


    (1071, 1_048_576),  # 32bit


    # points and vectors


    (1010, (10, 20, 30)),


    (1011, (11, 21, 31)),


    (1012, (12, 22, 32)),


    (1013, (13, 23, 33)),


    # scaled distances and factors


    (1041, 10),


    (1042, 10),
])
# getting the data
if line.has_xdata(APPID):


    tags = line.get_xdata(APPID)


    print(f"{str(line)} has {len(tags)} tags of XDATA for AppID {APPID!r}")


    for tag in tags:


        print(tag)

AutoLISP script for getting XDATA for AppID YOUR_UNIQUE_ID:

(defun C:SHOWXDATA (/ entity_list xdata_list)


    (setq entity_list (entget (car (entsel)) '("YOUR_UNIQUE_ID")))


    (setq xdata_list (assoc -3 entity_list))


    (car (cdr xdata_list))
)

Script output:

: SHOWXDATA
Select entity: ("YOUR_UNIQUE_ID" (1000 . "custom text") (1040 . 3.141592) ...

SEE ALSO:

XDATA Helper Classes

The XDataUserList and XDataUserDict are helper classes to manage XDATA content in a simple way.

Both classes store the Python types int, float and str and the ezdxf type Vec3. As the names suggests has the XDataUserList a list-like interface and the XDataUserDict a dict-like interface. This classes can not contain additional container types, but multiple lists and/or dicts can be stored in the same XDATA section for the same AppID.

These helper classes uses a fixed group code for each data type:

Additional required imports for these examples:

from ezdxf.math import Vec3
from ezdxf.entities.xdata import XDataUserDict, XDataUserList

Example for XDataUserDict:

Each XDataUserDict has a unique name, the default name is “DefaultDict” and the default AppID is EZDXF. If you use your own AppID, don’t forget to create the requited AppID table entry like doc.appids.new("MyAppID"), otherwise AutoCAD will not open the DXF file.

doc = ezdxf.new()
msp = doc.modelspace()
line = msp.add_line((0, 0), (1, 0))
with XDataUserDict.entity(line) as user_dict:


    user_dict["CreatedBy"] = "mozman"


    user_dict["Float"] = 3.1415


    user_dict["Int"] = 4711


    user_dict["Point"] = Vec3(1, 2, 3)

If you modify the content of without using the context manager entity(), you have to call commit() by yourself, to transfer the modified data back into the XDATA section.

Getting the data back from an entity:

with XDataUserDict.entity(line) as user_dict:


    print(user_dict)


    # acts like any other dict()


    storage = dict(user_dict)

Example for XDataUserList:

This example stores the data in a XDataUserList named “AppendedPoints”, the default name is “DefaultList” and the default AppID is EZDXF.

with XDataUserList.entity(line, name="AppendedPoints") as user_list:


    user_list.append(Vec3(1, 0, 0))


    user_list.append(Vec3(0, 1, 0))


    user_list.append(Vec3(0, 0, 1))

Now the content of both classes are stored in the same XDATA section for AppID EZDXF. The XDataUserDict is stored by the name “DefaultDict” and the XDataUserList is stored by the name “AppendedPoints”.

Getting the data back from an entity:

with XDataUserList.entity(line, name="AppendedPoints") as user_list:


    print(user_list)


    storage = list(user_list)
print(f"Copy of XDataUserList: {storage}")

SEE ALSO:

Extension Dictionaries

Extension dictionaries are another way to attach custom data to any DXF entity. This method requires DXF R13/14 or later. I will use the short term XDICT for extension dictionaries in this tutorial.

The Extension Dictionary is a regular DXF Dictionary which can store (key, value) pairs where the key is a string and the value is a DXF object from the OBJECTS section but not graphical DXF entities. The usual objects to store custom data are DictionaryVar to store simple strings and XRecord to store complex data.

Unlike XDATA, custom data attached by extension dictionary will not be transformed along with the DXF entity!

This example shows how to manage the XDICT and to store simple strings as DictionaryVar objects in the XDICT, to store more complex data go to the next section XRecord.

# create a DXF entity
line = msp.add_line((0, 0), (1, 0))
if line.has_extension_dict:


    # get the extension dictionary


    xdict = line.get_extension_dict()
else:


    # create a new extension dictionary


    xdict = line.new_extension_dict()

2. Add strings as DictionaryVar objects to the XDICT. No AppIDs required, but existing keys will be overridden, so be careful by choosing your keys:

xdict.add_dictionary_var("DATA1", "Your custom data string 1")
xdict.add_dictionary_var("DATA2", "Your custom data string 2")

3. Retrieve the strings from the XDICT as DictionaryVar objects:

print(f"DATA1 is '{xdict['DATA1'].value}'")
print(f"DATA2 is '{xdict['DATA2'].value}'")

The AutoLISP access to DICTIONARIES is possible, but it gets complex and I’m only referring to the AfraLISP Dictionaries and XRecords tutorial.

SEE ALSO:

XRecord

The XRecord object can store arbitrary data like the XDATA section, but is not limited by size and can use all group codes in the range from 1 to 369 for DXF Tags. The XRecord can be referenced by any DXF Dictionary, other XRecord objects (tricky ownership!), the XDATA section (store handle by group code 1005) or any other DXF object by adding the XRecord object to the Extension Dictionary of the DXF entity.

It is recommend to follow the DXF reference to assign appropriate group codes to DXF Tags. My recommendation is shown in the table below, but all group codes from 1 to 369 are valid. I advice against using the group codes 100 and 102 (structure tags) to avoid confusing generic tag loaders. Unfortunately, Autodesk doesn’t like general rules and uses DXF format exceptions everywhere.

Group codes are not unique in XRecord and can be repeated, therefore tag order matters.

This example shows how to attach a XRecord object to a LINE entity by Extension Dictionary:

line = msp.add_line((0, 0), (1, 0))
line2 = msp.add_line((0, 2), (1, 2))
if line.has_extension_dict:


    xdict = line.get_extension_dict()
else:


    xdict = line.new_extension_dict()
xrecord = xdict.add_xrecord("DATA1")
xrecord.reset([


    (1, "text1"),  # string


    (40, 3.141592),  # float


    (90, 256),  # 32-bit int


    (10, (1, 2, 0)),  # points and vectors


    (330, line2.dxf.handle)  # handles
])
print(xrecord.tags)

Script output:

[DXFTag(1, 'text1'),


 DXFTag(40, 3.141592),


 DXFTag(90, 256),


 DXFVertex(10, (1.0, 2.0, 0.0)),


 DXFTag(330, '30')]

Unlike XDATA, custom data attached by extension dictionary will not be transformed along with the DXF entity! To react to entity modifications by a CAD applications it is possible to write event handlers by AutoLISP, see the AfraLISP Reactors Tutorial for more information. This very advanced stuff!

SEE ALSO:

XRecord Helper Classes

The UserRecord and BinaryRecord are helper classes to manage XRECORD content in a simple way. The UserRecord manages the data as plain Python types: dict, list, int, float, str and the ezdxf types Vec2 and Vec3. The top level type for the UserRecord.data attribute has to be a list. The BinaryRecord stores arbitrary binary data as BLOB. These helper classes uses fixed group codes to manage the data in XRECORD, you have no choice to change them.

Additional required imports for these examples:

from pprint import pprint
import ezdxf
from ezdxf.math import Vec3
from ezdxf.urecord import UserRecord, BinaryRecord
from ezdxf.entities import XRecord
import zlib

Example 1: Store entity specific data in the Extension Dictionary:

line = msp.add_line((0, 0), (1, 0))
xdict = line.new_extension_dict()
xrecord = xdict.add_xrecord("MyData")
with UserRecord(xrecord) as user_record:


    user_record.data = [  # top level has to be a list!


        "MyString",


        4711,


        3.1415,


        Vec3(1, 2, 3),


        {


            "MyIntList": [1, 2, 3],


            "MyFloatList": [4.5, 5.6, 7.8],


        },


    ]

Example 1: Get entity specific data back from the Extension Dictionary:

if line.has_extension_dict:


    xdict = line.get_extension_dict()


    xrecord = xdict.get("MyData")


    if isinstance(xrecord, XRecord):


        user_record = UserRecord(xrecord)


        pprint(user_record.data)

If you modify the content of UserRecord.data without using the context manager, you have to call commit() by yourself, to store the modified data back into the XRECORD.

Example 2: Store arbitrary data in DICTIONARY objects. The XRECORD is stored in the named DICTIONARY, called rootdict in ezdxf. This DICTIONARY is the root entity for the tree-like data structure stored in the OBJECTS section, see also the documentation of the ezdxf.sections.objects module.

# Get the existing DICTIONARY object or create a new DICTIONARY object:
my_dict = doc.objects.rootdict.get_required_dict("MyDict")
# Create a new XRECORD object, the DICTIONARY object is the owner of this
# new XRECORD:
xrecord = my_dict.add_xrecord("MyData")
# This example creates the user record without the context manager.
user_record = UserRecord(xrecord)
# Store user data:
user_record.data = [


    "Just another user record",


    4711,


    3.1415,
]
# Store user data in associated XRECORD:
user_record.commit()

Example 2: Get user data back from the DICTIONARY object

my_dict = doc.rootdict.get_required_dict("MyDict")
entity = my_dict["MyData"]
if isinstance(entity, XRecord):


    user_record = UserRecord(entity)


    pprint(user_record.data)

Example 3: Store arbitrary binary data

my_dict = doc.rootdict.get_required_dict("MyDict")
xrecord = my_dict.add_xrecord("MyBinaryData")
with BinaryRecord(xrecord) as binary_record:


    # The content is stored as hex strings (e.g. ABBAFEFE...) in one or more


    # group code 310 tags.


    # A preceding group code 160 tag stores the data size in bytes.


    data = b"Store any binary data, even line breaks\r\n" * 20


    # compress data if required


    binary_record.data = zlib.compress(data, level=9)

Example 3: Get binary data back from the DICTIONARY object

entity = my_dict["MyBinaryData"]
if isinstance(entity, XRecord):


    binary_record = BinaryRecord(entity)


    print("\ncompressed data:")


    pprint(binary_record.data)


    print("\nuncompressed data:")


    pprint(zlib.decompress(binary_record.data))

HINT:

SEE ALSO:

AppData

Application-Defined Data (AppData) was introduced in DXF R13/14 and is used by AutoCAD internally to store the handle to the Extension Dictionary and the Reactors in DXF entities. Ezdxf supports these kind of data storage for any AppID and the data is preserved by AutoCAD and BricsCAD, but I haven’t found a way to access this data by AutoLISP or even the SDK. So I don’t recommend this feature to store application defined data, because Extended Data (XDATA) and the Extension Dictionary are well documented and safe ways to attach custom data to entities.

# register your appid
APPID = "YOUR_UNIQUE_ID"
doc.appids.add(APPID)
# create a DXF entity
line = msp.add_line((0, 0), (1, 0))
# setting the data
line.set_app_data(APPID, [(300, "custom text"), (370, 4711), (460, 3.141592)])
# getting the data
if line.has_app_data(APPID):


    tags = line.get_app_data(APPID)


    print(f"{str(line)} has {len(tags)} tags of AppData for AppID {APPID!r}")


    for tag in tags:


        print(tag)

Printed output:

LINE(#30) has 3 tags of AppData for AppID 'YOUR_UNIQUE_ID'
(300, 'custom text')
(370, 4711)
(460, 3.141592)

Tutorial for MultiLeader

New in version 0.18.

A multileader object typically consists of an arrowhead, a horizontal landing (a.k.a. “dogleg”), a leader line or curve, and either a MTEXT object or a BLOCK.

Factory methods of the BaseLayout class to create new MultiLeader entities:

Because of the complexity of the MULTILEADER entity, the factory method add_multileader_mtext() returns a MultiLeaderMTextBuilder instance to build a new entity and the factory method add_multileader_block() returns a MultiLeaderBlockBuilder instance.

Due of the lack of good documentation it’s not possible to support all combinations of MULTILEADER properties with decent quality, so stick to recipes and hints shown in this tutorial to get usable results otherwise, you will enter uncharted territory.

The rendering result of the MULTILEADER entity is highly dependent on the CAD application. The MULTILEADER entity does not have a pre-rendered anonymous block of DXF primitives like all DIMENSION entities, so results may vary from CAD application to CAD application. The general support for this entity is only good in Autodesk products other CAD applications often struggle when rendering MULTILEADERS, even my preferred testing application BricsCAD has rendering issues.

IMPORTANT:

SEE ALSO:

MTEXT Quick Draw

Full Python script: mtext_quick_leader.py

The quick_leader() method of a MTEXT - MULTILEADER entity constructs the geometry parameters in reverse manner, starting from a given target point:

DXF document setup:

    doc = ezdxf.new(setup=True)


    # Create a new custom MLEADERSTYLE:


    mleaderstyle = doc.mleader_styles.duplicate_entry("Standard", "EZDXF")


    # The required TEXT style "OpenSans" was created by ezdxf.new() because setup is True:


    mleaderstyle.set_mtext_style("OpenSans")


    msp = doc.modelspace()

Draw a red circle to mark the target point:

    target_point = Vec2(40, 15)


    msp.add_circle(


        target_point, radius=0.5, dxfattribs=GfxAttribs(color=colors.RED)


    )

Create four horizontal placed MULTILEADER entities pointing at the target point, the first segment of the leader line is determined by an angle in this example pointing away from the target point:

    for angle in [45, 135, 225, -45]:


        ml_builder = msp.add_multileader_mtext("EZDXF")


        ml_builder.quick_leader(


            f"angle={angle}°\n2nd text line",


            target=target_point,


            segment1=Vec2.from_deg_angle(angle, 14),


        )

The content is automatically aligned to the end of the leader line. The first segment is a relative vector to the target point and the optional second segment vector is relative to the end of the first segment. The default connection type is horizontal but can be changed to vertical:

A smaller text size is required:

    mleaderstyle = doc.mleader_styles.duplicate_entry("Standard", "EZDXF")


    mleaderstyle.set_mtext_style("OpenSans")


    mleaderstyle.dxf.char_height = 2.0  # set the default char height of MTEXT

Adding vertical placed MULTILEADER entities:

    for angle in [45, 135, 225, -45]:


        ml_builder = msp.add_multileader_mtext("EZDXF")


        ml_builder.quick_leader(


            f"angle={angle}°\n2nd text line",


            target=target_point,


            segment1=Vec2.from_deg_angle(angle, 14),


            connection_type=mleader.VerticalConnection.center_overline,

This example already shows the limitation caused by different text renderings in various CAD applications. The ezdxf text measurement by matplotlib is different to AutoCAD and BricsCAD and the result is a misalignment of the overline and the leader line.

The DXF file shown in BricsCAD: [image]

The same DXF file shown with the ezdxf view command (drawing add-on): [image]

My advice is to avoid vertical placed MULTILEADER entities at all and for horizontal placed MULTILEADER entities avoid styles including an “underline” or an “overline”.

The quick_leader() method is not very customizable for ease of use, but follows the settings of the associated MLeaderStyle.

The following sections show how to have more control when adding MULTILEADER entities.

Create MTEXT Content

Full Python script: mtext_content.py

This section shows how to create a MULTILEADER entity with MTEXT content the manual way with full control over all settings.

For good results the MTEXT alignment should match the leader connection side, e.g. if you attach leaders to the left side also align the MTEXT to the left side, for leaders attached at the right side, align the MTEXT to the right side and if you attach leaders at both sides one side will fit better than the other or maybe a center aligned MTEXT is a good solution, for further details see section MTEXT Alignment.

The first example uses the default connection type of the MLEADERSTYLE “Standard” which is “middle of the top line” for left and right attached leaders. The render UCS for this example is the WCS to keep things simple.

Create a new MULTILEADER entity.

    msp = doc.modelspace()

Set MTEXT content, text style and alignment.

    ml_builder = msp.add_multileader_mtext("Standard")


    ml_builder.set_content(


        "Line1\nLine2",


        style="OpenSans",


        alignment=mleader.TextAlignment.left,  # set MTEXT alignment!

Add the first leader on the left side. The leader points always to the first given vertex and all vertices are given in render UCS coordinates (= WCS in this example).

    )

More than one vertex per leader can be used:

    ml_builder.add_leader_line(mleader.ConnectionSide.left, [Vec2(-20, -15)])


    ml_builder.add_leader_line(


        mleader.ConnectionSide.left,


        [Vec2(-20, 15), Vec2(-10, 15), Vec2(-15, 11), Vec2(-10, 7)],

The insert point of the build() method is the alignment point for the MTEXT content.

    )

The “dogleg” settings are defined by the MLEADERSTYLE “Standard”. [image]

This example shows a leader attached to the right side and the MTEXT aligned to the right side.

    msp = doc.modelspace()


    ml_builder = msp.add_multileader_mtext("Standard")


    ml_builder.set_content(


        "Line1\nLine2",


        style="OpenSans",


        alignment=mleader.TextAlignment.right,  # set MTEXT alignment!


    )


    ml_builder.add_leader_line(mleader.ConnectionSide.right, [Vec2(40, -15)])

This example shows two leaders attached to both sides and the MTEXT aligned to the left side, which shows that the right landing gap (space between text and start of vertex) is bigger than the gap on the left size. This is due to the different text size calculations from AutoCAD/BricsCAD and Matplotlib. The longer the text, the greater the error.

    msp = doc.modelspace()


    ml_builder = msp.add_multileader_mtext("Standard")


    ml_builder.set_content(


        "Line1\nLine1",


        style="OpenSans",


        alignment=mleader.TextAlignment.left,  # set MTEXT alignment!


    )


    ml_builder.add_leader_line(mleader.ConnectionSide.left, [Vec2(-20, -15)])


    ml_builder.add_leader_line(mleader.ConnectionSide.right, [Vec2(40, -15)])

A centered MTEXT alignment gives a more even result.

    msp = doc.modelspace()


    ml_builder = msp.add_multileader_mtext("Standard")


    ml_builder.set_content(


        "First Line\n2. Line",


        style="OpenSans",


        alignment=mleader.TextAlignment.center,  # set MTEXT alignment!


    )


    ml_builder.add_leader_line(mleader.ConnectionSide.left, [Vec2(-20, -15)])


    ml_builder.add_leader_line(mleader.ConnectionSide.right, [Vec2(40, -15)])

But even this has its disadvantages, the attachment calculation is always based on the bounding box of the MTEXT content. [image]

MTEXT Connection Types

There are four connection sides defined by the enum ezdxf.render.ConnectionSide:

The MultiLeader entity supports as the name says multiple leader lines, but all have to have a horizontal (left/right) connection side or a vertical (top/bottom) connection side, it’s not possible to mix left/right and top/bottom connection sides. This is determined by the DXF format.

There are different connection types available for the horizontal and the vertical connection sides. All leaders connecting to the same side have the same connection type. The horizontal connection sides support following connection types, defined by the enum ezdxf.render.HorizontalConnection:

The vertical connection sides support following connection types, defined by the enum ezdxf.render.VerticalConnection:

The connection type for each side can be set by the method set_connection_types(), the default for all sides is by_style:

    ml_builder.add_leader_line(mleader.ConnectionSide.right, [Vec2(40, -15)])


    ml_builder.set_connection_types(


        left=mleader.HorizontalConnection.middle_of_top_line,


        right=mleader.HorizontalConnection.middle_of_bottom_line,

HINT:

MTEXT Alignment

In contrast to the standalone MTEXT entity supports the MTEXT content entity only three text alignments defined by the enum ezdxf.render.TextAlignment.

The MTEXT alignment is set as argument alignment of the set_content() method and the alignment point is the insert point of the build() method.

Create BLOCK Content

Full Python script: block_content.py

This section shows how to create a MULTILEADER entity with BLOCK content the manual way with full control over all settings.

The BLOCK content consist of a BLOCK layout and optional ATTDEF entities which defines the location and DXF attributes of dynamically created ATTRIB entities.

Create the BLOCK content, the full create_square_block() function can be found in the block_content.py script.

    block = create_square_block(


        doc, size=8.0, margin=0.25, base_point=base_point


    )

Create the MULTILEADER and set the content:

    ml_builder = msp.add_multileader_block(style="Standard")


    ml_builder.set_content(


        name=block.name, alignment=mleader.BlockAlignment.insertion_point


    )

Set the BLOCK attribute content as text:

    ml_builder.set_attribute("ONE", "Data1")


    ml_builder.set_attribute("TWO", "Data2")

Add some leader lines to the left and right side of the BLOCK:

Construction plane of the entity is defined by a render UCS. The leader lines vertices are expected in render UCS coordinates, which means relative to the UCS origin and this example shows the simple case where the UCS is the WCS which is also the default setting.

    ml_builder.add_leader_line(mleader.ConnectionSide.right, [Vec2(x2, y1)])


    ml_builder.add_leader_line(mleader.ConnectionSide.right, [Vec2(x2, y2)])


    ml_builder.add_leader_line(mleader.ConnectionSide.left, [Vec2(x1, y1)])


    ml_builder.add_leader_line(mleader.ConnectionSide.left, [Vec2(x1, y2)])

Last step is to build the final MULTILEADER entity. This example uses the alignment type insertion_point where the insert point of the build() method is the base point of the BLOCK:

    ml_builder.build(insert=Vec2(5, 2), rotation=30)

The result is shown in BricsCAD as expected, although BricsCAD shows “Center extents” as attachment type in the properties dialog instead of the correct attachment type “Insertion point”.

BLOCK Connection Types

There are four connection sides defined by the enum ezdxf.render.ConnectionSide:

The connection point for leader lines is always the center of the side of the block bounding box the leader is connected to and has the same limitation as for the MTEXT content, it’s not possible to mix the connection sides left/right and top/bottom.

The connection side is set when adding the leader line by the add_leader_line() method.

Unfortunately BricsCAD has an error in version 22.2.03 and renders all connection types as left/right, this is top/bottom connection shown in Autodesk TrueView 2022: [image]

The top/bottom connection type does not support the “dogleg” feature.

BLOCK Alignment

There are two alignments types, defined by the enum ezdxf.render.BlockAlignment

The alignment is set by the set_content() method.

The alignment type center_extent inserts the BLOCK with the center of the bounding box at the insert point of the build() method. The insert point is (5, 2) in this example: [image]

The same MULTILEADER with alignment type insert_point: [image]

BLOCK Scaling

The BLOCK content can be scaled independently from the overall scaling of the MULTILEADER entity:

The block scaling factor is set by the set_content() method:

ml_builder.set_content(


    name=block.name, scale=2.0, alignment=mleader.BlockAlignment.center_extents
)

This is the first example with a block scaling factor of 2. The BLOCK and the attached ATTRIB entities are scaled but not the arrows. [image]

BLOCK Rotation

The rotation around the render UCS z-axis in degrees is applied by the build() method:

ml_builder.build(insert=Vec2(5, 2), rotation=30)

This is the first example with a rotation of 30 degrees. The BLOCK, the attached ATTRIB entities and the last connection lines (“dogleg”) are rotated. [image]

BLOCK Attributes

BLOCK attributes are defined as ATTDEF entities in the BLOCK layout. This ATTDEF entities will be replaced by ATTRIB entities at the rendering process of the CAD application. Only the text content and the text width factor can be changed for each MULTILEADER entity individually by the set_attribute() method. The ATTDEF is addressed by it’s DXF tag attribute:

ml_builder.set_attribute("ONE", "Data1")
ml_builder.set_attribute("TWO", "Data2")

Leader Properties

“Dogleg” Properties

The “dogleg” is the last line segment from the last leader vertex to the MULTILEADER content for polyline leaders. [image]

The length of the dogleg and the landing gap size is set by the set_connection_properties().

Polyline Leader

A polygon leader line has only straight line segments and is added by the add_leader_line():

ml_builder.add_leader_line(


    mleader.ConnectionSide.left,


    [Vec2(-20, 15), Vec2(-10, 15), Vec2(-15, 11), Vec2(-10, 7)],
)

All leader line vertices have render UCS coordinates and the start- and end-vertex of the “dogleg” is calculated automatically.

Spline Leader

A spline leader line has a single curved line as leader line and is also added by the add_leader_line(). This is spline leader has the same vertices as the previous created polyline leader:

ml_builder.set_leader_properties(leader_type=mleader.LeaderType.splines)
ml_builder.add_leader_line(


    mleader.ConnectionSide.left,


    [Vec2(-20, 15), Vec2(-10, 15), Vec2(-15, 11), Vec2(-10, 7)],
)

The spline leader has no “dogleg” and spline leaders and polyline leaders can not be mixed in a single MULTILEADER entity.

The leader type is set by the set_leader_properties() method.

The LeaderType enum:

Line Styling

The leader color, linetype and lineweight is set by the set_leader_properties() method:

ml_builder.set_leader_properties(


    color=colors.MAGENTA,


    linetype="DASHEDX2",


    lineweight=70,
)

All leader lines have the same properties.

Arrowheads

The arrow head is set by the set_arrow_properties() method:

from ezdxf.render import ARROWS
ml_builder.set_arrow_properties(name=ARROWS.closed_blank, size=8.0)

All leader lines have the same arrow head and size. The available arrow heads are defined in the ARROWS object.

Overall Scaling

The overall scaling has to be applied by the set_overall_scaling() method and scales the MTEXT or BLOCK content and the arrows.

Setup MLEADERSTYLE

The MLeaderStyle stores many of the MULTILEADER settings but most of them are copied to the MULTILINE entity at initialization. So changing the MLEADERSTYLE style afterwards has little to no effect for existing MULTILEADER entities.

Create a new MLEADERSTYLE called “MY_STYLE” and set the MTEXT style to “OpenSans”:

my_style = doc.mleader_styles.duplicate_entry("Standard", "MY_STYLE")
my_style.set_mtext_style("OpenSans")

The style for a MULTILEADER is set at the add_multileader_mtext() and add_multileader_block() factory methods.

General Document

General preconditions:

import sys
import ezdxf
try:


    doc = ezdxf.readfile("your_dxf_file.dxf")
except IOError:


    print(f"Not a DXF file or a generic I/O error.")


    sys.exit(1)
except ezdxf.DXFStructureError:


    print(f"Invalid or corrupted DXF file.")


    sys.exit(2)
msp = doc.modelspace()

This works well with DXF files from trusted sources like AutoCAD or BricsCAD, for loading DXF files with minor or major flaws look at the ezdxf.recover module.

Load DXF Files with Structure Errors

If you know the files you will process have most likely minor or major flaws, use the ezdxf.recover module:

import sys
from ezdxf import recover
try:  # low level structure repair:


    doc, auditor = recover.readfile(name)
except IOError:


    print(f"Not a DXF file or a generic I/O error.")


    sys.exit(1)
except ezdxf.DXFStructureError:


    print(f"Invalid or corrupted DXF file: {name}.")


    sys.exit(2)
# DXF file can still have unrecoverable errors, but this is maybe
# just a problem when saving the recovered DXF file.
if auditor.has_errors:


    print(f"Found unrecoverable errors in DXF file: {name}.")


    auditor.print_error_report()

For more loading scenarios follow the link: ezdxf.recover

Set/Get Header Variables

ezdxf has an interface to get and set HEADER variables:

doc.header["VarName"] = value
value = doc.header["VarName"]

SEE ALSO:

Set DXF Drawing Units

The header variable $INSUNITS defines the drawing units for the modelspace and therefore for the DXF document if no further settings are applied. The most common units are 6 for meters and 1 for inches.

Use this HEADER variables to setup the default units for CAD applications opening the DXF file. This setting is not relevant for ezdxf API calls, which are unitless for length values and coordinates and decimal degrees for angles (in most cases).

Sets drawing units:

doc.header["$INSUNITS"] = 6

For more information see section DXF Units.

Create More Readable DXF Files (DXF Pretty Printer)

DXF files are plain text files, you can open this files with every text editor which handles bigger files. But it is not really easy to get quick the information you want.

Create a more readable HTML file (DXF Pretty Printer):

# Call as executable script from the command line:
ezdxf pp FILE [FILE ...]
# Call as module on Windows:
py -m ezdxf pp FILE [FILE ...]
# Call as module on Linux/Mac
python3 -m ezdxf pp FILE [FILE ...]

This creates a HTML file with a nicer layout than a plain text file, and handles are links between DXF entities, this simplifies the navigation between the DXF entities.

Changed in version 0.16: The dxfpp command was replaced by a sub-command of the ezdxf launcher.

usage: ezdxf pp [-h] [-o] [-r] [-x] [-l] FILE [FILE ...]
positional arguments:


  FILE             DXF files pretty print
optional arguments:


  -h, --help       show this help message and exit


  -o, --open       open generated HTML file with the default web browser


  -r, --raw        raw mode - just print tags, no DXF structure interpretation


  -x, --nocompile  don't compile points coordinates into single tags (only in


                   raw mode)


  -l, --legacy     legacy mode - reorders DXF point coordinates

IMPORTANT:

Calculate Extents for the Modelspace

Since ezdxf v0.16 exist a ezdxf.bbox module to calculate bounding boxes for DXF entities. This module makes the extents calculation very easy, but read the documentation for the bbox module to understand its limitations.

import ezdxf
from ezdxf import bbox
doc = ezdxf.readfile("your.dxf")
msp = doc.modelspace()
extents = bbox.extents(msp)

The returned extents is a ezdxf.math.BoundingBox object.

Set Initial View/Zoom for the Modelspace

To show an arbitrary location of the modelspace centered in the CAD application window, set the '*Active' VPORT to this location. The DXF attribute dxf.center defines the location in the modelspace, and the dxf.height specifies the area of the modelspace to view. Shortcut function:

doc.set_modelspace_vport(height=10, center=(10, 10))

New in version 0.16.

The new ezdxf.zoom module of ezdxf v0.16, makes this task much easier.

Setting the initial view to the extents of all entities in the modelspace:

import ezdxf
from ezdxf import zoom
doc = ezdxf.readfile("your.dxf")
msp = doc.modelspace()
zoom.extents(msp)

Setting the initial view to the extents of just some entities:

lines = msp.query("LINES")
zoom.objects(lines)

The zoom module also works for paperspace layouts.

IMPORTANT:

Hide the UCS Icon

The visibility of the UCS icon is controlled by the DXF ucs_icon attribute of the VPort entity:

The state of the UCS icon can be set in conjunction with the initial VPort of the model space, this code turns off the UCS icon:

doc.set_modelspace_vport(10, center=(10, 10), dxfattribs={"ucs_icon": 0})

Alternative: turn off UCS icons for all VPort entries in the active viewport configuration:

for vport in doc.viewports.get_config("*Active"):


    vport.dxf.ucs_icon = 0

Show Lineweights in DXF Viewers

By default lines and curves are shown without lineweights in DXF viewers. By setting the header variable $LWDISPLAY to 1 the DXF viewer should display lineweights, if supported by the viewer.

doc.header["$LWDISPLAY"] = 1

Add ezdxf Resources to Existing DXF Document

Add all ezdxf specific resources (line types, text- and dimension styles) to an existing DXF document:

import ezdxf
from ezdxf.tools.standards import setup_drawing
doc = ezdxf.readfile("your.dxf")
setup_drawing(doc, topics="all")

Set Logging Level of ezdxf

Set the logging level of the ezdxf package to a higher level to minimize logging messages from ezdxf. At level ERROR only severe errors will be logged and WARNING, INFO and DEBUG messages will be suppressed:

import logging
logging.getLogger("ezdxf").setLevel(logging.ERROR)

DXF Viewer

A360 Viewer Problems

AutoDesk web service A360 seems to be more picky than the AutoCAD desktop applications, may be it helps to use the latest DXF version supported by ezdxf, which is DXF R2018 (AC1032) in the year of writing this lines (2018).

DXF Entities Are Not Displayed in the Viewer

ezdxf does not automatically locate the main viewport of the modelspace at the entities, you have to perform the “Zoom to Extends” command, here in TrueView 2020: [image]

And here in the Autodesk Online Viewer: [image]

Add this line to your code to relocate the main viewport, adjust the center (in modelspace coordinates) and the height (in drawing units) arguments to your needs:

doc.set_modelspace_vport(height=10, center=(0, 0))

Show IMAGES/XREFS on Loading in AutoCAD

If you are adding XREFS and IMAGES with relative paths to existing drawings and they do not show up in AutoCAD immediately, change the HEADER variable $PROJECTNAME='' to (not really) solve this problem. The ezdxf templates for DXF R2004 and later have $PROJECTNAME='' as default value.

Thanks to David Booth:

So far - no solution for showing IMAGES with relative paths on loading.

Set Initial View/Zoom for the Modelspace

See section “General Document”: Set Initial View/Zoom for the Modelspace

Show Lineweights in DXF Viewers

By default lines and curves are shown without lineweights in DXF viewers. By setting the header variable $LWDISPLAY to 1 the DXF viewer should display lineweights, if supported by the viewer.

doc.header["$LWDISPLAY"] = 1

DXF Content

General preconditions:

import sys
import ezdxf
try:


    doc = ezdxf.readfile("your_dxf_file.dxf")
except IOError:


    print(f'Not a DXF file or a generic I/O error.')


    sys.exit(1)
except ezdxf.DXFStructureError:


    print(f'Invalid or corrupted DXF file.')


    sys.exit(2)
msp = doc.modelspace()

Get/Set Entity Color

The entity color is stored as ACI (AutoCAD Color Index):

aci = entity.dxf.color

Default value is 256 which means BYLAYER:

layer = doc.layers.get(entity.dxf.layer)
aci = layer.get_color()

The special get_color() method is required, because the color attribute Layer.dxf.color is misused as layer on/off flag, a negative color value means the layer is off.

ACI value 0 means BYBLOCK, which means the color from the block reference (INSERT entity).

Set color as ACI value as int in range [0, 256]:

entity.dxf.color = 1

The ACI value 7 has a special meaning, it is white on dark backgrounds and white on light backgrounds.

Get/Set Entity RGB Color

RGB true color values are supported since DXF R13 (AC1012), the 24-bit RGB value is stored as integer in the DXF attribute true_color:

# 24 bit binary value: 0bRRRRRRRRGGGGGGGGBBBBBBBB or hex value: 0xRRGGBB
# set true color value to red
entity.dxf.true_color = 0xFF0000

Use the helper functions from the ezdxf.colors module for RGB integer value handling:

from ezdxf import colors
entity.dxf.true_color = colors.rgb2int((0xFF, 0, 0))
r, g, b = colors.int2rgb(entity.dxf.true_color)

The RGB values of the AutoCAD default colors are not officially documented, but an accurate translation table is included in ezdxf:

# Warning: ACI value 256 (BYLAYER) raises an IndexError!
rgb24 = colors.DXF_DEFAULT_COLORS[aci]
print(f"RGB Hex Value: #{rgb24:06X}")
r, g, b = colors.int2rgb(rgb24)
print(f"RGB Channel Values: R={r:02X} G={g:02X} b={b:02X}")

If color and true_color values are set, BricsCAD and AutoCAD use the true_color value as display color for the entity.

Get/Set True Color as RGB-Tuple

Get/Set the true color value as (r, g, b)-tuple by the rgb property of the DXFGraphic entity:

# set true color value to red
entity.rgb = (0xFF, 0, 0)
# get true color values
r, g, b = entity.rgb

Get/Set Block Reference Attributes

Block references (Insert) can have attached attributes (Attrib), these are simple text annotations with an associated tag appended to the block reference.

Iterate over all appended attributes:

# get all INSERT entities with entity.dxf.name == "Part12"
blockrefs = msp.query('INSERT[name=="Part12"]')
if len(blockrefs):


    entity = blockrefs[0]  # process first entity found


    for attrib in entity.attribs:


        if attrib.dxf.tag == "diameter":  # identify attribute by tag


            attrib.dxf.text = "17mm"  # change attribute content

Get attribute by tag:

diameter = entity.get_attrib('diameter')
if diameter is not None:


    diameter.dxf.text = "17mm"

Adding XDATA to Entities

Adding XDATA as list of tuples (group code, value) by set_xdata(), overwrites data if already present:

doc.appids.new('YOUR_APPID')  # IMPORTANT: create an APP ID entry
circle = msp.add_circle((10, 10), 100)
circle.set_xdata(


    'YOUR_APPID',


    [


        (1000, 'your_web_link.org'),


        (1002, '{'),


        (1000, 'some text'),


        (1002, '{'),


        (1071, 1),


        (1002, '}'),


        (1002, '}')


    ])

For group code meaning see DXF reference section DXF Group Codes in Numerical Order Reference, valid group codes are in the range 1000 - 1071.

Method get_xdata() returns the extended data for an entity as Tags object.