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 documents or create new DXF documents.

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 the outdated dxfwrite and 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.8 (determined by numpy) 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 pyparsing, numpy, fontTools 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 these DXF files.

Supported Operating Systems

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

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]

PySide6 Issue

Maybe PySide6 won’t launch on debian based distributions and shows this error message:

qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
...

This may fix the issue:

sudo apt-get install libxcb-cursor0

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.

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 binary wheels available on PyPi which included the compiled C-extensions.

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 development environment.

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 and the python3.10-dev package the required headers, change 3.10 to the Python version you are using:

sudo apt install build-essential python3.10-dev

The system Python 3 interpreter has the version 3.8 (in 2021), 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 (in 2021), 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
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 documents from a file:

doc = ezdxf.readfile(filename)

or from a zip-file:

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

Which loads the DXF document 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 document 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 documents from trusted sources like AutoCAD or BricsCAD. For loading DXF documents with minor or major flaws use the ezdxf.recover module.

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.paperspace("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 an 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

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 do 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 entity attributes and assets are only available from Python properties or methods outside the dxf namespace like the vertices of 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 if the attribute really exist:

entity.dxf.hasattr("true_color")

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

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

SEE ALSO:

Create a New DXF File

Create new document for the latest supported DXF version:

doc = ezdxf.new()

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

doc = ezdxf.new("R12")

The ezdxf.new() function can create some standard resources, such as linetypes and text styles, by setting the argument setup to True:

doc = ezdxf.new(setup=True)

SEE ALSO:

Create New DXF Entities

The factory methods for creating new graphical DXF entities are located in the BaseLayout class and these 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"})

A few important/required DXF attributes are explicit method arguments, most additional DXF attributes are gives as a regular Python dict object by the keyword only argument dxfattribs. The supported DXF attributes can be found in the documentation of the ezdxf.entities module.

WARNING:

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 New Blocks

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

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

SEE ALSO:

Create Block References

A block reference is just another DXF entity called INSERT. The Insert entity is created by the factory method: 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 the 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.layers.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 manually destruction of entities by calling the method destroy():

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.

HINT:

DXF Entities and Objects

DXF entities are objects that make up the design data stored in a DXF file.

Graphical Entities

Graphical entities are visible objects stored in blocks, modelspace- or paperspace layouts. They represent the various shapes, lines, and other elements that make up a 2D or 3D design.

Some common types of DXF entities include:

These entities are defined using specific codes and values in the DXF file format, and they can be created and manipulated by ezdxf.

Objects

DXF objects are non-graphical entities and have no visual representation, they store administrative data, paperspace layout definitions, style definitions for multiple entity types, custom data and objects. The OBJECTS section in DXF files serves as a container for these non-graphical objects.

Some common DXF types of DXF objects include:

TagStorage

The ezdxf package supports many but not all entity types, all these unsupported types are stored as TagStorage instances to preserve their data when exporting the edited DXF content by ezdxf.

Access Entity Attributes

All DXF attributes are stored in the entity namespace attribute dxf.

print(entity.dxf.layer)

Some attributes are mandatory others are optional in most cases a reasonable values will be returned as default value if the attribute is missing.

SEE ALSO:

Where to Look for Entities

The DXF document has an entity database where all entities which have a handle are stored in a (key, value) storage. The query() method is often the easiest way to request data:

for text in doc.entitydb.query("TEXT"):
    print(text.dxf.text)

SEE ALSO:

Graphical entities are stored in blocks, the modelspace or paperspace layouts.

The query() method of the Drawing class which represents the DXF document, runs the query on all layouts and block definitions.

Non-graphical entities are stored in the OBJECTS section:

Resource definitions like Layer, Linetype or Textstyle are stored in resource tables:

IMPORTANT:

SEE ALSO:

How to Create Entities

The recommended way to create new DXF entities is to use the factory methods of layouts and blocks to create entities and add them to the entity space automatically.

SEE ALSO:

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 do not preserve the layout of a drawing very well, because of the lack of a standard color table and missing DXF structures to define these color tables in the DXF file. If a CAD user redefines an ACI color entry in a CAD application and does not provide this CTB or STB file, you can not know what color or lineweight was used intentionally. This got better in later DXF versions by supporting additional DXF attributes like lineweight and true_color which can define these attributes by distinct values. [image]

SEE ALSO:

True Color

The support for true color was added to the DXF file format in revision R2004. The true color value has three components red, green and blue in the range from 0 to 255 and is stored as a 24-bit value in the DXF namespace as true_color attribute and looks like this 0xRRGGBB as hex value. For a more easy usage all graphical entities support the rgb property to get and set the true color as (r, g, b) tuples where the components must be in the range from 0 to 255.

import ezdxf
doc = ezdxf.new()
msp = doc.modelspace()
line = msp.add_line((0, 0), (10, 0))
line.rgb = (255, 128, 32)

The true color value has higher precedence than the AutoCAD Color Index (ACI) value, if the attributes color and the true_color are present the entity will be rendered with the true color value.

The true color value has the advantage that it defines the color absolutely and unambiguously, no unexpected overwriting is possible. The representation of the color is fixed and only depends on the calibration of the output medium: [image]

SEE ALSO:

Transparency

The support for transparency was added to the DXF file format in revision R2004. The raw transparency value stored as 32 bit value in the DXF namespace as transparency attribute, has a range from 0 to 255 where 0 is fully transparent and 255 if opaque and has the top byte set to 0x02. For a more easy usage all graphical entities support the transparency property to get and set the transparency as float value in the range frem 0.0 to 1.0 where 0.0 is opaque and 1.0 is fully transparent. The transparency value can be set explicit in the entity, by layer or by block.

import ezdxf
doc = ezdxf.new()
msp = doc.modelspace()
line = msp.add_line((0, 0), (10, 0))
line.transparency = 0.5

SEE ALSO:

Layers

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.add(), 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.

The DXF format do not require a layer table entry for a layer. A layer without a layer table entry has the default linetype 'Continuous', a default color of 7 and a lineweight of -3 which represents the default lineweight of 0.25mm in most circumstances.

Layer Properties

The advantage of assigning properties to a layer is that entities can inherit this properties from the layer by using the string 'BYLAYER' as linetype string, 256 as color or -1 as lineweight, all these values are the default values for new entities. DXF version R2004 and later also support inheriting true_color and transparency attributes from a layer.

Layer Status

The layer status is important for the visibility and the ability to select and edit DXF entities on that layer in CAD applications. Ezdxf does not care about the visual representation and works at the level of entity spaces and the entity database and therefore all the layer states documented below are ignored by ezdxf. This means if you iterate an entity space like the modelspace or the entity database you will get all entities from that entity space regardless the layer status.

Deleting Layers

Deleting a layer is not as simple as it might seem, especially if you are used to use a CAD application like AutoCAD. There is no directory of locations where layers can be used and references to layers can occur even in third-party data. Deleting the layer table entry removes only the default attributes of that layer and does not delete any layer references automatically. And because a layer can exist without a layer table entry, the layer exist as long as at least one layer reference to the layer exist.

Renaming Layers

Renaming a layer is also problematic because the DXF format stores the layer references in most cases as text strings, so renaming the layer table entry just creates a new layer and all entities which still have a reference to the old layer now inherit their attributes from an undefined layer table entry with default settings.

Viewport Overrides

Most of the layer properties can be overriden for each Viewport entity individually and this overrides are stored in layer table entry referenced by the handle of the VIEWPORT entity. In contrast the frozen status of layers is store in the VIEWPORT entity.

SEE ALSO:

Linetypes

The linetype defines the rendering pattern of linear graphical entities like LINE, ARC, CIRCLE and so on. 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 linetype from the assigned layer by setting linetype to 'BYLAYER', which is also the default value. CONTINUOUS is the default linetype for layers with an unspecified linetype.

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

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

In DXF R13 Autodesk introduced complex linetypes which can contain text or shapes.

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.

The linetype scaling for a single entity can be set by the DXF attribute ltscale, which is supported since DXF 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 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 script 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 disabled by default, the same has to be done in the page setup options for plotting lineweights.

Setting the HEADER variable $LWDISPLAY to 1, activates support for displaying lineweights on screen:

# activate on screen lineweight display
doc.header["$LWDISPLAY"] = 1

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

SEE ALSO:

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 are coordinates relative to the object itself. The main goal of OCS is to place 2D elements in 3D space and the OCS is defined by the extrusion vector of the entity. As long the extrusion vector is (0, 0, 1) (the WCS z-axis) the OCS is coincident to the WCS, which means the OCS coordinates are equal to the WCS coordinates, most of the time this is true for 2D entities.

OCS entities: ARC, CIRCLE, TEXT, LWPOLYLINE, HATCH, SOLID, TRACE, INSERT, IMAGE

Because ezdxf is just an interface to DXF, it does not automatically convert OCS into WCS, this is the domain of the user/application. These lines convert the center of a 3D circle from OCS to WCS:

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. Ezdxf does not use or support DCS in any way.

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 applications, BricsCAD tries to be as compatible with AutoCAD as possible. Therefore, this information should also apply to AutoCAD.

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

Length Units

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

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

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

Block Units

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

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

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

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

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

HINT:

Angle Units

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

Display Format

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

$INSUNITS

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

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

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

doc.header['$INSUNITS'] = 6

See also enumeration ezdxf.enums.InsertUnits.

$MEASUREMENT

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

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

In BricsCAD the base scaling of linetypes and hatch pattern is defined by the $MEASUREMENT value, the value of $INSUNITS is ignored.

doc.header['$MEASUREMENT'] = 1

See also enumeration ezdxf.enums.Measurement

$LUNITS

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

doc.header['$LUNITS'] = 2

See also enumeration ezdxf.enums.LengthUnits

$AUNITS

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

doc.header['$AUNITS'] = 0

See also enumeration ezdxf.enums.AngularUnits

Helper Tools

Modelspace

The modelspace contains the “real” world representation of the drawing subjects in real world units and is displayed in the tab called “Model” in CAD applications. The modelspace is always present and can’t be deleted.

The modelspace object is acquired by the method modelspace() of the Drawing class and new entities should be added to the modelspace by factory methods: Thematic Index of Layout Factory Methods.

This is a common idiom for creating a new document and acquiring the modelspace:

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

The modelspace can have one or more rectangular areas called modelspace viewports. The modelspace viewports can be used for displaying different views of the modelspace from different locations of the modelspace or viewing directions. It is important to know that modelspace viewports (VPort) are not the same as paperspace viewport entities (Viewport).

SEE ALSO:

Paperspace

A paperspace layout is where the modelspace drawing content is assembled and organized for 2D output, such as printing on a sheet of paper, or as a digital document, such as a PDF file.

Each DXF document can have one or more paperspace layouts but the DXF version R12 supports only one paperspace layout and it is not recommended to rely on paperspace layouts in DXF version R12.

Graphical entities can be added to the paperspace by factory methods: Thematic Index of Layout Factory Methods. Views or “windows” to the modelspace are added as Viewport entities, each viewport displays a region of the modelspace and can have an individual scaling factor, rotation angle, clipping path, view direction or overridden layer attributes.

SEE ALSO:

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.

Block Attributes

A block attribute (Attrib) is a text annotation attached to a block reference with an associated tag. Attributes are often used to add information to block references which can be evaluated and exported by CAD applications.

Extended Block Features

Autodesk added many new features to BLOCKS (dynamic blocks, constraints) as undocumented DXF entities, many of these features are not fully supported by other CAD application and ezdxf also has no support or these features beyond the preservation of these undocumented DXF entities.

SEE ALSO:

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 this 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 paperspace 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 paperspace 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 modelspace (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 paperspace layout, which is the last activated paperspace layout tab, are stored in the header variable $PEXTMIN, $PEXTMAX, $PLIMMIN and $PLIMMAX.

Each paperspace 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

This tutorial shows how to get data from an existing DXF document. If you are a new user of ezdxf, 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

The term layout is used as a synonym for an arbitrary entity space which can contain DXF entities like LINE, CIRCLE, TEXT and so on. Each DXF entity can only reside in exact one layout.

There are three different layout types:

A DXF document consist of exact one modelspace and at least 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

This code shows how to iterate over all DXF entities in modelspace:

# 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

The e.dxftype() method returns the DXF type, the DXF type is always an uppercase string like "LINE". 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 (the DXF attribute does not exist), a DXFValueError will be raised. The get() method returns a default value in this case or None if no default value is specified:

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

or check beforehand if the attribute exist:

if e.dxf.hasattr("paperspace"):
    ...

An unsupported DXF attribute raises a DXFAttributeError, to check if an attribute is supported by an entity use:

if e.dxf.is_supported("paperspace"):
    ...

Getting a paperspace layout

paperspace = doc.paperspace("layout0")

The code above retrieves the paperspace named layout0, the usage of the Paperspace object is the same as of the modelspace object. DXF R12 provides only one paperspace, therefore the paperspace name in the method call doc.paperspace("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 DXF names have to be uppercase. The * search can exclude entity types by adding the entity name with a preceding ! (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 to further refine the query, such as retrieving 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 the source just contains LINE entities.

This could be executed as a single query:

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

An advanced query for getting all modelspace entities at layer construction, but excluding entities with linetype DASHED:

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

Extended EntityQuery Features

The EntityQuery class has properties and overloaded operators to build extended queries by Python features instead of a query string.

Same task as in the previous section but using features of the EntityQuery container:

# The overloaded rational operators return an EntityQuery object and not a bool value!
lines = msp.query("LINES").layer == "construction"
not_dashed_lines = lines.linetype != "DASHED"

SEE ALSO:

Retrieve entities by groupby() function

The groupby() function searches and group entities by a user defined criteria. As an 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 the modelspace matching this layer as dict-value:

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

The entities argument can be any container or generator which yields DXF entities:

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. For a more advanced query 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, the dict-key is a (layer, color) tuple and the dict-value is a list of entities with matching DXF attributes:

def layer_and_color_key(entity):
    # return None to exclude entities from the 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)

The groupby() function catches DXFAttributeError exceptions while processing entities and excludes this entities from the result. 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 DXF Drawings

Create a new DXF document by the ezdxf.new() function:

import ezdxf
# create a new DXF R2010 document
doc = ezdxf.new("R2010")
# add new entities to the modelspace
msp = doc.modelspace()
# add a LINE entity
msp.add_line((0, 0), (10, 0))
# save the DXF document
doc.saveas("line.dxf")

New entities are always added to layouts, a layout can be the modelspace, a paperspace layout or a block layout.

SEE ALSO:

Predefined Resources

Ezdxf creates new DXF documents with as little content as possible, this means only the resources that are absolutely necessary are created. The ezdxf.new() function can create some standard resources, such as linetypes and text styles, by setting the argument setup to True.

import ezdxf
doc = ezdxf.new("R2010", setup=True)
msp = doc.modelspace()
msp.add_line((0, 0), (10, 0), dxfattribs={"linetype": "DASHED"})

The defined standard linetypes are shown in the basic concept section for Linetypes and the available text styles are shown in the Tutorial for Text.

IMPORTANT:

Simple DXF R12 drawings

The r12writer add-on creates simple DXF R12 drawings with a restricted set of DXF types: LINE, CIRCLE, ARC, TEXT, POINT, SOLID, 3DFACE and POLYLINE.

The advantage of the r12writer is the speed and the small memory footprint, all entities are written directly to a file or stream without creating a document structure in memory.

SEE ALSO:

Tutorial for Common Graphical Attributes

The graphical attributes color, linetype, lineweight, true_color, transparency, ltscale and invisible are available for all graphical DXF entities and are located in the DXF namespace attribute dxf of the DXF entities. All these attributes are optional and all except for true_color and transparency have a default value.

Not all of these attributes are supported by all DXF versions. This table shows the minimum required DXF version for each attribute:

Color

Please read the section about the AutoCAD Color Index (ACI) to understand the basics.

The usage of the color attribute is very straight forward. Setting the value is:

entity.dxf.color = 1

and getting the value looks like this:

value = entity.dxf.color

The color attribute has a default value of 256, which means take the color defined by the layer associated to the entity. The ezdxf.colors module defines some constants for often used color values:

entity.dxf.color = ezdxf.colors.RED

The ezdxf.colors.aci2rgb() function converts the ACI value to the RGB value of the default modelspace palette.

SEE ALSO:

True Color

Please read the section about True Color to understand the basics.

The easiest way is to use the rgb property to set and get the true color values as RGB tuples:

entity.rgb = (255, 128, 16)

The rgb property return None if the true_color attribute is not present:

rgb = entity.rgb
if rgb is not None:
    r, g, b = rgb

Setting and getting the true_color DXF attribute directly is possible and the ezdxf.colors module has helper function to convert RGB tuples to 24-bit value and back:

entity.dxf.true_color = ezdxf.colors.rgb2int(255, 128, 16)

The true_color attribute is optional does not have a default value and therefore it is not safe to use the attribute directly, check if the attribute exists beforehand:

if entity.dxf.hasattr("true_color"):
    r, g, b = ezdxf.colors.int2rgb(entity.dxf.true_color)

or use the get() method of the dxf namespace attribute to get a default value if the attribute does not exist:

r, g, b = ezdxf.colors.int2rgb(entity.dxf.get("true_color", 0)

SEE ALSO:

Transparency

Please read the section about Transparency to understand the basics.

It’s recommended to use the transparency property of the DXFGraphic base class. The transparency property is a float value in the range from 0.0 to 1.0 where 0.0 is opaque and 1.0 if fully transparent:

entity.transparency = 0.5

or set the values of the DXF attribute by constants defined in the ezdxf.colors module:

entity.dxf.transparency = ezdxf.colors.TRANSPARENCY_50

The default setting for transparency in CAD applications is always transparency by layer, but the transparency property in ezdxf has a default value of 0.0 (opaque), so there are additional entity properties to check if the transparency value should be taken from the associated entity layer or from the parent block:

if entity.is_transparency_by_layer:
    ...
elif entity.is_transparency_by_block:
    ...
else:
    ...

The top level entity attribute transparency does not support setting transparency by layer or block:

from ezdxf import colors
...
# set transparency by layer by removing the DXF attribute "transparency":
entity.dxf.discard("transparency")
# set transparency by block:
entity.dxf.transparency = colors.TRANSPARENCY_BYBLOCK
# there are also some handy constants in the colors module:
# TRANSPARENCY_10 upto TRANSPARENCY_90 in steps of 10
entity.dxf.transparency = colors.TRANSPARENCY_30  # set 30% transparency
entity.dxf.transparency = colors.OPAQUE

SEE ALSO:

Linetype

Please read the section about Linetypes to understand the basics.

The linetype attribute contains the name of the linetype as string and can be set by the dxf namespace attribute directly:

entity.dxf.linetype = "DASHED"  # linetype DASHED must exist!

The linetype attribute is optional and has a default value of “BYLAYER”, so the attribute can always be used without any concerns:

name = entity.dxf.linetype

WARNING:

Ezdxf creates new DXF documents with as little content as possible, this means only the resources that are absolutely necessary are created. The ezdxf.new() function can create some standard linetypes by setting the argument setup to True:

doc = ezdxf.new("R2010", setup=True)

SEE ALSO:

Lineweight

Please read the section about Lineweights to understand the basics.

The lineweight attribute contains the lineweight as an integer value and can be set by the dxf namespace attribute directly:

entity.dxf.lineweight = 25

The lineweight value is the line width in millimeters times 100 e.g. 0.25mm = 25, but only certain values are valid for more information go to section: Lineweights.

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

The lineweight attribute is optional and has a default value of -1, so the attribute can always be used without any concerns:

lineweight = entity.dxf.lineweight

IMPORTANT:

# activate on screen lineweight display
doc.header["$LWDISPLAY"] = 1

SEE ALSO:

Linetype Scale

The ltscale attribute scales the linetype pattern by a float value and can be set by the dxf namespace attribute directly:

entity.dxf.ltscale = 2.0

The ltscale attribute is optional and has a default value of 1.0, so the attribute can always be used without any concerns:

scale = entity.dxf.ltscale

SEE ALSO:

Invisible

The invisible attribute an boolean value (0/1) which defines if an entity is invisible or visible and can be set by the dxf namespace attribute directly:

entity.dxf.invisible = 1

The invisible attribute is optional and has a default value of 0, so the attribute can always be used without any concerns:

is_invisible = bool(entity.dxf.invisible)

GfxAttribs

When adding new entities to an entity space like the modelspace or a block definition, the factory methods expect the graphical DXF attributes by the argument dxfattribs. This object can be a Python dict where the key is the DXF attribute name and the value is the attribute value, or better use the GfxAttribs object which has some additional validation checks and support for code completions by IDEs:

import ezdxf
from ezdxf.gfxattribs import GfxAttribs
doc = ezdxf.new()
msp = doc.modelspace()
line = msp.add_line(
    (0, 0), (10, 10), dxfattribs=GfxAttribs(layer="0", rgb=(25, 128, 16))
)

SEE ALSO:

Tutorial for Layers

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

Reminder: a layer definition is not required for using a layer!

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

Moving an Entity to a Different Layer

Moving an entity to a different layer is a simple assignment of the new layer name to the layer attribute of the entity.

line = msp.add_line((0, 0), (10, 0), dxfattribs={"layer": "MyLines"})
# move the entity to layer "OtherLayer"
line.dxf.layer = "OtherLayer"

Changing Layer State

Get the layer definition object from the layer table:

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 the color of a layer by property Layer.color, because the DXF attribute Layer.dxf.color is misused for switching the layer on and off, the layer is off if the color value is negative.

Changing the layer properties:

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

SEE ALSO:

Check Available Layers

The LayerTable 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

Renaming a Layer

The Layer class has a method for renaming the layer, but has same limitations, not all places where layer references can occur are documented, third-party entities are black-boxes with unknown content and layer references could be stored in the extended data section of any DXF entity or in a XRECORD entity, so some references may reference a non-existing layer definition after the renaming, at least these references are still valid, because a layer definition is not required for using a layer.

my_lines = doc.layers.get("MyLines")
my_lines.rename("YourLines")

Deleting a Layer Definition

Delete a layer definition:

doc.layers.remove("MyLines")

This just deletes the layer definition, all DXF entities referencing this layer still exist, if they inherit any properties from the deleted layer they will now get the default layer properties.

WARNING:

Deleting All Entities From a Layer

Because of all these uncertainties about layer references mentioned above, deleting all entities referencing a certain layer from a DXF document is not implemented as an API call!

Nonetheless deleting all graphical entities from the DXF document which do reference a certain layer by the layer attribute is a safe procedure:

key_func = doc.layers.key
layer_key = key_func("MyLines")
# The trashcan context-manager is a safe way to delete entities from the
# entities database while iterating.
with doc.entitydb.trashcan() as trash:
    for entity in doc.entitydb.values():
        if not entity.dxf.hasattr("layer"):
            continue
        if layer_key == key_func(entity.dxf.layer):
            # safe destruction while iterating
            trash.add(entity.dxf.handle)

Tutorial for Creating Linetype Pattern

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 removed linetype definition “DASHED” and AutoCAD will not open DXF files including undefined linetypes.

Tutorial for Creating Complex Linetype Pattern

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 Simple DXF Entities

These are basic graphical entities located in an entity space like the modelspace or a block definition and only support the common graphical attributes.

The entities in the following examples are always placed in the xy-plane of the WCS aka the 2D drawing space. Some of these entities can only be placed outside the xy-plane in 3D space by utilizing the OCS, but this feature is beyond the scope of this tutorial, for more information about that go to: Tutorial for OCS/UCS Usage.

Prelude to all following examples:

import ezdxf
from ezdxf.gfxattribs import GfxAttribs
doc = ezdxf.new()
doc.layers.new("ENTITY", color=1)
msp = doc.modelspace()
attribs = GfxAttribs(layer="ENTITY")

SEE ALSO:

Point

The Point entity marks a 3D point in the WCS:

point = msp.add_point((10, 10), dxfattribs=attribs)

All Point entities have the same styling stored in the header variable $PDMODE, for more information read the reference of class Point.

SEE ALSO:

Line

The Line entity is a 3D line with a start- and an end point in the WCS:

line = msp.add_line((0, 0), (10, 10), dxfattribs=attribs)

SEE ALSO:

Circle

The Circle entity is an OCS entity defined by a center point and a radius:

circle = msp.add_circle((10, 10), radius=3, dxfattribs=attribs)

SEE ALSO:

Arc

The Arc entity is an OCS entity defined by a center point, a radius a start- and an end angle in degrees:

arc = msp.add_arc((10, 10), radius=3, start_angle=30, end_angle=120, dxfattribs=attribs)

The arc goes always in counter-clockwise orientation around the z-axis more precisely the extrusion vector of OCS, but this is beyond the scope of this tutorial.

The helper class ezdxf.math.ConstructionArc provides constructors to create arcs from different scenarios:

This example creates an arc from point (10, 0) to point (0, 0) passing the point (5, 3):

from ezdxf.math import ConstructionArc
# -x-x-x- snip -x-x-x-
arc = ConstructionArc.from_3p(
    start_point=(10, 0), end_point=(0, 0), def_point=(5, 3)
)
arc.add_to_layout(msp, dxfattribs=attribs)

SEE ALSO:

Ellipse

The Ellipse entity requires DXF R2000 or newer and is a true WCS entity. The ellipse is defined by a center point, a vector for the major axis, the ratio between major- and minor axis and the start- and end parameter in radians:

ellipse = msp.add_ellipse(
    (10, 10), major_axis=(5, 0), ratio=0.5, start_param=0, end_param=math.pi, dxfattribs=attribs
)

When placed in 3D space the extrusion vector defines the normal vector of the ellipse plane and the minor axis is the extrusion vector cross the major axis.

SEE ALSO:

Further Tutorials

Tutorial for Blocks

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

Create a Block

Blocks are managed as BlockLayout objects by the BlocksSection object, every drawing has only one blocks section referenced by 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 can be created by adding an Insert entity to any of these layout types:

A block reference can be scaled and rotated individually. Lets add some random flags to 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 adding a block reference to a 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.

Block Attributes

A block 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 applications. An attribute can be added to a block reference by the Insert.add_attrib() method, the ATTRIB entity is geometrically not related to the block reference, so insertion point, rotation and scaling of the attribute have to be calculated by the user, but helper tools for that do exist.

Using Attribute Definitions

Another way to add attributes to block references is using attribute templates (AttDef). First create the attribute definition in the block definition, then add the block reference by add_blockref() and attach and fill attributes automatically by the add_auto_attribs() method to the block reference. This method has the advantage that all attributes are placed relative to the block base point with the same rotation and scaling as the block reference, but non-uniform scaling is not handled very well.

The add_auto_blockref() method 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. This method has the disadvantage of a more complex evaluation of attached attributes

Using attribute definitions (AttDef templates):

# 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 the 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 the references of the 'FLAG' block
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 the results may not be perfect. A non-uniform scaling lead to incorrect results for text entities (TEXT, MTEXT, ATTRIB) and some other entities like HATCH with circular- or elliptic path segments. The “exploded” entities are added to the same layout as the block reference by default.

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

Examine Entities of Block References

To just examine the content entities of a block reference use the virtual_entities() method. This methods yields “virtual” entities with properties 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 (lightweight polyline) was introduced in DXF R13/14 and it is defined as a single graphic entity, which differs from the old-style Polyline entity, which is defined as a group of sub-entities. It is recommended to prefer the LWPOLYLINE over the 2D POLYLINE entity because it requires less space in memory and in DXF files and displays faster in AutoCAD.

IMPORTANT:

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 index operator [] 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

The context manager points() can be used to edit polyline points, this method was introduced because accessing individual points was very slow in early versions of ezdxf, in current versions of ezdxf the direct access by the index operator [] is very fast and using the context manager is not required anymore, but the context manager still exist and has the advantage of supporting an 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, delete it to be sure it’s unset:

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

Helper functions to handle bulge values: Bulge Related Functions

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
from ezdxf.enums import TextEntityAlignment
# The TEXT entity is a DXF primitive and is supported in all DXF versions.
# The argument setup=True creates standard linetypes and text styles in the
# new DXF document.
doc = ezdxf.new("R12", setup=True)
msp = doc.modelspace()
# Use method set_placement() to define the TEXT alignment, because the
# relations between the DXF attributes 'halign', 'valign', 'insert' and
# 'align_point' are tricky.
msp.add_text("A Simple Text").set_placement(
    (2, 3),
    align=TextEntityAlignment.MIDDLE_RIGHT
)
# Using a predefined text style:
msp.add_text(
    "Text Style Example: Liberation Serif",
    height=0.35,
    dxfattribs={"style": "LiberationSerif"}
).set_placement((2, 6), align=TextEntityAlignment.LEFT)
doc.saveas("simple_text.dxf")

Alignments defined by the enum TextEntityAlignment:

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]

IMPORTANT:

New Text Style

Creating a new text style is simple:

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

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, otherwise 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 and Tutorial for UCS Based Transformations.

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.

IMPORTANT:

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

The MText entity has an alias MText.dxf.text for the MText.text attribute for compatibility to the Text entity.

IMPORTANT:

Text placement

The location of the MTEXT entity is defined by the MText.dxf.insert and the MText.dxf.attachment_point attributes in WCS coordinates. 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. 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 the support class MTextEditor.

Stacked text

MTEXT 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 the support class MTextEditor.

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

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

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 from the SPLINE entity:

# 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

Creating splines from fit points is the easiest way, 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) uses an unknown proprietary algorithm to generate control points and knot values from fit points. 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 passing the given 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)
spline.dxf.end_tangent = (1, 0, 0)

Get data count as stored in DXF attributes:

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

Get data count from 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 also 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_mesh(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 a bunch of 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)

SEE ALSO:

Tutorial for Mesh

The Mesh entity is a 3D object in WCS build up from vertices and faces.

Create a cube mesh by directly accessing the 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 using the edit_data() context manager of the Mesh class and 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")

Its recommended to use the MeshBuilder objects to create 3D meshes and render them as MESH entities by the render_mesh() 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_mesh(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 a bunch of 3DFACE entities
cube.render_3dfaces(msp, dxfattribs=blue)
doc.saveas("meshes.dxf")

There exist some tools to manage meshes:

The ezdxf.render.forms module provides function to create basic geometries like cube, cone, sphere and so on and functions to create meshes from profiles by extrusion, rotation or sweeping.

This example shows how to sweep a gear profile along a helix:

import ezdxf
from ezdxf.render import forms
doc = ezdxf.new()
doc.layers.add("MESH", color=ezdxf.colors.YELLOW)
msp = doc.modelspace()
# sweeping a gear-profile
gear = forms.gear(
    8, top_width=0.01, bottom_width=0.02, height=0.02, outside_radius=0.1
)
helix = path.helix(radius=2, pitch=1, turns=6)
# along a helix spine
sweeping_path = helix.flattening(0.1)
mesh = forms.sweep(gear, sweeping_path, close=True, caps=True)
# and render as MESH entity
mesh.render_mesh(msp, dxfattribs={"layer": "MESH"})
doc.saveas("gear_along_helix.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)

SEE ALSO:

Tutorial for Hatch Pattern Definition

A hatch pattern consist of one or more hatch lines. A hatch line defines a set of lines which have the same orientation an the same line pattern. All the lines defined by a hatch line are parallel and have a constant distance to each other. The origin defines the start point of the hatch line and also the starting point of the line pattern. The direction defines the angle between the WCS x-axis and the hatch line. The offset is a 2D vector which will be added consecutively the the origin for each new hatch line. The line pattern has the same format as as the simple linetype pattern (Tutorial for Creating Linetype Pattern).

IMPORTANT:

The first example creates a simple pattern of horizontal solid lines with a vertical distance of 0.5 drawing units.

import ezdxf
doc = ezdxf.new("R2010")
msp = doc.modelspace()
hatch = msp.add_hatch()
hatch.set_pattern_fill(
    "MyPattern",
    color=7,
    angle=0,
    scale=1.0,
    style=0,  # normal hatching style
    pattern_type=0,  # user-defined
    # pattern definition as list of:
    # [angle in degree, origin as 2d vector, offset as 2d vector, line pattern]
    # line pattern is a solid line
    definition=[[0, (0, 0), (0, 0.5), []]],
)
points = [(0, 0), (10, 0), (10, 10), (0, 10)]
hatch.paths.add_polyline_path(points)
msp.add_lwpolyline(points, close=True, dxfattribs={"color": 1})
doc.saveas("user_defined_hatch_pattern.dxf")

The next example shows how the offset value works:

# -x-x-x- snip -x-x-x-
hatch = msp.add_hatch()
hatch.set_pattern_fill(
    "MyPattern",
    color=7,
    angle=0,
    scale=1.0,
    style=0,  # normal hatching style
    pattern_type=0,  # user-defined
    # the line pattern is a dashed line:  - - - -
    # the offset is 1 unit vertical and 0.3 units horizontal
    # [angle in degree, origin as 2d vector, offset as 2d vector, line pattern]
    definition=[[0, (0, 0), (0.3, 1), [1, -1]]],
)
# -x-x-x- snip -x-x-x-

The next example combines two parallel hatch lines, the origin defines how the hatch lines are offset from each other:

# -x-x-x- snip -x-x-x-
hatch = msp.add_hatch()
hatch.set_pattern_fill(
    "MyPattern",
    color=7,
    angle=0,
    scale=1.0,
    style=0,  # normal hatching style
    pattern_type=0,  # user-defined
    # [angle in degree, origin as 2d vector, offset as 2d vector, line pattern]
    definition=[
        [0, (0, 0), (0.3, 1), [1, -1]],  # dashed line
        [0, (0, 0.5), (0, 1), []],  # solid line
    ],
)
# -x-x-x- snip -x-x-x-

The next example combines two hatch lines with different angles. The origins can be the same for this example. The Vec2 class is used to calculate the offset value for a normal distance of 0.7 drawing units between the slanted lines:

from ezdxf.math import Vec2
# -x-x-x- snip -x-x-x-
hatch = msp.add_hatch()
# offset vector for a normal distance of 0.7 for a 45 deg slanted hatch line
offset = Vec2.from_deg_angle(45 + 90, length=0.7)
hatch.set_pattern_fill(
    "MyPattern",
    color=7,
    angle=0,
    scale=1.0,
    style=0,  # normal hatching style
    pattern_type=0,  # user-defined
    # [angle in degree, origin as 2d vector, offset as 2d vector, line pattern]
    definition=[
        [0, (0, 0), (0, 1), [1, -1]],  # horizontal dashed line
        [45, (0, 0), offset, []],  # slanted solid line
    ],
)
# -x-x-x- snip -x-x-x-

Tutorial for Image and ImageDef

This example shows how to use a raster image in a DXF document. Each IMAGE entity requires an associated IMAGEDEF entity in the objects section, which stores the filename of the linked image and the size in pixels. Multiple IMAGE entities can share the same IMAGEDEF entity.

IMPORTANT:

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

This example shows hot to insert a a PDF, DWF, DWFx or DGN file as drawing underlay. Each UNDERLAY entity requires an associated UNDERLAYDEF entity in the objects section, which stores the filename of the linked document and the parameters of the underlay. Multiple UNDERLAY entities can share the same UNDERLAYDEF entity.

IMPORTANT:

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 MultiLeader

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.

    ml_builder = msp.add_multileader_mtext("Standard")

Set MTEXT content, text style and alignment.

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

    ml_builder.add_leader_line(mleader.ConnectionSide.left, [Vec2(-20, -15)])

More than one vertex per leader can be used:

    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.

    ml_builder.build(insert=Vec2(5, 0))

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.

    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)])
    ml_builder.build(insert=Vec2(15, 0))

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.

    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)])
    ml_builder.build(insert=Vec2(5, 0))

A centered MTEXT alignment gives a more even result.

    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)])
    ml_builder.build(insert=Vec2(10, 0))

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

Tutorial for Viewports in Paperspace

This tutorial is based on the example script viewports_in_paperspace.py. The script creates DXF files for the version R12 and for R2000+, but the export for DXF R12 has a wrong papersize in BricsCAD and wrong margins in Autodesk DWG Trueview. I don’t know why this happens and I don’t waste my time to fix this.

IMPORTANT:

The scripts creates three flat geometries in the xy-plane of the WCS and a 3D mesh as content of the modelspace: [image]

Page Setup

The paperspace layout feature lacks documentation in the DXF reference, there is no information in practice on how it is used, so most of the information here is assumptions gathered through trail and error.

The page_setup() method defines the properties of the paper sheet itself. The units of the modelspace and the paperspace are not related and can even have different unit systems (imperial, meters), but to keep things simple it’s recommended to use the same unit system for both spaces.

layout.page_setup(size=(24, 18), margins=(1, 1, 1, 1), units="inch")

The size argument defines the overall paper size in rotation mode 0, it seems to be the best practice to define the paper extents in landscape mode and rotate the paper by the rotate argument afterwards.

Choices for the rotation argument:

The scale argument reflects the relationship between paper unit and drawing unit in paperspace. It’s recommended to let this scale at the default value of 1:1 and draw lines and text in paperspace with the same units as you defined the paper size.

SEE ALSO:

Drawing in Paperspace

You can add DXF entities to the paperspace like to any other layout space. The coordinate origin (0, 0) is in the left bottom corner of the canvas which is the paper size minus the margins. You can draw beyond this limits but CAD applications may not print that content.

HINT:

Adding Viewports

The Viewport entity is a window to the modelspace to display the content of the modelspace in paperspace with an arbitrary scaling and rotation. The VIEWPORT entity will be added by the factory method add_viewport(), the center argument defines the center and the size argument defines the width and height of the of the VIEWPORT in paperspace. The source of the modelspace to display is defined by the arguments view_center_point and view_height. [image]

Scaling Factor

The scaling factor of the VIEWPORT is not an explicit value, the factor is defined by the relation of the VIEWPORT height of the size argument and the view_height argument.

If both values are equal the scaling is 1:1

paperspace.add_viewport(
    center=(14.5, 2.5),
    size=(5, 5),
    view_center_point=(12.5, 7.5),
    view_height=5,
)

If the view_height is 5x larger than the VIEWPORT height the scaling is 1:5

paperspace.add_viewport(
    center=(8.5, 2.5),
    size=(5, 5),
    view_center_point=(10, 5),
    view_height=25,
)

View Direction

The default view direction is the top down view, but can be changed to any view by the attributes view_target_point and view_direction_vector of the dxf namespace.

vp = paperspace.add_viewport(
    center=(16, 10), size=(4, 4), view_center_point=(0, 0), view_height=30
)
vp.dxf.view_target_point = (40, 40, 0)
vp.dxf.view_direction_vector = (-1, -1, 1)

Viewport Frame

The VIEWPORT frame (borderlines) are shown in paperspace by default. The VIEWPORT entity does not have an attribute to change this. The visibility of the VIEWPORT frame is controlled by the layer assigned to the VIEWPORT entity which is the layer “VIEWPORTS” by default in ezdxf. Turning off this layer hides the frames of the VIEWPORT entities on this layer, to do that the layer “VIEWPORTS” have to be created by the library user:

vp_layer = doc.layers.add("VIEWPORTS")
vp_layer.off()

Freeze Layers

Each VIEWPORT can have individual frozen layers, which means the layers are not visible in this VIEWPORT. To freeze layers in a VIEWPORT assign the names of the frozen layers as a list-like object to the frozen_layers attribute of the VIEWPORT entity:

vp.frozen_layers = ["Layer0", "Layer1"]

IMPORTANT:

SEE ALSO:

Override Layer Properties

Each VIEWPORT can override layer properties individually. These overrides are stored in the Layer entity and referenced by the handle of the VIEWPORT. This procedure is a bit more complex and shown in the example file viewports_override_layer_attributes.py.

layer = doc.layers.get("Layer0")
override = layer.get_vp_overrides()
override.set_linetype(vp.dxf.handle, "DASHED")
override.commit()

Supported property overrides:

SEE ALSO:

Tutorial for OCS/UCS Usage

For OCS/UCS usage is a basic understanding of vector math 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 and directions 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 as a 3D point, where the z-values of this point is the elevation height and the x-value and the y-value are 0.

Thickness

Defines the extrusion distance for an entity.

NOTE:

Placing 2D Circle in 3D Space

The colors of the system 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 the OCS and the 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 pointing in the same direction (extrusion direction), and the x-axis of the UCS and the WCS pointing also in 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 the UCS, the OCS and the 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 of placing text in 3D space is the text rotation, which is always counter clockwise around the OCS z-axis, and 0 degree is the 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 the 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.

Placement by OCS coordinates and rotation about the OCS z-axis, can be achieved the same way as for generic 2D entities. 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

The ezdxf version v0.13 introduced a transformation interface for DXF primitives, which makes working with OCS/UCS much easier. This is a new edition of the Tutorial for OCS/UCS Usage. Please read the old tutorial for the basics about the OCS.

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,
    }
).transform(ucs.matrix)

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

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. The 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 DXF primitives like LINE and TEXT entities, this representation is called the dimension line rendering in this documentation, beside the fact that 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 this value 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 will be displayed, but these 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 the 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 shapely.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__
shapely_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. 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 is 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: