--- name: "ezdxf" section: "1" platform: "linux" package: "python3-ezdxf" version: "1.4.1-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ezdxf" --- # ezdxf(1) ezdxf Documentation \[image\] Welcome! This is the documentation for ezdxf release 1.4.1, last updated May 05, 2025. ## NAME ezdxf - ezdxf Documentation \[image\] Welcome! This is the documentation for ezdxf release 1.4.1, last updated May 05, 2025. - • *ezdxf* is a Python package to create new DXF documents and read/modify/write existing DXF documents - • MIT-License - • the intended audience are programmers - • requires at least Python 3.9 - • OS independent - • tested with CPython and pypy3 - • has type annotations and passes **mypy --ignore-missing-imports -p ezdxf** successful - • additional required packages for the core package without add-ons: *typing\_extensions*, *pyparsing*, *numpy*, *fontTools* - • read/write/new support for DXF versions: R12, R2000, R2004, R2007, R2010, R2013 and R2018 - • additional read-only support for DXF versions R13/R14 (upgraded to R2000) - • additional read-only support for older DXF versions than R12 (upgraded to R12) - • read/write support for ASCII DXF and Binary DXF - • retains third-party DXF content - • optional C-extensions for CPython are included in the binary wheels, available on *PyPI* for Windows, Linux and macOS ## INCLUDED EXTENSIONS Additional packages required for these add-ons are not automatically installed during the *basic* setup, for more information about the setup & dependencies visit the *documentation*. - • *drawing* add-on to visualise and convert DXF files to images which can be saved as PNG, PDF or SVG files - • *r12writer* add-on to write basic DXF entities direct and fast into a DXF R12 file or stream - • *iterdxf* add-on to iterate over DXF entities from the modelspace of huge DXF files (\> 5GB) which do not fit into memory - • *importer* add-on to import entities, blocks and table entries from another DXF document - • *dxf2code* add-on to generate Python code for DXF structures loaded from DXF documents as starting point for parametric DXF entity creation - • *acadctb* add-on to read/write *Plot Style Files (CTB/STB)* - • *pycsg* add-on for Constructive Solid Geometry (CSG) modeling technique - • *MTextExplode* add-on for exploding MTEXT entities into single-line TEXT entities - • *text2path* add-on to convert text into outline paths - • *geo* add-on to support the *\_\_geo\_interface\_\_* - • *meshex* add-on for exchanging meshes with other tools as STL, OFF or OBJ files - • *openscad* add-on, an interface to *OpenSCAD* - • *odafc* add-on, an interface to the *ODA File Converter* to read and write DWG files - • **hpgl2** add-on for converting *HPGL/2* plot files to DXF, SVG and PDF ## WEBSITE *https://ezdxf.mozman.at/* ## DOCUMENTATION Documentation of development version at *https://ezdxf.mozman.at/docs* Documentation of latest release at *http://ezdxf.readthedocs.io/* ## KNOWLEDGE GRAPH The *Knowledge Graph* contains additional information beyond the documentation and is managed by *logseq*. The source data is included in the repository in the folder **ezdxf/notes**. There is also a *HTML export* on the website which gets regular updates. ## RELEASE NOTES The *release notes* are included in the *Knowledge Graph*. ## CHANGELOG The *changelog* is included in the *Knowledge Graph*. ## SOURCE CODE & FEEDBACK Source Code: *http://github.com/mozman/ezdxf.git* Issue Tracker: *http://github.com/mozman/ezdxf/issues* Forum: *https://github.com/mozman/ezdxf/discussions* ## QUESTIONS AND ANSWERS Please post questions at the *forum* or *stack overflow* to make answers available to other users as well. ## INTRODUCTION ### 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 - • *ezdxf* is not a DXF converter: *ezdxf* can not convert between different DXF versions, if you are looking for an appropriate application, try the free *ODAFileConverter* from the *Open Design Alliance*, which converts between different DXF version and also between the DXF and the DWG file format. - • *ezdxf* is not a CAD file format converter: *ezdxf* can not convert DXF files to other CAD formats such as DWG - • *ezdxf* is not a CAD kernel and does not provide high level functionality for construction work, it is just an interface to the DXF file format. If you are looking for a CAD kernel with *Python* scripting support, look at *FreeCAD*. ### Supported Python Versions *Ezdxf* requires at least Python 3.9 (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.9). ### Supported DXF Versions | | | | --- | --- | | Version | AutoCAD Release | | AC1009 | AutoCAD R12 | | AC1012 | AutoCAD R13 -\> R2000 | | AC1014 | AutoCAD R14 -\> R2000 | | AC1015 | AutoCAD R2000 | | AC1018 | AutoCAD R2004 | | AC1021 | AutoCAD R2007 | | AC1024 | AutoCAD R2010 | | AC1027 | AutoCAD R2013 | | AC1032 | AutoCAD R2018 | *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*. ## SETUP & DEPENDENCIES The primary goal is to keep the dependencies of the *core* package as small as possible. The add-ons are not part of the core package and can therefore use as many packages as needed. The only requirement for these packages is an easy way to install them on *Windows*, *Linux* and *macOS*, preferably as: ``` pip3 install ezdxf ``` The packages *pyparsing*, *numpy*, *fontTools* and *typing\_extensions* are the hard dependency and will be installed automatically by *pip3*! The minimal required Python version is determined by the latest release version of *numpy*. ### 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] ``` | | | | --- | --- | | Tag | Additional Installed Packages | | **\[draw\]** | *Matplotlib*, *PySide6*, *PyMuPDF*, *Pillow* | | **\[dev\]** | **\[draw\]** + setuptools, wheel, Cython, pytest (full development setup) | If *PySide6* is not available on your system, use *PyQt5* by this options: | | | | --- | --- | | Tag | Additional Installed Packages | | **\[draw5\]** | *Matplotlib*, *PyQt5*, *PyMuPDF*, *Pillow* | | **\[dev5\]** | **\[draw5\]** + setuptools, wheel, Cython, pytest (full development setup) | ### 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*: - • *Windows*: only amd64 packages - • *Linux*: manylinux and musllinux packages for x86\_64 & aarch64 - • *macOS*: x86\_64, arm64 and universal packages 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 Make a build directory and a virtual environment: ``` mkdir build cd build py -m venv .venv .venv/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\.venv\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 .venv source .venv/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/.venv/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 .venv source .venv/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/.venv/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 .venv source .venv/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* 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 the *drawing* add-on will not work. Proceed with the *ezdxf* installation from source as shown for the *Raspberry Pi OS*. ## USAGE FOR BEGINNERS This section shows the intended usage of the *ezdxf* package. This is just a brief overview for new *ezdxf* users, follow the provided links for more detailed information. First import the package: ``` import ezdxf ``` ### 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:** Documentation for *ezdxf.readfile()*, *ezdxf.readzip()* and *ezdxf.read()*, for more information about file management go to the *Document Management* section. For loading DXF documents with structural errors look at the *ezdxf.recover* module. ### 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:** For more information go to the *Tutorial for Getting Data from DXF Files* ### 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:** - • *Common graphical DXF attributes* - • Helper class *ezdxf.gfxattribs.GfxAttribs* for building DXF attribute dictionaries. ### 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:** - • *Tutorial for Creating DXF Drawings* - • Documentation for *ezdxf.new()*, for more information about file management go to the *Document Management* section. ### 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: - • *Modelspace* - • *Paperspace* - • *BlockLayout* 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:** Do not instantiate DXF entities by yourself and add them to layouts, always use the provided factory methods to create new graphical entities, this is the intended way to use *ezdxf*. **SEE ALSO:** - • *Thematic Index of Layout Factory Methods* - • *Tutorial for Creating DXF Drawings* - • *Tutorial for Simple DXF Entities* - • *Tutorial for LWPolyline* - • *Tutorial for Text* - • *Tutorial for MText and MTextEditor* - • *Tutorial for Hatch* ### 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:** Documentation for *ezdxf.document.Drawing.save()* and *ezdxf.document.Drawing.saveas()*, for more information about file management go to the *Document Management* section. ### Create New Blocks The block definitions of a DXF document are managed by the *BlocksSection* object: ``` my_block = doc.blocks.new("MyBlock") ``` **SEE ALSO:** *Tutorial for Blocks* ### 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:** See *Tutorial for Blocks* for more advanced features like using *Attrib* entities. ### 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:** *Layers* ### 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 - • *Basic Concepts*: what is the meaning or purpose of … - • *Tasks*: how to accomplish certain tasks - • *Reference* ## BASIC CONCEPTS The Basic Concepts section teach the intended meaning of DXF attributes and structures without teaching the application of this information or the specific implementation by *ezdxf*, if you are looking for more information about the *ezdxf* internals look at the *Reference* section or if you want to learn how to use *ezdxf* go to the *Tutorials* section and for the solution of specific problems go to the *Howto* section. ### What is DXF? The common assumption is also the cite of *Wikipedia*: AutoCAD DXF (Drawing eXchange Format) is a CAD data file format developed by Autodesk for enabling data interoperability between AutoCAD and **other** applications. DXF was originally introduced in December 1982 as part of AutoCAD 1.0, and was intended to provide an exact representation of the data in the AutoCAD native file format, DWG (Drawing). For many years Autodesk did not publish specifications making correct imports of DXF files difficult. Autodesk now publishes the DXF specifications online. The more precise cite from the *DXF reference* itself: The DXF™ format is a tagged data representation of all the information contained in an AutoCAD® drawing file. Tagged data means that each data element in the file is preceded by an integer number that is called a group code. A group code’s value indicates what type of data element follows. This value also indicates the meaning of a data element for a given object (or record) type. Virtually all user-specified information in a drawing file can be represented in DXF format. 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: - • *AutoCAD* and *Trueview* - • CAD applications based on the *OpenDesignAlliance* (ODA) SDK, see also *ODA on wikipedia*, even *Autodesk* is a corporate member, see their blog post from *22 Sep 2020* at *adsknews* but only to use the ODA IFC tools and not to improve the DWG/DXF compatibility - • *BricsCAD* (ODA based) - • *GstarCAD* (ODA based) - • *ZWCAD* (ODA based) 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:** Please do not submit bug reports based on the use of *LibreCAD* or *QCAD*, these applications are in no way reliable regarding the DXF format and I will not waste my time on them. ### 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: - • LINE and POLYLINE: These are the basic building blocks of a DXF file. They represent straight and curved lines. - • CIRCLE and ARC: These entities represent circles and portions of circles, respectively. - • TEXT and MTEXT: DXF files can also contain text entities, which can be used to label parts of the design or provide other information. - • HATCH: DXF files can also include hatch patterns, which are used to fill in areas with a specific pattern or texture. - • DIMENSION: DXF files can also contain dimension entities, which provide precise measurements of the various elements in a design. - • INSERT: A block is a group of entities that can be inserted into a design multiple times by the INSERT entity, making it a useful way to reuse elements of a design. 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: - • DICTIONARY: A dictionary object consists of a series of name-value pairs, where the name is a string that identifies a specific object within the dictionary, and the value is a reference to that object. The objects themselves can be any type of DXF entity or custom object defined in the DXF file. - • XRECORD entities are used to store custom application data in a DXF file. - • the LAYOUT entity is a DXF entity that represents a single paper space layout in a DXF file. Paper space is the area in a CAD drawing that represents the sheet of paper or other physical media on which the design will be plotted or printed. - • MATERIAL, MLINESTYLE, MLEADERSTYLE definitions stored in certain DICTIONARY objects. - • A GROUP entity contains a list of handles that refer to other DXF entities in the drawing. The entities in the group can be of any type, including entities from the model space or paper space layouts. ### 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:** *Tutorial for Getting Data from DXF Files* ### 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:** - • *ezdxf.query* module - • *ezdxf.entitydb* module Graphical entities are stored in blocks, the modelspace or paperspace layouts. - • The **doc.modelspace()** function returns the *Modelspace* instance - • The **doc.paperspace()** returns a *Paperspace* instance - • The **doc.blocks** attribute provides access to the *BlocksSection* 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: - • The **doc.objects** attribute provides access to the *ObjectsSection*. Resource definitions like *Layer*, *Linetype* or *Textstyle* are stored in resource tables: - • **doc.layers**: the *LayerTable* - • **doc.linetypes**: the *LinetypeTable* - • **doc.styles**: the *TextstyleTable* - • **doc.dimstyles**: the *DimStyleTable* **IMPORTANT:** A layer assignment is just an attribute of a DXF entity, it’s not an entity container! **SEE ALSO:** - • Basic concept of the *Modelspace* - • Basic concept of *Paperspace* layouts - • Basic concept of *Blocks* - • *Tutorial for Getting Data from DXF Files* ### 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:** - • *Thematic Index of Layout Factory Methods* - • Reference of the *BaseLayout* class - • *Tutorial for Simple DXF Entities* ### 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:** - • *Plot Style Files (CTB/STB)* - • *ezdxf.colors* - • *Tutorial for Common Graphical Attributes* - • Autodesk Knowledge Network: *About Setting the Color of Objects* - • BricsCAD Help Center: *Entity Color* ### 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:** - • *ezdxf.colors* - • *Tutorial for Common Graphical Attributes* - • Autodesk Knowledge Network: *About Setting the Color of Objects* - • BricsCAD Help Center: *Entity Color* ### 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:** - • *ezdxf.colors* - • *Tutorial for Common Graphical Attributes* - • Autodesk Knowledge Network: *About Making Objects Transparent* - • BricsCAD Help Center: *Entity Transparency* ### 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: - • Layers give you a way to turn groups of objects on and off - both on the screen and on the plot. - • Layers provide the most efficient way of controlling object color and linetype 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. - • ON: the layer is visible, entities on that layer are visible, selectable and editable - • OFF: the layer is not visible, entities on that layer are not visible, not selectable and not editable - • FROZEN: the layer is not visible, entities on that layer are not visible, not selectable and not editable, very similar to the OFF status but layers can be frozen individually in VIEWPORTS and freezing layers may speed up some commands in CAD applications like ZOOM, PAN or REGEN. - • LOCKED: the layer is visible, entities on that layer are visible but not selectable and not editable ### 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:** - • *Tutorial for Layers* - • *Tutorial for Viewports in Paperspace* - • Autodesk Knowledge Network: *About Layers* - • BricsCAD Help Center: *Working with Layers* ### 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) ``` \[image\] In DXF R13 Autodesk introduced complex linetypes which can contain text or shapes. **SEE ALSO:** - • *Tutorial for Common Graphical Attributes* - • *Tutorial for Creating Linetype Pattern* - • Autodesk Knowledge Network: *About Linetypes* - • BricsCAD Help Center: *Entity Linetype* ### 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* | | | | --- | --- | | -1 | LINEWEIGHT\_BYLAYER | | -2 | LINEWEIGHT\_BYBLOCK | | -3 | LINEWEIGHT\_DEFAULT | 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 ``` \[image\] The lineweight value can be overridden by *CTB* or *STB* files. **SEE ALSO:** - • Autodesk Knowledge Network: *About Lineweights* - • BricsCAD Help Center: *Entity Lineweight* ### 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:** - • Table entry **UCS** - • *ezdxf.math.UCS* - converter between WCS and UCS ### 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:** - • *Object Coordinate System (OCS)* - deeper insights into OCS - • *ezdxf.math.OCS* - converter between WCS and OCS ### 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) - • *DXF Reference for OCS* provided by Autodesk. 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: - • Its origin coincides with the WCS origin. - • The orientation of the x- and y-axis within the xy-plane are calculated in an arbitrary but consistent manner. AutoCAD performs this calculation using the arbitrary axis algorithm (see below). - • Because of the *Arbitrary Axis Algorithm* the OCS can only represent a **right-handed** coordinate system! 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. - • *Line* - • *Point* - • **3DFace** - • *Polyline* (3D) - • *Vertex* (3D) - • *Polymesh* - • *Polyface* - • *Viewport* 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. - • *Circle* - • *Arc* - • *Solid* - • *Trace* - • *Text* - • *Attrib* - • **Attdef** - • *Shape* - • *Insert* - • *Polyline* (2D) - • *Vertex* (2D) - • *LWPolyline* - • *Hatch* - • *Image* 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 - • *DXF Reference for Arbitrary Axis Algorithm* provided by Autodesk. 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) ``` **SEE ALSO:** - • *ezdxf.math.OCS* management class - • The *ezdxf.entities.DXFGraphic.ocs()* method returns the *OCS* of a graphical DXF entity. - • *Tutorial for OCS/UCS Usage* ### DXF Units The *DXF reference* has no explicit information how to handle units in DXF, any information in this section is based on experiments with BricsCAD and may differ in other CAD applications, BricsCAD tries to be as compatible with AutoCAD as possible. Therefore, this information should also apply to AutoCAD. Please open an issue on *github* if you have any corrections or additional information about this topic. ### Length Units Any length or coordinate value in DXF is unitless in the first place, there is no unit information attached to the value. The unit information comes from the context where a DXF entity is used. The document/modelspace get the unit information from the header variable $INSUNITS, paperspace and block layouts get their unit information from the attribute *units*. The modelspace object has also a **units** property, but this value do not represent the modelspace units, this value is always set to 0 “unitless”. Get and set document/modelspace units as enum by the *Drawing* property **units**: ``` import ezdxf from ezdxf import units doc = ezdxf.new() # Set centimeter as document/modelspace units doc.units = units.CM # which is a shortcut (including validation) for doc.header['$INSUNITS'] = units.CM ``` ### Block Units As said each block definition can have independent units, but there is no implicit unit conversion applied, not in CAD applications and not in *ezdxf*. When inserting a block reference (INSERT) into the modelspace or another block layout with different units, the scaling factor between these units **must** be applied explicit as DXF attributes (**xscale**, …) of the *Insert* entity, e.g. modelspace in meters and block in centimeters, x-, y- and z-scaling has to be 0.01: ``` doc.units = units.M my_block = doc.blocks.new('MYBLOCK') my_block.units = units.CM block_ref = msp.add_block_ref('MYBLOCK') # Set uniform scaling for x-, y- and z-axis block_ref.set_scale(0.01) ``` Use helper function *conversion\_factor()* to calculate the scaling factor between units: ``` factor = units.conversion_factor(doc.units, my_block.units) # factor = 100 for 1m is 100cm # scaling factor = 1 / factor block_ref.set_scale(1.0/factor) ``` **HINT:** It is never a good idea to use different measurement system in one project, ask the NASA about their Mars Climate Orbiter from 1999. The same applies for units of the same measurement system, just use one unit like meters or inches. ### Angle Units Angles are always in degrees (360 deg = full circle) in counter-clockwise orientation, unless stated explicit otherwise. ### Display Format How values are shown in the CAD GUI is controlled by the header variables $LUNITS and $AUNITS, but this has no meaning for values stored in DXF files. ### $INSUNITS The most important setting is the header variable $INSUNITS, this variable defines the drawing units for the modelspace and therefore for the DXF document if no further settings are applied. The modelspace LAYOUT entity has a property *units* as any layout like object, but it seem to have no meaning for the modelspace, BricsCAD set this property always to 0, which means unitless. The most common units are 6 for meters and 1 for inches. ``` doc.header['$INSUNITS'] = 6 ``` | | | | --- | --- | | 0 | Unitless | | 1 | Inches, **units.IN** | | 2 | Feet, **units.FT** | | 3 | Miles, **units.MI** | | 4 | Millimeters, **units.MM** | | 5 | Centimeters, **units.CM** | | 6 | Meters, **units.M** | | 7 | Kilometers, **units.KM** | | 8 | Microinches | | 9 | Mils | | 10 | Yards, **units.YD** | | 11 | Angstroms | | 12 | Nanometers | | 13 | Microns | | 14 | Decimeters, **units.DM** | | 15 | Decameters | | 16 | Hectometers | | 17 | Gigameters | | 18 | Astronomical units | | 19 | Light years | | 20 | Parsecs | | 21 | US Survey Feet | | 22 | US Survey Inch | | 23 | US Survey Yard | | 24 | US Survey Mile | See also enumeration *ezdxf.enums.InsertUnits*. ### $MEASUREMENT The header variable $MEASUREMENT controls whether the current drawing uses imperial or metric hatch pattern and linetype files: This setting is independent from $INSUNITS, it is possible to set the drawing units to inch and use metric linetypes and hatch pattern. In BricsCAD the base scaling of linetypes and hatch pattern is defined by the $MEASUREMENT value, the value of $INSUNITS is ignored. ``` doc.header['$MEASUREMENT'] = 1 ``` | | | | --- | --- | | 0 | English | | 1 | Metric | See also enumeration *ezdxf.enums.Measurement* ### $LUNITS The header variable $LUNITS defines how CAD applications display linear values in the GUI and has no meaning for *ezdxf*: ``` doc.header['$LUNITS'] = 2 ``` | | | | --- | --- | | 1 | Scientific | | 2 | Decimal (default) | | 3 | Engineering | | 4 | Architectural | | 5 | Fractional | See also enumeration *ezdxf.enums.LengthUnits* ### $AUNITS The header variable $AUNITS defines how CAD applications display angular values in the GUI and has no meaning for *ezdxf*, DXF angles are always stored as degrees in counter-clockwise orientation, unless stated explicit otherwise: ``` doc.header['$AUNITS'] = 0 ``` | | | | --- | --- | | 0 | Decimal degrees | | 1 | Degrees/minutes/seconds | | 2 | Grad | | 3 | Radians | See also enumeration *ezdxf.enums.AngularUnits* ### Helper Tools - **ezdxf.units.conversion\_factor(source\_units: *InsertUnits*, target\_units: *InsertUnits*) -\> float** Returns the conversion factor to represent *source\_units* in *target\_units*. E.g. millimeter in centimeter **conversion\_factor(MM, CM)** returns 0.1, because 1 mm = 0.1 cm - **ezdxf.units.unit\_name(enum: int) -\> str** Returns the name of the unit enum. - **ezdxf.units.angle\_unit\_name(enum: int) -\> str** Returns the name of the angle unit enum. ### 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:** - • Reference of class *Modelspace* - • *Thematic Index of Layout Factory Methods* - • Example for usage of modelspace viewports: *tiled\_window\_setup.py* ### 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:** - • Reference of class *Paperspace* - • *Thematic Index of Layout Factory Methods* - • Example for usage of paperspace viewports: *viewports\_in\_paperspace.py* ### 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:** - • *Blocks* Section - • *Tutorial for Blocks* ### 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:** The AutoCAD online reference for the *ZOOM* and the *LIMITS* command. ### 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:** How to: *Calculate Extents for the Modelspace* ### 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. ## TASKS These topics provide brief overviews of how to complete specific tasks, but they’re not comprehensive tutorials. For a deeper understanding, explore the beginner’s guide, explanations of basic concepts, in-depth tutorials, the reference guide, example code, and even the source code itself. ### Add Data ### Add DXF Entities ### Layout Factory Methods Recommended way to create DXF entities. For all supported entities exist at least one factory method in the *ezdxf.layouts.BaseLayout* class. All factory methods have the prefix: **add\_...** ``` import ezdxf doc = ezdxf.new() msp = doc.modelspace() msp.add_line((0, 0, 0), (3, 0, 0), dxfattribs={"color": 2}) ``` ### Thematic Index of Layout Factory Methods ### DXF Primitives - • *add\_3dface()* - • *add\_arc()* - • *add\_circle()* - • *add\_ellipse()* - • *add\_hatch()* - • *add\_helix()* - • *add\_image()* - • *add\_leader()* - • *add\_line()* - • *add\_lwpolyline()* - • *add\_mesh()* - • *add\_mline()* - • *add\_mpolygon()* - • *add\_multileader\_mtext()* - • *add\_multileader\_block()* - • *add\_point()* - • *add\_polyface()* - • *add\_polyline2d()* - • *add\_polyline3d()* - • *add\_polymesh()* - • *add\_ray()* - • *add\_shape()* - • *add\_solid()* - • *add\_trace()* - • *add\_wipeout()* - • *add\_xline()* ### Text Entities - • *add\_attdef()* - • *add\_mtext\_dynamic\_auto\_height\_columns()* - • *add\_mtext\_dynamic\_manual\_height\_columns()* - • *add\_mtext\_static\_columns()* - • *add\_mtext()* - • *add\_text()* ### Spline Entity - • *add\_cad\_spline\_control\_frame()* - • *add\_open\_spline()* - • *add\_rational\_spline()* - • *add\_spline\_control\_frame()* - • *add\_spline()* ### Block References and Underlays - • **add\_arrow\_blockref()** - • *add\_auto\_blockref()* - • *add\_blockref()* - • *add\_underlay()* ### Viewport Entity Only available in paper space layouts. - • **add\_viewport()** ### Dimension Entities Linear Dimension - • *add\_aligned\_dim()* - • *add\_linear\_dim()* - • *add\_multi\_point\_linear\_dim()* Radius and Diameter Dimension - • *add\_diameter\_dim\_2p()* - • *add\_diameter\_dim()* - • *add\_radius\_dim\_2p()* - • *add\_radius\_dim\_cra()* - • *add\_radius\_dim()* Angular Dimension - • *add\_angular\_dim\_2l()* - • *add\_angular\_dim\_3p()* - • *add\_angular\_dim\_arc()* - • *add\_angular\_dim\_cra()* Arc Dimension - • *add\_arc\_dim\_3p()* - • *add\_arc\_dim\_arc()* - • *add\_arc\_dim\_cra()* Ordinate Dimension - • *add\_ordinate\_dim()* - • *add\_ordinate\_x\_dim()* - • *add\_ordinate\_y\_dim()* ### Miscellaneous - • *add\_entity()* - • *add\_foreign\_entity()* - • **add\_arrow()** ### ACIS Entities The creation of the required *ACIS* data has do be done by an external library! - • *add\_3dsolid()* - • *add\_body()* - • *add\_extruded\_surface()* - • *add\_lofted\_surface()* - • *add\_region()* - • *add\_revolved\_surface()* - • *add\_surface()* - • *add\_swept\_surface()* **SEE ALSO:** Layout base class: *BaseLayout* ### Factory Functions Alternative way to create DXF entities for advanced *ezdxf* users. The **ezdxf.entities.factory** module provides the **new()** function to create new DXF entities by their DXF name and a dictionary of DXF attributes. This will bypass the validity checks in the factory methods of the *BaseLayout* class. This new created entities are virtual entities which are not assigned to any DXF document nor to any layout. Add the entity to a layout (and document) by the layout method *add\_entity()*. ``` import ezdxf from ezdxf.entities import factory doc = ezdxf.new() msp = doc.modelspace() line = factory.new( "LINE", dxfattribs={ "start": (0, 0, 0), "end": (3, 0, 0), "color": 2, }, ) msp.add_entity(line) ``` ### Direct Object Instantiation For advanced developers with knowledge about the internal design of *ezdxf*. Import the entity classes from sub-package *ezdxf.entities* and instantiate them. This will bypass the validity checks in the factory methods of the *BaseLayout* class and maybe additional required setup procedures for some entities - **study the source code!**. **WARNING:** A refactoring of the internal *ezdxf* structures will break your code. This new created entities are virtual entities which are not assigned to any DXF document nor to any layout. Add the entity to a layout (and document) by the layout method *add\_entity()*. ``` import ezdxf from ezdxf.entities import Line doc = ezdxf.new() msp = doc.modelspace() line = Line.new( dxfattribs={ "start": (0, 0, 0), "end": (3, 0, 0), "color": 2, } ) msp.add_entity(line) ``` ### Add Layouts and Blocks Layouts are containers for DXF entities like LINE or CIRCLE. There exist three layouts types: - • *Modelspace* - • *Paperspace* - • *Blocks* ### Modelspace The *Modelspace* is unique. It is not possible to create another one. ### Paperspace Layout All DXF versions can have multiple paperspace layouts expect DXF R12. Add a new paperspace layout to a DXF document: ``` doc.layouts.new("MyLayout") ``` The layout name is the name shown on the tab in CAD applications and has to be unique, otherwise a **DXFValueError** will be raised. It is possible to add multiple paperspace layouts to all DXF versions, but *ezdxf* exports for DXF R12 only the active paperspace layout. Any paperspace layout can be set as the active paperspace layout by the method: *ezdxf.layouts.Layouts.set\_active\_layout()*. - • *ezdxf.layouts.Layouts.new()* ### Block Definition Add a new block definition to a DXF document: ``` doc.blocks.new("MyLayout") ``` The block name has to be unique, otherwise a **DXFValueError** will be raised. Add an anonymous block definition: ``` my_block = doc.blocks.new_anonymous_block() # store the block name, so you can create block references to this block block_name = my_block.name ``` Anonymous blocks are used internally and do not show up in the insert dialog for block references in CAD applications. - • *ezdxf.sections.blocks.BlocksSection.new()* - • *ezdxf.sections.blocks.BlocksSection.new\_anonymous\_block()* **SEE ALSO:** **Tasks:** - • *Get Layouts and Blocks* - • *Delete Layouts and Blocks* - • *Add DXF Entities* - • *Copy or Move DXF Entities* - • *Delete DXF Entities* - • *Add Block References* **Tutorials:** - • *Tutorial for Getting Data from DXF Files* - • *Tutorial for Blocks* - • *Tutorial for Creating DXF Drawings* - • *Tutorial for Viewports in Paperspace* **Basics:** - • *Layout Types* - • *Modelspace* - • *Paperspace* - • *Blocks* **Classes:** - • *ezdxf.layouts.BaseLayout* - parent of all layouts - • *ezdxf.layouts.Layout* - parent of modelspace & paperspace - • *ezdxf.layouts.Modelspace* - • *ezdxf.layouts.Paperspace* - • *ezdxf.layouts.BlockLayout* - • *ezdxf.layouts.Layouts* - layout manager (**Drawing.layouts** attribute) - • *ezdxf.sections.blocks.BlocksSection* - blocks manager (**Drawing.blocks** attribute) ### Add Block References Blocks are collections of DXF entities which can be placed multiple times as block references in different layouts and other block definitions. A block reference is represented by the INSERT entity. ### Add Block Reference Add a block reference to the modelspace for a block definition “BlockName”: ``` my_block_ref = msp.add_blockref('BlockName', location, dxfattribs={ 'xscale': 1.0, 'yscale': 1.0, 'zscale': 1.0, 'rotation': angle, }) ``` Non-uniform scaling is supported by CAD applications. The rotations angle is in degrees (circle=360 degrees). - • *ezdxf.layouts.BaseLayout.add\_blockref()* ### Add Block Attribute To avoid confusion, it’s important to distinguish block attributes (ATTRIB entities) from DXF attributes. Block attributes are text annotations linked to a block reference. They have their own location and can be attached to any block reference, even without a corresponding attribute definition (ATTDEF) in the block layout. Add a block attribute to **my\_block\_ref**: ``` my_attribute = my_block_ref.add_attrib("MY_TAG", "VALUE_STR") my_attribute.set_placement(location) ``` - • “MY\_TAG”: a unique identifier or label for the attribute, unique in the context of the block reference - • “VALUE\_STR”: the text content displayed by the attribute Block attributes are a subtype of the TEXT entity. This means they inherit placement and editing functionalities from the TEXT class. - • *ezdxf.entities.Insert.add\_attrib()* - • *ezdxf.entities.Text.set\_placement()* ### Add Block Attribute from Template Block definitions can include pre-defined templates for attributes using ATTDEF entities. The *add\_auto\_attribs()* method simplifies adding these attributes to block references. It takes a dictionary argument where: - • Keys: the attribute tags (e.g. “MY\_TAG”). - • Values: the content for each attribute (e.g. “VALUE\_STR”). The **add\_auto\_attribs()** method automatically attaches attributes (ATTRIB entities) to the block reference. These attributes inherit relevant DXF properties (layer, color, text style, etc.) from the corresponding ATTDEF entities within the block definition. The method also ensures that the relative position of each attribute within the block reference mirrors the position of its corresponding ATTDEF entity relative to the block origin: ``` my_block_ref.add_auto_attrib({"MY_TAG": "VALUE_STR"}) ``` - • *ezdxf.entities.Insert.add\_auto\_attribs()* **SEE ALSO:** **Tasks:** - • *Add DXF Entities* - • *Copy or Move DXF Entities* - • *Delete DXF Entities* **Tutorials:** - • *Tutorial for Blocks* - • *Tutorial for Getting Data from DXF Files* - • *Tutorial for Creating DXF Drawings* **Basics:** - • *Modelspace* - • *Paperspace* - • *Blocks* **Classes:** - • *ezdxf.layouts.BlockLayout* - • *ezdxf.entities.BlockRecord* - • *ezdxf.entities.Block* - • *ezdxf.entities.Insert* - • *ezdxf.entities.Attrib* - • *ezdxf.entities.AttDef* - • *ezdxf.entities.Text* ### Add Resource Table Entries All resources require a unique name in their category (names are case-insensitive). ### Layer A layer in a DXF document is a category that controls visual properties (like color and linetype) for associated entities. It acts like a grouping tag, not a container. Add a new layer to a DXF document: ``` doc.layers.add("MY_NEW_LAYER", color=1, linetype="DASHED") ``` DXF entities reference layers, but layers themselves don’t directly contain entities. Instead, each entity has a **dxf.layer** attribute that specifies the layer by name it belongs to. - • *ezdxf.sections.table.LayerTable.add()* ### Linetype The linetype defines the rendering pattern of linear graphical entities like LINE, ARC, CIRCLE and so on. Add a new linetype to a DXF document: ``` doc.linetypes.add("DOTTED", pattern=[0.2, 0.0, -0.2]) ``` - • *ezdxf.sections.table.LinetypeTable.add()* ### Text Style The text style defines the rendering font for text based entities like TEXT, ATTRIB and MTEXT. Add a new text style to a DXF document: ``` doc.styles.add("ARIAL", font="arial.ttf") ``` - • *ezdxf.sections.table.TextstyleTable.add()* ### Dimension Style The dimension style defines the initial properties for the DIMENSION entity. Add a new dimension style to a DXF document: ``` doc.dimstyles.add("EZDXF") ``` - • *ezdxf.sections.table.DimStyleTable.add()* ### AppID The XDATA section of DXF entities is grouped by AppIDs and these ids require an entry in the **AppIDTable** otherwise the DXF file in invalid (for AutoCAD): ``` doc.appids.add("EZDXF") ``` - • *ezdxf.sections.table.AppIDTable.add()* **SEE ALSO:** **Tutorials:** - • *Tutorial for Layers* - • *Tutorial for Creating Linetype Pattern* - • *Tutorial for Text* - • *Tutorial for MText and MTextEditor* - • *Tutorial for Common Graphical Attributes* **Basics:** - • *Layers* - • *Linetypes* - • *Lineweights* - • *AutoCAD Color Index (ACI)* - • *True Color* - • *Font Resources* **Classes:** - • *ezdxf.entities.Layer* - • *ezdxf.entities.Linetype* - • *ezdxf.entities.Textstyle* - • *ezdxf.entities.DimStyle* - • **ezdxf.entities.Appid** - • *ezdxf.fonts.fonts* ### Add Custom and Extended Data DXF supports storing custom data through various mechanisms. ### Header Variables Custom data can be stored in the HEADER section of a DXF file. Integer values are stored in variables named $USERI1 to $USERI5, while floating-point values are stored in variables named $USERR1 to $USERR5. Example: ``` doc.header["$USERI1"] = 17 ``` ### XDATA Section The XDATA section is a container for extended data associated with an entity. It’s essentially a way to store additional information beyond the standard DXF properties for that particular entity. The XDATA section is divided into sub-sections, each associated with an AppID. It’s important that the AppID is registered in the AppID table: ``` doc.appids.add("YOUR_ID") ``` - • *ezdxf.sections.table.AppIDTable.add()* Example: ``` point = msp.add_point((10, 10)) point.set_xdata("YOUR_ID", (1040, 3.1415)) ``` - • *ezdxf.entities.DXFEntity.set\_xdata()* ### Extension Dictionaries Each DXF entity can have an extension dictionary to attach custom data. The extension dictionary is a *Dictionary* entity which stores references to other DXF entities in a key/value storage, mostly *Dictionary* and *XRecord* entities. Example: ``` point = msp.add_point((10, 10)) xdict = point.new_extension_dict() ``` - • *ezdxf.entities.DXFEntity.new\_extension\_dict()* ### Custom Data as XRECORD The XRECORD is used to store arbitrary data. It is composed of DXF group codes ranging from 1 through 369. This object is similar in concept to XDATA but is not limited by size or order. Example: ``` point = msp.add_point((10, 10)) xdict = point.new_extension_dict() xrecord = xdict.add_xrecord("MyData") xrecord.extend([(1, "MyText"), (40, 3.1415)]) ``` - • *ezdxf.entities.xdict.ExtensionDict.add\_xrecord()* - • *ezdxf.entities.xdict.ExtensionDict.add\_dictionary()* - • *ezdxf.entities.xdict.ExtensionDict.add\_dictionary\_var()* **SEE ALSO:** **Tasks:** - • *Get Extended Data from DXF Entities* - • *Modify Extended Data* - • *Delete Extended Data* **Tutorials:** - • *Storing Custom Data in DXF Files* **Basics:** - • *Extended Data* - • *Extension Dictionary* - • *DXF Tags* **Classes:** - • *ezdxf.entities.xdata.XData* - • *ezdxf.entities.xdict.ExtensionDict* - • *ezdxf.entities.XRecord* - • *ezdxf.entities.Dictionary* - • *ezdxf.entities.DictionaryVar* **Helper-Classes:** - • *ezdxf.entities.xdata.XDataUserList* - • *ezdxf.entities.xdata.XDataUserDict* - • *ezdxf.urecord.UserRecord* - • *ezdxf.urecord.BinaryRecord* ### Query Data ### Query Entities DXF entities can be selected from layouts or arbitrary entity-sequences based on their DXF type and attributes. Create new queries be the *new()* function or by the *query()* methods implemented by all layouts. **SEE ALSO:** - • Tutorial: *Tutorial for Getting Data from DXF Files* - • Reference: *ezdxf.query* module ### Entity Query String The query string is the combination of two queries, first the required entity query and second the optional attribute query, enclosed in square brackets, append **'i'** after the closing square bracket to ignore case for strings. ### Query Result The *EntityQuery* class is the return type of all **query()** methods. *EntityQuery* contains all DXF entities of the source collection, which matches one name of the entity query AND the whole attribute query. If a DXF entity does not have or support a required attribute, the corresponding attribute search term is **False**. Select all LINE and CIRCLE entities with layer == “construction”: ``` result = msp.query('LINE CIRCLE[layer=="construction"]') ``` This result is always empty, because the LINE entity has no text attribute: ``` result = msp.query('LINE[text ? ".*"]') ``` Select all entities except those with layer == “construction” and color \< 7: ``` result = msp.query('*[!(layer=="construction" & color<7)]') ``` Ignore case, selects all entities with layer == “construction”, “Construction”, “ConStruction” …: ``` result = msp.query('*[layer=="construction"]i') ``` ### Extended EntityQuery Features The *EntityQuery* container supports the full Sequence protocol: ``` result = msp.query(...) first = result[0] last = result[-1] ``` Slices return a new *EntityQuery* container: ``` sequence = result[1:-2] ``` The **\_\_getitem\_\_()** function accepts also a DXF attribute name and returns all entities which support this attribute, this is the base for supporting queries by relational operators. More on that later. The **\_\_setitem\_\_()** method assigns a DXF attribute to all supported entities in the *EntityQuery* container: ``` result = msp.query(...) result["layer"] = "MyLayer" ``` Entities which do not support an attribute are silently ignored: ``` result = msp.query(...) result["center"] = (0, 0) # set center only of CIRCLE and ARC entities ``` The **\_\_delitem\_\_()** method discards DXF attributes from all entities in the *EntityQuery* container: ``` result = msp.query(...) # reset the layer attribute from all entities in container result to the # default layer "0" del result["layer"] ``` ### Descriptors for DXF Attributes For some basic DXF attributes exist descriptors in the *EntityQuery* class: - • **layer**: layer name as string - • **color**: *AutoCAD Color Index (ACI)*, see *ezdxf.colors* - • **linetype**: linetype as string - • **ltscale**: linetype scaling factor as float value - • **lineweight**: *Lineweights* - • **invisible**: 0 if visible 1 if invisible, 0 is the default value - • **true\_color**: true color as int value, see *ezdxf.colors*, has no default value - • **transparency**: transparency as int value, see *ezdxf.colors*, has no default value A descriptor simplifies the attribute access through the *EntityQuery* container and has auto-completion support from IDEs: ``` result = msp.query(...) # set attribute of all entities in result result.layer = "MyLayer" # delete attribute from all entities in result del result.layer # and for selector usage, see following section assert len(result.layer == "MyLayer") == 1 ``` ### Relational Selection Operators The attribute selection by **\_\_getitem\_\_()** allows further selections by relational operators: ``` msp.add_line((0, 0), (1, 0), dxfattribs={"layer": "MyLayer}) lines = msp.query("LINE") # select all entities on layer "MyLayer" entities = lines["layer"] == "MyLayer" assert len(entities) == 1 # or select all entities except the entities on layer "MyLayer" entities = lines["layer"] != "MyLayer" ``` These operators work only with real DXF attributes, for instance the **rgb** attribute of graphical entities is not a real DXF attribute either the **vertices** of the LWPOLYLINE entity. The selection by relational operators is case insensitive by default, because all names of DXF table entries are handled case insensitive. But if required the selection mode can be set to case sensitive: ``` lines = msp.query("LINE") # use case sensitive selection: "MyLayer" != "MYLAYER" lines.ignore_case = False entities = lines["layer"] == "MYLAYER" assert len(entities) == 0 # the result container has the default setting: assert entities.ignore_case is True ``` Supported selection operators are: - • **==** equal “value” - • **!=** not equal “value” - • **\<** lower than “value” - • **\<=** lower or equal than “value” - • **\>** greater than “value” - • **\>=** greater or equal than “value” The relational operators \<, \>, \<= and \>= are not supported for vector-based attributes such as *center* or *insert* and raise a **TypeError**. **NOTE:** These operators are selection operators and not logic operators, therefore the logic operators **and**, **or** and **not** are **not** applicable. The methods *union()*, *intersection()*, *difference()* and *symmetric\_difference()* can be used to combine selection. See section *Query Set Operators* and *Build Custom Filters*. ### Regular Expression Selection The *EntityQuery.match()* method returns all entities where the selected DXF attribute matches the given regular expression. This methods work only on string based attributes, raises **TypeError** otherwise. From here on I use only descriptors for attribute selection if possible. ``` msp.add_line((0, 0), (1, 0), dxfattribs={"layer": "Lay1"}) msp.add_line((0, 0), (1, 0), dxfattribs={"layer": "Lay2"}) lines = msp.query("LINE") # select all entities at layers starting with "Lay", # selection is also case insensitive by default: assert len(lines.layer.match("^Lay.*")) == 2 ``` ### Build Custom Filters The method *EntityQuery.filter* can be used to build operators for none-DXF attributes or for complex logic expressions. Find all MTEXT entities in modelspace containing “SearchText”. All *MText* entities have a **text** attribute, no need for a safety check: ``` mtext = msp.query("MTEXT").filter(lambda e: "SearchText" in e.text) ``` This filter checks the non-DXF attribute **rgb**. The filter has to check if the **rgb** attributes exist to avoid exceptions, because not all entities in modelspace may have the **rgb** attribute e.g. the **DXFTagStorage** entities which preserve unknown DXF entities: ``` result = msp.query().filter( lambda e: hasattr(e, "rgb") and e.rgb == (0, 0, 0) ) ``` Build 1-pass logic filters for complex queries, which would require otherwise multiple passes: ``` result = msp.query().filter(lambda e: e.dxf.color < 7 and e.dxf.layer == "0") ``` Combine filters for more complex operations. The first filter passes only valid entities and the second filter does the actual check: ``` def validator(entity): return True # if entity is valid and has all required attributes def check(entity): return True # if entity passes the attribute checks result = msp.query().filter(validator).filter(check) ``` ### Query Set Operators The **\|** operator or *EntityQuery.union()* returns a new *EntityQuery* with all entities from both queries. All entities are unique - no duplicates. This operator acts like the logical **or** operator. ``` entities = msp.query() # select all entities with color < 2 or color > 7 result = (entities.color < 2 ) | (entities.color > 7) ``` The **&** operator or *EntityQuery.intersection()* returns a new *EntityQuery* with entities common to *self* and *other*. This operator acts like the logical **and** operator. ``` entities = msp.query() # select all entities with color > 1 and color < 7 result = (entities.color > 1) & (entities.color < 7) ``` The **-** operator or *EntityQuery.difference()* returns a new *EntityQuery* with all entities from *self* that are not in *other*. ``` entities = msp.query() # select all entities with color > 1 and not layer == "MyLayer" result = (entities.color > 1) - (entities.layer != "MyLayer") ``` The **^** operator or *EntityQuery.symmetric\_difference()* returns a new *EntityQuery* with entities in either *self* or *other* but not both. ``` entities = msp.query() # select all entities with color > 1 or layer == "MyLayer", exclusive # entities with color > 1 and layer == "MyLayer" result = (entities.color > 1) ^ (entities.layer == "MyLayer") ``` ### Groupby Function **SEE ALSO:** Tutorial: *Retrieve entities by groupby() function* - **ezdxf.groupby.groupby(entities: Iterable\[*DXFEntity*\], dxfattrib: str = '', key: KeyFunc \| None = None) -\> dict\[Hashable, list\[*DXFEntity*\]\]** Groups a sequence of DXF entities by a DXF attribute like **'layer'**, returns a dict with *dxfattrib* values as key and a list of entities matching this *dxfattrib*. A *key* function can be used to combine some DXF attributes (e.g. layer and color) and should return a hashable data type like a tuple of strings, integers or floats, *key* function example: ``` def group_key(entity: DXFEntity): return entity.dxf.layer, entity.dxf.color ``` For not suitable DXF entities return **None** to exclude this entity, in this case it’s not required, because *groupby()* catches **DXFAttributeError** exceptions to exclude entities, which do not provide layer and/or color attributes, automatically. Result dict for *dxfattrib* = **'layer'** may look like this: ``` { '0': [ ... list of entities ], 'ExampleLayer1': [ ... ], 'ExampleLayer2': [ ... ], ... } ``` Result dict for *key* = *group\_key*, which returns a **(layer, color)** tuple, may look like this: ``` { ('0', 1): [ ... list of entities ], ('0', 3): [ ... ], ('0', 7): [ ... ], ('ExampleLayer1', 1): [ ... ], ('ExampleLayer1', 2): [ ... ], ('ExampleLayer1', 5): [ ... ], ('ExampleLayer2', 7): [ ... ], ... } ``` All entity containers (modelspace, paperspace layouts and blocks) and the *EntityQuery* object have a dedicated *groupby()* method. - **Parameters** - • **entities** – sequence of DXF entities to group by a DXF attribute or a *key* function - • **dxfattrib** – grouping DXF attribute like **'layer'** - • **key** – key function, which accepts a **DXFEntity** as argument and returns a hashable grouping key or **None** to ignore this entity ### Selection Tools The *ezdxf.select* module provides entity selection capabilities, allowing users to select entities based on various shapes such as windows, points, circles, polygons, and fences. The selection functions *bbox\_inside()* and *bbox\_outside()* work similarly to the inside and outside selection tools in CAD applications but the selection is based on the bounding box of the DXF entities rather than their actual geometry. The *bbox\_overlap()* function works similarly to crossing selection in CAD applications. Entities that are outside the selection shape but whose bounding box overlapps the selection shape are included in the selection. This is not the case with crossing selection in CAD applications. The selection functions accept any iterable of DXF entities as input and return an *ezdxf.query.EntityQuery* container, that provides further selection tools based on entity type and DXF attributes. ### Usage Select all entities from the modelspace inside a window defined by two opposite vertices: ``` import ezdxf from ezdxf import select doc = ezdxf.readfile("your.dxf") msp = doc.modelspace() # Define a window for selection window = select.Window((0, 0), (10, 10)) # Select entities inside the window from modelspace selected_entities = select.bbox_inside(window, msp) # Iterate over selected entities for entity in selected_entities: print(entity) ``` **SEE ALSO:** - • *Tutorial for Entity Selection* ### Selection Functions The following selection functions are implemented: - • *bbox\_inside()* - • *bbox\_outside()* - • *bbox\_overlap()* - • *bbox\_chained()* - • *bbox\_crosses\_fence()* - • *point\_in\_bbox()* - **ezdxf.select.bbox\_inside(shape: SelectionShape, entities: Iterable\[DXFEntity\], \*, cache: *Cache* \| None = None) -\> *EntityQuery*** Selects entities whose bounding box lies withing the selection shape. - **Parameters** - • **shape** – seclection shape - • **entities** – iterable of DXFEntities - • **cache** – optional *ezdxf.bbox.Cache* instance - **ezdxf.select.bbox\_outside(shape: SelectionShape, entities: Iterable\[DXFEntity\], \*, cache: *Cache* \| None = None) -\> *EntityQuery*** Selects entities whose bounding box is completely outside the selection shape. - **Parameters** - • **shape** – seclection shape - • **entities** – iterable of DXFEntities - • **cache** – optional *ezdxf.bbox.Cache* instance - **ezdxf.select.bbox\_overlap(shape: SelectionShape, entities: Iterable\[DXFEntity\], \*, cache: *Cache* \| None = None) -\> *EntityQuery*** Selects entities whose bounding box overlaps the selection shape. - **Parameters** - • **shape** – seclection shape - • **entities** – iterable of DXFEntities - • **cache** – optional *ezdxf.bbox.Cache* instance - **ezdxf.select.bbox\_chained(start: DXFEntity, entities: Iterable\[DXFEntity\], \*, cache: *Cache* \| None = None) -\> *EntityQuery*** Selects elements that are directly or indirectly connected to each other by overlapping bounding boxes. The selection begins at the specified starting element. Warning: the current implementation has a complexity of O(n²). - **Parameters** - • **start** – first entity of selection - • **entities** – iterable of DXFEntities - • **cache** – optional *ezdxf.bbox.Cache* instance - **ezdxf.select.bbox\_crosses\_fence(vertices: Iterable\[*UVec*\], entities: Iterable\[DXFEntity\], \*, cache: *Cache* \| None = None) -\> *EntityQuery*** Selects entities whose bounding box intersects an open polyline. All entities are projected on the xy-plane. A single point can not be selected by a fence polyline by definition. - **Parameters** - • **vertices** – vertices of the selection polyline - • **entities** – iterable of DXFEntities - • **cache** – optional *ezdxf.bbox.Cache* instance - **ezdxf.select.point\_in\_bbox(location: *UVec*, entities: Iterable\[DXFEntity\], \*, cache: *Cache* \| None = None) -\> *EntityQuery*** Selects entities where the selection point lies within the bounding box. All entities are projected on the xy-plane. - **Parameters** - • **point** – selection point - • **entities** – iterable of DXFEntities - • **cache** – optional *ezdxf.bbox.Cache* instance ### Selection Shapes The following selection shapes are implemented: - • *Window* - • *Circle* - • *Polygon* - **class ezdxf.select.Window(p1: *UVec*, p2: *UVec*)** This selection shape tests entities against a rectangular and axis-aligned 2D window. All entities are projected on the xy-plane. - **Parameters** - • **p1** – first corner of the window - • **p2** – second corner of the window - **class ezdxf.select.Circle(center: *UVec*, radius: float)** This selection shape tests entities against a circle. All entities are projected on the xy-plane. - **Parameters** - • **center** – center of the circle - • **radius** – radius of the circle - **class ezdxf.select.Polygon(vertices: Iterable\[*UVec*\])** This selection shape tests entities against an arbitrary closed polygon. All entities are projected on the xy-plane. Complex **concave** polygons may not work as expected. ### Planar Search Index Added in version 1.4. - **class ezdxf.select.PlanarSearchIndex(entities: Iterable\[DXFEntity\], cache: *Cache* \| None = None, max\_node\_size=5)** **Spatial Search Index for DXF Entities** This class implements a spatial search index for DXF entities based on their bounding boxes except for POINT and LINE. It operates strictly within the two-dimensional (2D) space of the xy-plane. The index is built once and cannot be extended afterward. The index can be used to pre-select DXF entities from a certain area to reduce the search space for other selection tools of this module. **Functionality** - • The index relies on the bounding boxes of DXF entities, and only the corner vertices of these bounding boxes are indexed except for POINT and LINE. - • It can only find DXF entities that have at least one bounding box vertex located within the search area. Entities whose bounding boxes overlap the search area but have no vertices inside it will not be found (e.g., a circle whose center point is inside the search area but none of its bounding box vertices will not be included). - • The detection behavior can be customized by overriding the *detection\_points()* method. **Recommendations** Since this index is intended to be used in conjunction with other selection tools within this module, it’s recommended to maintain a bounding box cache to avoid the computational cost of recalculating them frequently. This class creates a new bounding box cache if none is specified. This cache can be accessed through the public attribute **cache**. - **detection\_point\_in\_circle(center: *UVec*, radius: float) -\> Sequence\[DXFEntity\]** Returns all DXF entities that have at least one detection point located around *center* with a max. distance of *radius*. - **detection\_point\_in\_rect(p1: *UVec*, p2: *UVec*) -\> Sequence\[DXFEntity\]** Returns all DXF entities that have at least one detection point located inside or at the border of the rectangle defined by the two given corner points. - **detection\_points(entity: DXFEntity) -\> Sequence\[*Vec2*\]** Returns the detection points for a given DXF entity. The detection points must be 2D points projected onto the xy-plane (ignore z-axis). This implementation returns the corner vertices of the entity bounding box. Override this method to return more sophisticated detection points (e.g., the vertices of LWPOLYLINE and POLYLINE or equally spaced raster points for block references). ### Get DXF Entity Type The *dxftype()* method returns the entity type as defined by the DXF reference as an uppercase string. ``` e = msp.add_line((0, 0), (1, 0)) assert e.dxftype() == "LINE" ``` **SEE ALSO:** - • *DXF Reference* for DXF R2018 ### Get DXF Attributes From Entities 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 ``` The **dxf** namespace attribute has a **get()** method, which can return a default value if the attribute doesn’t exist: ``` e.dxf.get('color', 9) ``` The attribute has to be supported by the DXF type otherwise a **DXFAttributeError** will be raised. You can check if an DXF attribute is supported by the method **dxf.is\_supported()**: ``` line = msp.add_line((0, 0), (1, 0)) assert line.dxf.is_supported("text") is False ``` ### Optional DXF Attributs Many DXF attributes are optional, you can check if an attribute exists by the **hasattrib()** method: ``` assert line.dxf.hasattrib("linetype") is False ``` ### Default Values Some DXF attributes have default values and this default value will be returned if the DXF attribute doesn’t exist: ``` assert line.dxf.linetype == "BYLAYER" ``` **SEE ALSO:** **Tasks:** - • *Common graphical DXF attributes* - • *Modify DXF Attributes of Entities* - • *Delete DXF Attributes from Entities* **Tutorials:** - • *Tutorial for Common Graphical Attributes* - • *Tutorial for Getting Data from DXF Files* ### Get Content From DXF Entities ### TEXT Entity The content of the TEXT entity is stored in a single DXF attribute **Text.dxf.text** and has an empty string as default value: ``` for text in msp.query("TEXT"): print(text.dxf.text) ``` The *plain\_text()* method returns the content of the TEXT entity without formatting codes. **SEE ALSO:** **Classes** - • *ezdxf.entities.Text* **Tutorials** - • *Tutorial for Text* ### MTEXT Entity The content of the MTEXT entity is stored in multiple DXF attributes. The content can be accessed by the read/write property *text* and the DXF attribute **MText.dxf.text** and has an empty string as default value: ``` for mtext in msp.query("MTEXT"): print(mtext.text) # is the same as: print(mtext.dxf.text) ``` **IMPORTANT:** The line ending character **\\n** will be replaced automatically by the MTEXT line ending **\\P**. The *plain\_text()* method returns the content of the MTEXT entity without inline formatting codes. **SEE ALSO:** **Classes** - • *ezdxf.entities.MText* - • *ezdxf.tools.text.MTextEditor* **Tutorials** - • *Tutorial for MText and MTextEditor* ### MLEADER Entity The content of MLEADER entities is stored in the **MultiLeader.context** object. The MLEADER contains text content if the **context.mtext** attribute is not **None** and block content if the **context.block** attribute is not **None** **SEE ALSO:** **Classes** - • *ezdxf.entities.MultiLeader* - • *ezdxf.entities.MLeaderContext* - • *ezdxf.entities.MTextData* - • *ezdxf.entities.BlockData* - • *ezdxf.entities.AttribData* **Tutorials** - • *Tutorial for MultiLeader* ### Text Content ``` for mleader in msp.query("MLEADER MULTILEADER"): mtext = mleader.context.mtext if mtext: print(mtext.insert) # insert location print(mtext.default_content) # text content ``` The text content supports the same formatting features as the MTEXT entity. ### Block Content The INSERT (block reference) attributes are stored in **MultiLeader.context.block** as *BlockData*. ``` for mleader in msp.query("MLEADER MULTILEADER"): block = mleader.context.block if block: print(block.insert) # insert location ``` The ATTRIB attributes are stored outside the context object in **MultiLeader.block\_attribs** as *AttribData*. ``` for mleader in msp.query("MLEADER MULTILEADER"): for attrib in mleader.block_attribs: print(attrib.text) # text content of the ATTRIB entity ``` ### DIMENSION Entity Get real measurement determined by definition points: ``` for dimension in msp.query("DIMENSION"): print(str(dimension)) print(f"Dimension Type: {dimension.dimtype}") print(f"Measurement: {dimension.get_measurement()}") ``` | | | | | --- | --- | --- | | Type | Dimension Type | Measurement | | 0 | Linear and Rotated Dimension | length in drawing units | | 1 | Aligned Dimension | length in drawing units | | 2 | Angular Dimension | angle in degree | | 3 | Diameter Dimension | length in drawing units | | 4 | Radius Dimension | length in drawing units | | 5 | Angular 3P Dimension | angle in degree | | 6 | Ordinate Dimension | feature location as *Vec3* | Get measurement text. This is how the measurement text was rendered into the associated geometry block by the CAD application as the DIMENSION entity was created: ``` for dimension in msp.query("DIMENSION"): print(str(dimension)) print(f"Measurement Text: {dimension.dxf.text}") ``` | | | | --- | --- | | Text | Measurement text rendered by CAD application | | **"\<\>"** | actual measurement | | **""** | (empty string) actual measurement | | **" "** | (space) measurement text is suppressed | | other | measurement text entered by the CAD user | Get measurement text from text entities in the associated geometry block. This is the actual measurement text displayed by CAD applications: ``` for dimension in msp.query("DIMENSION"): print(str(dimension)) block = dimension.get_geometry_block() if block is None: print("Geometry block not found.") continue for entity in block.query("TEXT MTEXT"): print(f"{str(entity)}: {entity.dxf.text}") ``` **SEE ALSO:** **Tutorials:** - • *Tutorial for Linear Dimensions* **Classes:** - • *ezdxf.entities.Dimension* ### ACAD\_TABLE Entity The helper function **read\_acad\_table\_content()** returns the content of an ACAD\_TABLE entity as list of table rows. If the count of table rows or table columns is missing the complete content is stored in the first row. All cells contain strings. ``` from ezdxf.entities.acad_table import read_acad_table_content ... for acad_table in msp.query("ACAD_TABLE"): content = read_acad_table_content(acad_table) for n, row in enumerate(content): for m, value in enumerate(row): print(f"cell [{n}, {m}] = '{value}'") ``` **IMPORTANT:** The ACAD\_TABLE entity has only limited support to preserve the entity. There is no support for adding a new ACAD\_TABLE entity or modifying it’s content. ### INSERT Entity - Block References ### Get Block Attributes Get a block attribute by tag: ``` diameter = insert.get_attrib('diameter') if diameter is not None: print(f"diameter = {diameter.dxf.text}") ``` Iterate over all block attributes: ``` for attrib in insert.attribs: print(f"{attrib.dxf.tag} = {attrib.dxf.text}") ``` **IMPORTANT:** Do not confuse block attributes and DXF entity attributes, these are different concepts! ### Get Block Entities Get block entities as virtual DXF entities from an *Insert* entity: ``` for insert in msp.query("INSERT"): for entity in insert.virtual_entities(): print(str(entity)) ``` ### Get Transformation Matrix ``` m = insert.matrix44() ``` This transformation matrix transforms the virtual block entities from the block reference coordinate system into the *WCS*. **SEE ALSO:** **Tasks:** - • *Add Block References* - • *Explode Block References* **Tutorials:** - • *Tutorial for Blocks* **Basics:** - • *Blocks* **Classes:** - • *ezdxf.entities.Insert* - • *ezdxf.entities.Attrib* - • *ezdxf.entities.AttDef* - • *ezdxf.math.Matrix44* ### Get Extended Data from DXF Entities ### HEADER Variables ``` i1 = doc.header["$USERI1"] # integer r1 = doc.header["$USERR1"] # float ``` ### XDATA Section The structure of XDATA is arbitrary and only some structures used by AutoCAD are documented in the DXF reference. Use the *Browse* command to explore these structures directly in DXF files. ``` my_app_id = "MY_APP_1" if line.has_xdata(my_app_id): tags = line.get_xdata(my_app_id) print(f"{str(line)} has {len(tags)} tags of XDATA for AppID {my_app_id!r}") for tag in tags: print(tag) ``` - • *ezdxf.entities.DXFEntity.get\_xdata()* ### Extension Dictionaries Like XDATA the structure of extension dictionaries is arbitrary and not documented by the DXF reference. ``` for line in msp.query("LINE"): if line.has_extension_dict: # get the extension dictionary xdict = line.get_extension_dict() ``` - • *ezdxf.entities.DXFEntity.get\_extension\_dict()* **SEE ALSO:** **Tasks:** - • *Add Custom and Extended Data* - • *Modify Extended Data* - • *Delete Extended Data* **Tutorials:** - • *Storing Custom Data in DXF Files* **Basics:** - • *Extended Data* - • *Extension Dictionary* - • *DXF Tags* **Classes:** - • *ezdxf.entities.xdata.XData* - • *ezdxf.entities.xdict.ExtensionDict* - • *ezdxf.entities.XRecord* - • *ezdxf.entities.Dictionary* - • *ezdxf.entities.DictionaryVar* **Helper-Classes:** - • *ezdxf.entities.xdata.XDataUserList* - • *ezdxf.entities.xdata.XDataUserDict* - • *ezdxf.urecord.UserRecord* - • *ezdxf.urecord.BinaryRecord* ### Get Layouts and Blocks Layouts and blocks contain all the graphical entities likes LINE, CIRCLE and so on. Get all paperspace and modelspace layout names in arbitrary order: ``` layout_names = doc.layout_names() ``` Get all paperspace and modelspace layout names in tab-order of CAD applications: ``` layout_names = doc.layout_names_in_taborder() ``` ### Modelspace Each DXF document has one and only one *Modelspace* layout. The *modelspace()* method of the *Drawing* class returns the *Modelspace* object. ``` msp = doc.modelspace() ``` ### Paperspace Layouts Each DXF document has one or more *Paperspace* layout. DXF R12 supports only one paperspace layout. Get the active (default) paperspace layout: ``` psp = doc.paperspace() ``` Get a paperspace layout by name: ``` psp = doc.paperspace("Layout0") ``` The *name* argument is the name shown in the tabs of CAD applications. ### Block Layouts *Blocks* are collections of DXF entities which can be placed multiple times as block references in different layouts and other block definitions. Iterate over all block definitions: ``` for block in doc.blocks: print(block.name) ``` Get block definition by name: ``` block = doc.blocks.get("MyBlock") if block is None: print("block not found.") ``` Count block references: ``` from ezdxf import blkrefs ... counter = blkrefs.BlockReferenceCounter(doc) count = counter.by_name("MyBlock") print(f"MyBlock is referenced {count} times." ``` Find unused (unreferenced) block definitions: Added in version 1.3.5. ``` from ezdxf import blkrefs ... for name in blkrefs.find_unreferenced_blocks(doc) block = doc.blocks.get(name) ``` **SEE ALSO:** **Tasks:** - • *Add Layouts and Blocks* - • *Delete Layouts and Blocks* - • *Add Block References* - • *Delete DXF Entities* **Tutorials:** - • *Tutorial for Blocks* **Basics:** - • *Layout Types* - • *Modelspace* - • *Paperspace* - • *Blocks* **Classes:** - • *ezdxf.layouts.Modelspace* - • *ezdxf.layouts.Paperspace* - • *ezdxf.layouts.BlockLayout* - • *ezdxf.sections.blocks.BlocksSection* - • *ezdxf.document.Drawing* **Modules:** - • *ezdxf.blkrefs* ### Modify Data ### Modify DXF Attributes of Entities All DXF attributes of an entity are grouped in the namespace attribute **dxf**. You can modify/set a DXF attribute by assignment: ``` e.dxf.layer = "MyLayer" e.dxf.color = 9 ``` … or by the **set()** method: ``` e.dxf.set('color', 9) ``` The attribute has to be supported by the DXF type otherwise a **DXFAttributeError** will be raised. You can check if an DXF attribute is supported by the method **dxf.is\_supported()**: ``` line = msp.add_line((0, 0), (1, 0)) assert line.dxf.is_supported("text") is False ``` **SEE ALSO:** **Tasks** - • *Common graphical DXF attributes* - • *Get DXF Attributes From Entities* - • *Delete DXF Attributes from Entities* **Tutorials:** - • *Tutorial for Common Graphical Attributes* ### Modify Resource Table Entries TODO ### Layer TODO ### Linetype TODO ### Text Style TODO ### Dimension Style TODO ### Modify Geometry of DXF Entities TODO ### LINE TODO ### CIRCLE TODO ### ARC TODO ### ELLIPSE TODO ### SPLINE TODO ### LWPOLYLINE TODO ### POLYLINE TODO ### MESH TODO ### HATCH TODO ### DIMENSION Delete the existing DIMENSION and create a new one. ### MLEADER Delete the existing MLEADER and create a new one. ### ACAD\_TABLE Not supported. ### Transform Entities and Layouts TODO ### Transform DXF Entities TODO ### Transform Layouts TODO ### Copy or Move DXF Entities TODO ### Duplicate DXF Entities TODO ### Move DXF Entities between Layouts TODO ### Modify Block References TODO ### Modify Block attributes TODO ### Clip Block References TODO ### Modify Entity Content TODO ### TEXT Entity TODO ### MTEXT Entity TODO ### DIMENSION Entity Delete the existing DIMENSION and create a new one. ### MLEADER Entity Delete the existing MLEADER and create a new one. ### ACAD\_TABLE Entity Not supported. ### Modify Header Variables TODO ### Modify Extended Data TODO **SEE ALSO:** **Tasks:** - • *Add Custom and Extended Data* - • *Get Extended Data from DXF Entities* - • *Delete Extended Data* **Tutorials:** - • *Storing Custom Data in DXF Files* **Basics:** - • *Extended Data* - • *Extension Dictionary* - • *DXF Tags* **Classes:** - • *ezdxf.entities.xdata.XData* - • *ezdxf.entities.xdict.ExtensionDict* - • *ezdxf.entities.XRecord* - • *ezdxf.entities.Dictionary* - • *ezdxf.entities.DictionaryVar* **Helper-Classes:** - • *ezdxf.entities.xdata.XDataUserList* - • *ezdxf.entities.xdata.XDataUserDict* - • *ezdxf.urecord.UserRecord* - • *ezdxf.urecord.BinaryRecord* ### Delete Data ### Delete DXF Attributes from Entities All DXF attributes of an entity are grouped in the namespace attribute **dxf**. You can delete a DXF attribute by the *del* operator: ``` line = msp.add_line((0, 0), (1, 0)) line.dxf.layer = "MyLayer" del line.dxf.layer assert line.dxf.layer == "0" # the default layer for all entities ``` The *del* operator raises an **DXFAttributeError** if the attribute doesn’t exist or isn’t supported. The **discard()** method ignores these errors: ``` line.dxf.discard('text') # doesn't raise an exception ``` **SEE ALSO:** **Tasks** - • *Common graphical DXF attributes* - • *Get DXF Attributes From Entities* - • *Modify DXF Attributes of Entities* **Tutorials:** - • *Tutorial for Common Graphical Attributes* ### Delete DXF Entities TODO ### Delete Entities from Layouts TODO ### Delete Block Reference Attributes TODO ### Delete Resource Table Entries TODO ### Layer TODO ### Linetype TODO ### Text Style TODO ### Dimension Style TODO ### Delete Layouts and Blocks ### Modelspace This is not possible. ### Paperspace Layouts Delete a paperspace layout and it’s entities. ``` name = "MyLayout" try: doc.layouts.delete(name) except ezdxf.DXFKeyError: print(f"layout '{name}' not found") except ezdxf.DXFValueError: print(f"layout '{name}' cannot be deleted") # modelspace or last remaining paperspace layout ``` ### Block Definitions Delete a block definition: ``` try: doc.blocks.delete_block(name, safe=True) except ezdxf.DXFBlockInUseError: print(f"cannot delete block '{name}'") ``` Raises a **DXFBlockInUseError** exception if the block is referenced by an INSERT entity or if it is an anonymous/special block. Purge/delete unused (unreferenced) block definitions: Added in version 1.3.5. ``` from ezdxf import blkrefs ... for name in blkrefs.find_unreferenced_blocks(doc) doc.blocks.delete_block(name, safe=False) ``` **SEE ALSO:** **Tasks:** - • *Add Layouts and Blocks* - • *Get Layouts and Blocks* - • *Add Block References* - • *Delete DXF Entities* **Tutorials:** - • *Tutorial for Blocks* **Basics:** - • *Layout Types* - • *Modelspace* - • *Paperspace* - • *Blocks* **Classes:** - • *ezdxf.layouts.Layouts* - • *ezdxf.document.Drawing* **Modules:** - • *ezdxf.blkrefs* ### Delete Extended Data TODO **SEE ALSO:** **Tasks:** - • *Add Custom and Extended Data* - • *Get Extended Data from DXF Entities* - • *Modify Extended Data* **Tutorials:** - • *Storing Custom Data in DXF Files* **Basics:** - • *Extended Data* - • *Extension Dictionary* - • *DXF Tags* **Classes:** - • *ezdxf.entities.xdata.XData* - • *ezdxf.entities.xdict.ExtensionDict* - • *ezdxf.entities.XRecord* - • *ezdxf.entities.Dictionary* - • *ezdxf.entities.DictionaryVar* **Helper-Classes:** - • *ezdxf.entities.xdata.XDataUserList* - • *ezdxf.entities.xdata.XDataUserDict* - • *ezdxf.urecord.UserRecord* - • *ezdxf.urecord.BinaryRecord* ### Explode Entities ### Explode DXF Entities TODO ### POINT TODO ### POLYLINE & LWPOLYLINE TODO ### MESH TODO ### INSERT (Block References) *Explode Block References* ### DIMENSION TODO ### MLEADER TODO ### MLINE TODO ### ACAD\_TABLE TODO ### Proxy Graphic TODO ### Explode Block References TODO ### Flatten DXF Entities TODO ## EXTERNAL REFERENCES (XREF) Added in version 1.1. Attached XREFs are links to the modelspace of a specified drawing file. Changes made to the referenced drawing are automatically reflected in the current drawing when it’s opened or if the XREF is reloaded. XREFs can be nested within other XREFs: that is, you can attach an XREF that contains another XREF. You can attach as many copies of an XREF as you want, and each copy can have a different position, scale, and rotation. You can also overlay an XREF on your drawing. Unlike an attached XREF, an overlaid XREF is not included when the drawing is itself attached or overlaid as an XREF to another drawing. ### DXF Files as Attached XREFs **IMPORTANT:** AutoCAD can only display DWG files as attached XREFs but *ezdxf* can only create DXF files. Consequently, any DXF file attached as an XREF to a DXF document must be converted to DWG in order to be viewed in AutoCAD. Fortunately, other CAD applications are more cooperative, BricsCAD has no problem displaying DXF files as XREFs, although it is not possible to attach a DXF file as an XREF in the BricsCAD application itself. The *ezdxf.xref* module provides an interface for working with XREFs. - • *attach()* - attach a DXF/DWG file as XREF - • *detach()* - detach a BLOCK definition as XREF - • *embed()* - embed an XREF as a BLOCK definition - • *dxf\_info()* - scans a DXF file for basic settings and properties For loading the content of DWG files is a loading function required, which loads the DWG file as **Drawing** document. The *odafc* add-on module provides such a function: *readfile()* **SEE ALSO:** - • *Tutorial for External References* ### XREF Structures An XREF is a normal block definition located in the BLOCKS section with special flags set and a filename to the referenced DXF/DWG file and without any content, the block content is the modelspace of the referenced file. An XREF can be referenced (inserted) by one or multiple INSERT entities. Find block definitions in the BLOCKS section: ``` for block_layout in doc.blocks: block = block_layout.block # the BLOCK entity if block.is_xref: handle_xref(block_layout) elif block.is_xref_overlay: handle_xref_overlay(block_layout) ``` Find XREF references in modelspace: ``` for insert in msp.query("INSERT"): if insert.is_xref: handle_xref_reference(insert) # ... or get the XREF definition block_layout = insert.block() if block_layout is not None: handle_xref_definition(block_layout) ``` Use the helper function *define()* to create your own XREF definition, the *attach()* creates this definition automatically and raises an exception if the block already exists. ### Supported Entities The current implementation supports only copyable and transformable DXF entities, these are all basic entity types as LINE, CIRCLE, … and block references and their associated required table entries and objects from the OBJECTS section. Unsupported is the ACAD\_TABLE entity and preserved unknown entities wrapped in a **DXFTagStorage** class like proxy entities and objects. Support for these entities may be added in a later version of *ezdxf*. Unsupported entities are ignored and do not raise exceptions. Most document features stored in the HEADER and OBJECTS sections are not supported by this module like GROUPS, LAYER\_FILTER, GEODATA, SUN. Added in version 1.3.0: Support for ACIS based entities was added. ### Importing Data and Resources The *ezdxf.xref* module replaces the *Importer* add-on. The basic functionality of the *ezdxf.xref* module is loading data from external files including their required resources, which is an often requested feature by users for importing data from other DXF files into the current document. The **Importer** add-on was very limited and removed many resources, where the *ezdxf.xref* module tries to preserve as much information as possible. - • *load\_modelspace()* - loads the modelspace content from another DXF document - • *load\_paperspace()* - loads a paperspace layout from another DXF document - • *write\_block()* - writes entities into the modelspace of a new DXF document - • *Loader* - low level loading interface ### High Level Functions - **ezdxf.xref.attach(doc: *Drawing*, \*, block\_name: str, filename: str, insert: *UVec* = (0, 0, 0), scale: float = 1.0, rotation: float = 0.0, overlay=False) -\> Insert** Attach the file *filename* to the host document as external reference (XREF) and creates a default block reference for the XREF in the modelspace of the document. The function raises an **XrefDefinitionError** exception if the block definition already exist, but an XREF can be inserted multiple times by adding additional block references: ``` msp.add_blockref(block_name, insert=another_location) ``` **IMPORTANT:** If the XREF has different drawing units than the host document, the scale factor between these units must be applied as a uniform scale factor to the block reference! Unfortunately the XREF drawing units can only be detected by scanning the HEADER section of a document by the function *dxf\_info()* and is therefore not done automatically by this function. Advice: always use the same units for all drawings of a project! - **Parameters** - • **doc** – host DXF document - • **block\_name** – name of the XREF definition block - • **filename** – file name of the XREF - • **insert** – location of the default block reference - • **scale** – uniform scaling factor - • **rotation** – rotation angle in degrees - • **overlay** – creates an XREF overlay if **True** and an XREF attachment otherwise - **Returns** default block reference for the XREF - **Return type** *Insert* - **Raises** **XrefDefinitionError** – block with same name exist Added in version 1.1. - **ezdxf.xref.define(doc: *Drawing*, block\_name: str, filename: str, overlay=False) -\> None** Add an external reference (xref) definition to a document. XREF attachment types: - • attached: the XREF that’s inserted into this drawing is also present in a document to which this document is inserted as an XREF. - • overlay: the XREF that’s inserted into this document is **not** present in a document to which this document is inserted as an XREF. - **Parameters** - • **doc** – host document - • **block\_name** – name of the xref block - • **filename** – external reference filename - • **overlay** – creates an XREF overlay if **True** and an XREF attachment otherwise - **Raises** **XrefDefinitionError** – block with same name exist Added in version 1.1. - **ezdxf.xref.detach(block: BlockLayout, \*, xref\_filename: str \| PathLike, overlay=False) -\> *Drawing*** Write the content of *block* into the modelspace of a new DXF document and convert *block* to an external reference (XREF). The new DXF document has to be written by the caller: **xref\_doc.saveas(xref\_filename)**. This way it is possible to convert the DXF document to DWG by the *odafc* add-on if necessary: ``` xref_doc = xref.detach(my_block, "my_block.dwg") odafc.export_dwg(xref_doc, "my_block.dwg") ``` It’s recommended to clean up the entity database of the host document afterwards: ``` doc.entitydb.purge() ``` The function does not create any block references. These references should already exist and do not need to be changed since references to blocks and XREFs are the same. - **Parameters** - • **block** – block definition to detach - • **xref\_filename** – name of the external referenced file - • **overlay** – creates an XREF overlay if **True** and an XREF attachment otherwise Added in version 1.1. - **ezdxf.xref.dxf\_info(filename: str \| PathLike) -\> DXFInfo** Scans the HEADER section of a DXF document and returns a **DXFInfo** object, which contains information about the DXF version, text encoding, drawing units and insertion base point. - **Raises** **IOError** – not a DXF file or a generic IO error - **ezdxf.xref.embed(xref: BlockLayout, \*, load\_fn: Callable\[\[str\], *Drawing*\] \| None = None, search\_paths: Iterable\[Path \| str\] = tuple(), conflict\_policy=ConflictPolicy.XREF\_PREFIX) -\> None** Loads the modelspace of the XREF as content into a block layout. The loader function loads the XREF as *Drawing* object, by default the function *ezdxf.readfile()* is used to load DXF files. To load DWG files use the *readfile()* function from the *ezdxf.addons.odafc* add-on. The *ezdxf.recover.readfile()* function is very robust for reading DXF files with errors. If the XREF path isn’t absolute the XREF is searched in the folder of the host DXF document and in the *search\_path* folders. - **Parameters** - • **xref** – **BlockLayout** of the XREF document - • **load\_fn** – function to load the content of the XREF as *Drawing* object - • **search\_paths** – list of folders to search for XREFS, default is the folder of the host document or the current directory if no filepath is set - • **conflict\_policy** – how to resolve name conflicts - **Raises** - • **XrefDefinitionError** – argument *xref* is not a XREF definition - • **FileNotFoundError** – XREF file not found - • *DXFVersionError* – cannot load a XREF with a newer DXF version than the host\ document, try the *odafc* add-on to downgrade the XREF\ document or upgrade the host document Added in version 1.1. - **ezdxf.xref.load\_modelspace(sdoc: *Drawing*, tdoc: *Drawing*, filter\_fn: Callable\[\[DXFEntity\], bool\] \| None = None, conflict\_policy=ConflictPolicy.KEEP) -\> None** Loads the modelspace content of the source document into the modelspace of the target document. The filter function *filter\_fn* gets every source entity as input and returns **True** to load the entity or **False** otherwise. - **Parameters** - • **sdoc** – source document - • **tdoc** – target document - • **filter\_fn** – optional function to filter entities from the source modelspace - • **conflict\_policy** – how to resolve name conflicts Added in version 1.1. - **ezdxf.xref.load\_paperspace(psp: Paperspace, tdoc: *Drawing*, filter\_fn: Callable\[\[DXFEntity\], bool\] \| None = None, conflict\_policy=ConflictPolicy.KEEP) -\> None** Loads the paperspace layout *psp* into the target document. The filter function *filter\_fn* gets every source entity as input and returns **True** to load the entity or **False** otherwise. - **Parameters** - • **psp** – paperspace layout to load - • **tdoc** – target document - • **filter\_fn** – optional function to filter entities from the source paperspace layout - • **conflict\_policy** – how to resolve name conflicts Added in version 1.1. - **ezdxf.xref.write\_block(entities: Sequence\[DXFEntity\], \*, origin: *UVec* = (0, 0, 0)) -\> *Drawing*** Write *entities* into the modelspace of a new DXF document. This function is called “write\_block” because the new DXF document can be used as an external referenced block. This function is similar to the WBLOCK command in CAD applications. Virtual entities are not supported, because each entity needs a real database- and owner handle. - **Parameters** - • **entities** – DXF entities to write - • **origin** – block origin, defines the point in the modelspace which will be inserted at the insert location of the block reference - **Raises** **EntityError** – virtual entities are not supported Added in version 1.1. ### Conflict Policy - **class ezdxf.xref.ConflictPolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** These conflict policies define how to handle resource name conflicts. Added in version 1.1. - **KEEP** Keeps the existing resource name of the target document and ignore the resource from the source document. - **XREF\_PREFIX** This policy handles the resource import like CAD applications by **always** renaming the loaded resources to *\$0$\*, where *xref* is the name of source document, the *$0$* part is a number to create a unique resource name and *\* is the name of the resource itself. - **NUM\_PREFIX** This policy renames the loaded resources to *$0$\* only if the resource *\* already exists. The *$0$* prefix is a number to create a unique resource name and *\* is the name of the resource itself. ### Low Level Loading Interface The *Loader* class is the basic building block for loading entities and resources. The class manages a list of loading commands which is executed at once by calling the *Loader.execute()* method. It is important to execute the commands at once to get a consistent renaming of resources when using resource name prefixes otherwise the loaded resources would get a new unique name at each loading process even when the resources are loaded from the same document. - **class ezdxf.xref.Loader(sdoc: *Drawing*, tdoc: *Drawing*, conflict\_policy=ConflictPolicy.KEEP)** Load entities and resources from the source DXF document *sdoc* into the target DXF document. - **Parameters** - • **sdoc** – source DXF document - • **tdoc** – target DXF document - • **conflict\_policy** – *ConflictPolicy* - **load\_modelspace(target\_layout: BaseLayout \| None = None, filter\_fn: Callable\[\[DXFEntity\], bool\] \| None = None) -\> None** Loads the content of the modelspace of the source document into a layout of the target document, the modelspace of the target document is the default target layout. The filter function *filter\_fn* is used to skip source entities, the function should return **False** for entities to ignore and **True** otherwise. - **Parameters** - • **target\_layout** – target layout can be any layout: modelspace, paperspace layout or block layout. - • **filter\_fn** – function to filter source entities - **load\_paperspace\_layout(psp: Paperspace, filter\_fn: Callable\[\[DXFEntity\], bool\] \| None = None) -\> None** Loads a paperspace layout as a new paperspace layout into the target document. If a paperspace layout with same name already exists the layout will be renamed to “\ (2)” or “\ (3)” and so on. The filter function *filter\_fn* is used to skip source entities, the function should return **False** for entities to ignore and **True** otherwise. The content of the modelspace which may be displayed through a VIEWPORT entity will **not** be loaded! - **Parameters** - • **psp** – the source paperspace layout - • **filter\_fn** – function to filter source entities - **load\_paperspace\_layout\_into(psp: Paperspace, target\_layout: BaseLayout, filter\_fn: Callable\[\[DXFEntity\], bool\] \| None = None) -\> None** Loads the content of a paperspace layout into an existing layout of the target document. The filter function *filter\_fn* is used to skip source entities, the function should return **False** for entities to ignore and **True** otherwise. The content of the modelspace which may be displayed through a VIEWPORT entity will **not** be loaded! - **Parameters** - • **psp** – the source paperspace layout - • **target\_layout** – target layout can be any layout: modelspace, paperspace layout or block layout. - • **filter\_fn** – function to filter source entities - **load\_block\_layout(block\_layout: BlockLayout) -\> None** Loads a block layout (block definition) as a new block layout into the target document. If a block layout with the same name exists the conflict policy will be applied. This method cannot load modelspace or paperspace layouts. - **Parameters** **block\_layout** – the source block layout - **load\_block\_layout\_into(block\_layout: BlockLayout, target\_layout: BaseLayout) -\> None** Loads the content of a block layout (block definition) into an existing layout of the target document. This method cannot load the content of modelspace or paperspace layouts. - **Parameters** - • **block\_layout** – the source block layout - • **target\_layout** – target layout can be any layout: modelspace, paperspace layout or block layout. - **load\_layers(names: Sequence\[str\]) -\> None** Loads the layers defined by the argument *names* into the target document. In the case of a name conflict the conflict policy will be applied. - **load\_linetypes(names: Sequence\[str\]) -\> None** Loads the linetypes defined by the argument *names* into the target document. In the case of a name conflict the conflict policy will be applied. - **load\_text\_styles(names: Sequence\[str\]) -\> None** Loads the TEXT styles defined by the argument *names* into the target document. In the case of a name conflict the conflict policy will be applied. - **load\_dim\_styles(names: Sequence\[str\]) -\> None** Loads the DIMENSION styles defined by the argument *names* into the target document. In the case of a name conflict the conflict policy will be applied. - **load\_mline\_styles(names: Sequence\[str\]) -\> None** Loads the MLINE styles defined by the argument *names* into the target document. In the case of a name conflict the conflict policy will be applied. - **load\_mleader\_styles(names: Sequence\[str\]) -\> None** Loads the MULTILEADER styles defined by the argument *names* into the target document. In the case of a name conflict the conflict policy will be applied. - **load\_materials(names: Sequence\[str\]) -\> None** Loads the MATERIALS defined by the argument *names* into the target document. In the case of a name conflict the conflict policy will be applied. - **execute(xref\_prefix: str = '') -\> None** Execute all loading commands. The *xref\_prefix* string is used as XREF name when the conflict policy *ConflictPolicy.XREF\_PREFIX* is applied. ## ADD-ONS ### Drawing / Export Add-on This add-on provides the functionality to render a DXF document to produce a rasterized or vector-graphic image which can be saved to a file or viewed interactively depending on the backend being used. The module provides two example scripts in the folder **examples/addons/drawing** which can be run to save rendered images to files or view an interactive visualisation. ``` $ ./draw_cad.py --supported_formats # will list the file formats supported by the matplotlib backend. # Many formats are supported including vector graphics formats # such as pdf and svg $ ./draw_cad.py --out image.png # draw a layout other than the model space $ ./draw_cad.py --layout Layout1 --out image.png # opens a GUI application to view CAD files $ ./cad_viewer.py ``` **SEE ALSO:** How-to section for the FAQ about the *Drawing Add-on*. ### Design The implementation of the **drawing** add-on is divided into a frontend and multiple backends. The frontend handles the translation of DXF features and properties into simplified structures, which are then processed by the backends. ### Common Limitations to all Backends - • rich text formatting of the MTEXT entity is close to AutoCAD but not pixel perfect - • relative size of POINT entities cannot be replicated exactly - • rendering of ACIS entities is not supported - • no 3D rendering engine, therefore: - • 3D entities are projected into the xy-plane and 3D text is not supported - • only top view rendering of the modelspace - • VIEWPORTS are always rendered as top view - • no VISUALSTYLE support - • only basic support for: - • infinite lines (rendered as lines with a finite length) - • OLE2FRAME entities (rendered as rectangles) - • vertical text (will render as horizontal text) - • rendering of additional MTEXT columns may be incorrect ### MatplotlibBackend The **MatplotlibBackend** is used by the *Draw* command of the *ezdxf* launcher. Example for the usage of the **Matplotlib** backend: ``` import sys import matplotlib.pyplot as plt from ezdxf import recover from ezdxf.addons.drawing import RenderContext, Frontend from ezdxf.addons.drawing.matplotlib import MatplotlibBackend # Safe loading procedure (requires ezdxf v0.14): try: doc, auditor = recover.readfile('your.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) # The auditor.errors attribute stores severe errors, # which may raise exceptions when rendering. if not auditor.has_errors: fig = plt.figure() ax = fig.add_axes([0, 0, 1, 1]) ctx = RenderContext(doc) out = MatplotlibBackend(ax) Frontend(ctx, out).draw_layout(doc.modelspace(), finalize=True) fig.savefig('your.png', dpi=300) ``` Simplified render workflow but with less control: ``` from ezdxf import recover from ezdxf.addons.drawing import matplotlib # Exception handling left out for compactness: doc, auditor = recover.readfile('your.dxf') if not auditor.has_errors: matplotlib.qsave(doc.modelspace(), 'your.png') ``` ### PyQtBackend - **class ezdxf.addons.drawing.pyqt.PyQtBackend(scene=None)** Backend which uses the **PySide6** package to implement an interactive viewer. The **PyQt5** package can be used as fallback if the **PySide6** package is not available. - **Parameters** **scene** -- drawing canvas of type **QtWidgets.QGraphicsScene**, if **None** a new canvas will be created The **PyQtBackend** is used by the *View* command of the *ezdxf* launcher. **SEE ALSO:** The *qtviewer.py* module implements the core of a simple DXF viewer and the *cad\_viewer.py* example is a skeleton to show how to launch the **CADViewer** class. ### Recorder Added in version 1.1. This is a special backend which records the output of the *Frontend* class in compact numpy arrays and these recordings and can be played by a **Player** instance on one or more backends. The recorded numpy arrays support measurement of bounding boxes and transformations which is for some backends a requirement to place the DXF content on size limited pages. - **class ezdxf.addons.drawing.recorder.Recorder** Records the output of the Frontend class. The class implements the **BackendInterface** but does not record **enter\_entity()**, **exit\_entity()** and **clear()** events. - **player() -\> *Player*** Returns a *Player* instance with the original recordings! Make a copy of this player to protect the original recordings from being modified: ``` safe_player = recorder.player().copy() ``` - **class ezdxf.addons.drawing.recorder.Player** Plays the recordings of the *Recorder* backend on another backend. - **bbox() -\> *BoundingBox2d*** Returns the bounding box of all records as *BoundingBox2d*. - **copy() -\> Self** Returns a copy of the player with non-shared recordings. - **crop\_rect(p1: *UVec*, p2: *UVec*, distance: float) -\> None** Crop recorded shapes inplace by a rectangle defined by two points. The argument *distance* defines the approximation precision for paths which have to be approximated as polylines for cropping but only paths which are really get cropped are approximated, paths that are fully inside the crop box will not be approximated. - **Parameters** - • **p1** -- first corner of the clipping rectangle - • **p2** -- second corner of the clipping rectangle - • **distance** -- maximum distance from the center of the curve to the center of the line segment between two approximation points to determine if a segment should be subdivided. - **recordings() -\> Iterator\[tuple\[DataRecord, BackendProperties\]\]** Yields all recordings as *(DataRecord, BackendProperties)* tuples. - **replay(backend: *BackendInterface*, override: Callable\[\[BackendProperties\], *Override*\] \| None = None) -\> None** Replay the recording on another backend that implements the **BackendInterface**. The optional *override* function can be used to override the properties and state of data records, it gets the **BackendProperties** as input and must return an *Override* instance. - **transform(m: *Matrix44*) -\> None** Transforms the recordings inplace by a transformation matrix *m* of type *Matrix44*. - **class ezdxf.addons.drawing.recorder.Override(properties: BackendProperties, is\_visible: bool = True)** Represents the override state for a data record. - **properties** original or modified **BackendProperties** - **Type** ezdxf.addons.drawing.properties.BackendProperties - **is\_visible** override visibility e.g. switch layers on/off - **Type** bool ### Layout Added in version 1.1. The **Layout** class builds the page layout and the matrix to transform the DXF content to page coordinates according to the layout **Settings**. The DXF coordinate transformation is required for PDF and HPGL/2 which expects the output coordinates in the first quadrant and SVG which has an inverted y-axis. The **Layout** class uses following classes and enums for configuration: - • *Page* - page definition - • *Margins* - page margins definition - • *Settings* - configuration settings - • *Units* - enum for page units - **class ezdxf.addons.drawing.layout.Page(width: float, height: float, units: *Units* = Units.mm, margins: *Margins* = (0, 0, 0, 0), max\_width: float = 0.0, max\_height: float = 0.0)** Page definition class - **width** page width, 0 for auto-detect - **Type** float - **height** page height, 0 for auto-detect - **Type** float - **units** page units as enum *Units* - **Type** *ezdxf.addons.drawing.layout.Units* - **margins** page margins in page units - **Type** *ezdxf.addons.drawing.layout.Margins* - **max\_width** limit width for auto-detection, 0 for unlimited - **Type** float - **max\_height** limit height for auto-detection, 0 for unlimited - **Type** float - **property is\_landscape: bool** Returns **True** if the page has landscape orientation. - **property is\_portrait: bool** Returns **True** if the page has portrait orientation. (square is portrait) - **classmethod from\_dxf\_layout(layout: *DXFLayout*) -\> Self** Returns the *Page* based on the DXF attributes stored in the LAYOUT entity. The modelspace layout often **doesn't** have usable page settings! - **Parameters** **layout** -- any paperspace layout or the modelspace layout - **get\_margin\_rect(top\_origin=True) -\> tuple\[*Vec2*, *Vec2*\]** Returns the bottom-left and the top-right corner of the page margins in mm. The origin (0, 0) is the top-left corner of the page if *top\_origin* is **True** or in the bottom-left corner otherwise. - **to\_landscape() -\> None** Converts the page to landscape orientation. - **to\_portrait() -\> None** Converts the page to portrait orientation. - **class ezdxf.addons.drawing.layout.Margins(top: float, right: float, bottom: float, left: float)** Page margins definition class - **top** - **Type** float - **left** - **Type** float - **bottom** - **Type** float - **right** - **Type** float - **classmethod all(margin: float) -\> Self** Returns a page margins definition class with four equal margins. - **classmethod all2(top\_bottom: float, left\_right: float) -\> Self** Returns a page margins definition class with equal top-bottom and left-right margins. - **scale(factor: float) -\> Self** - **class ezdxf.addons.drawing.layout.PageAlignment(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Page alignment of content as enum. - **TOP\_LEFT** - **TOP\_CENTER** - **TOP\_RIGHT** - **MIDDLE\_LEFT** - **MIDDLE\_CENTER** - **MIDDLE\_RIGHT** - **BOTTOM\_LEFT** - **BOTTOM\_CENTER** - **BOTTOM\_RIGHT** - **class ezdxf.addons.drawing.layout.Settings(content\_rotation: int = 0, fit\_page: bool = True, scale: float = 1.0, page\_alignment: *PageAlignment* = PageAlignment.MIDDLE\_CENTER, crop\_at\_margins: bool = False, max\_stroke\_width: float = 0.001, min\_stroke\_width: float = 0.05, fixed\_stroke\_width: float = 0.15, output\_coordinate\_space: float = 1000000, output\_layers: bool = True)** The Layout settings. - **content\_rotation** Rotate content about 0, 90, 180 or 270 degrees - **Type** int - **fit\_page** Scale content to fit the page. - **Type** bool - **page\_alignment** Supported by backends that use the *Page* class to define the size of the output media, default alignment is *PageAlignment.MIDDLE\_CENTER* - **Type** *ezdxf.addons.drawing.layout.PageAlignment* - **crop\_at\_margins** crops the content at the page margins if **True**, when supported by the backend, default is **False** - **Type** bool - **scale** Factor to scale the DXF units of model- or paperspace, to represent 1mm in the rendered output drawing. Only uniform scaling is supported. e.g. scale 1:100 and DXF units are meters, 1m = 1000mm corresponds 10mm in the output drawing = 10 / 1000 = 0.01; e.g. scale 1:1; DXF units are mm = 1 / 1 = 1.0 the default value The value is ignored if the page size is defined and the content fits the page and the value is also used to determine missing page sizes (width or height). - **Type** float - **max\_stroke\_width** Used for **LineweightPolicy.RELATIVE** policy, *max\_stroke\_width* is defined as percentage of the content extents, e.g. 0.001 is 0.1% of max(page-width, page-height) - **Type** float - **min\_stroke\_width** Used for **LineweightPolicy.RELATIVE** policy, *min\_stroke\_width* is defined as percentage of *max\_stroke\_width*, e.g. 0.05 is 5% of *max\_stroke\_width* - **Type** float - **fixed\_stroke\_width** Used for **LineweightPolicy.RELATIVE\_FIXED** policy, *fixed\_stroke\_width* is defined as percentage of *max\_stroke\_width*, e.g. 0.15 is 15% of *max\_stroke\_width* - **Type** float - **output\_coordinate\_space** expert feature to map the DXF coordinates to the output coordinate system \[0, output\_coordinate\_space\] - **Type** float - **output\_layers** For supported backends, separate the entities into 'layers' in the output - **Type** bool - **class ezdxf.addons.drawing.layout.Units(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Page units as enum. - **inch** 25\.4 mm - **px** 1/96 inch - **pt** 1/72 inch - **mm** - **cm** ### SVGBackend Added in version 1.1. - **class ezdxf.addons.drawing.svg.SVGBackend** This is a native SVG rendering backend and does not require any external packages to render SVG images other than the core dependencies. This backend support content cropping at page margins. - **get\_xml\_root\_element(page: *Page*, \*, settings: *Settings* = layout.Settings(), render\_box: *BoundingBox2d* \| None = None) -\> Element** - **get\_string(page: *Page*, \*, settings: *Settings* = layout.Settings(), render\_box: *BoundingBox2d* \| None = None, xml\_declaration=True) -\> str** Returns the XML data as unicode string. - **Parameters** - • **page** -- page definition, see *Page* - • **settings** -- layout settings, see *Settings* - • **render\_box** -- set explicit region to render, default is content bounding box - • **xml\_declaration** -- inserts the "\" string in front of the \ element Usage: ``` from ezdxf.addons.drawing import Frontend, RenderContext from ezdxf.addons.drawing import layout, svg doc = ezdxf.readfile("your.dxf") msp = doc.modelspace() backend = svg.SVGBackend() Frontend(RenderContext(doc), backend).draw_layout(msp) with open("your.svg", "wt") as fp: fp.write(backend.get_string(layout.Page(0, 0)) ``` ### PyMuPdfBackend Added in version 1.1. - **class ezdxf.addons.drawing.pymupdf.PyMuPdfBackend** This backend uses the *PyMuPdf* package to create PDF, PNG, PPM and PBM output. This backend support content cropping at page margins. PyMuPDF is licensed under the *AGPL*. Sorry, but it's the best package for the job I've found so far. Install package: ``` pip install pymupdf ``` - **get\_pdf\_bytes(page: *Page*, \*, settings: *Settings* = layout.Settings(), render\_box: *BoundingBox2d* \| None = None) -\> bytes** Returns the PDF document as bytes. - **Parameters** - • **page** -- page definition, see *Page* - • **settings** -- layout settings, see *Settings* - • **render\_box** -- set explicit region to render, default is content bounding box - **get\_pixmap\_bytes(page: *Page*, \*, fmt='png', settings: *Settings* = layout.Settings(), dpi: int = 96, alpha=False, render\_box: *BoundingBox2d* \| None = None) -\> bytes** Returns a pixel image as bytes, supported image formats: | | | | --- | --- | | png | Portable Network Graphics | | ppm | Portable Pixmap (no alpha channel) | | pbm | Portable Bitmap (no alpha channel) | - **Parameters** - • **page** -- page definition, see *Page* - • **fmt** -- image format - • **settings** -- layout settings, see *Settings* - • **dpi** -- output resolution in dots per inch - • **alpha** -- add alpha channel (transparency) - • **render\_box** -- set explicit region to render, default is content bounding box Usage: ``` import ezdxf from ezdxf.addons.drawing import Frontend, RenderContext from ezdxf.addons.drawing import layout, pymupdf doc = ezdxf.readfile("your.dxf") msp = doc.modelspace() backend = pymupdf.PyMuPdfBackend() Frontend(RenderContext(doc), backend).draw_layout(msp) with open("your.pdf", "wb") as fp: fp.write(backend.get_pdf_bytes(layout.Page(0, 0)) ``` Load the output of the **PyMuPdfBackend** into the **Image** class of the *Pillow* package for further processing or to output additional image formats: ``` import io from PIL import Image ... # see above # the ppm format is faster to process than png fp = io.BytesIO(backend.get_pixmap_bytes(layout.Page(0, 0), fmt="ppm", dpi=300)) image = Image.open(fp, formats=["ppm"]) ``` ### PlotterBackend Added in version 1.1. - **class ezdxf.addons.drawing.hpgl2.PlotterBackend** The *PlotterBackend* creates HPGL/2 plot files for output on raster plotters. This backend does not need any additional packages. This backend support content cropping at page margins. The plot files are tested by the plot file viewer *ViewCompanion Standard* but not on real hardware - please use with care and give feedback. - **get\_bytes(page: *Page*, \*, settings: *Settings* = layout.Settings(), render\_box: *BoundingBox2d* \| None = None, curves=True, decimal\_places: int = 1, base=64) -\> bytes** Returns the HPGL/2 data as bytes. - **Parameters** - • **page** -- page definition, see *Page* - • **settings** -- layout settings, see *Settings* - • **render\_box** -- set explicit region to render, default is content bounding box - • **curves** -- use Bèzier curves for HPGL/2 output - • **decimal\_places** -- HPGL/2 output precision, less decimal places creates smaller files but for the price of imprecise curves (text) - • **base** -- base for polyline encoding, 32 for 7 bit encoding or 64 for 8 bit encoding - **compatible(page: *Page*, settings: *Settings* = layout.Settings()) -\> bytes** Returns the HPGL/2 data as 7-bit encoded bytes curves as approximated polylines and coordinates are rounded to integer values. Has often the smallest file size and should be compatible to all output devices but has a low quality text rendering. - **low\_quality(page: *Page*, settings: *Settings* = layout.Settings()) -\> bytes** Returns the HPGL/2 data as 8-bit encoded bytes, curves as Bézier curves and coordinates are rounded to integer values. Has a smaller file size than normal quality and the output device must support 8-bit encoding and Bèzier curves. - **normal\_quality(page: *Page*, settings: *Settings* = layout.Settings()) -\> bytes** Returns the HPGL/2 data as 8-bit encoded bytes, curves as Bézier curves and coordinates are floats rounded to one decimal place. Has a smaller file size than high quality and the output device must support 8-bit encoding, Bèzier curves and fractional coordinates. - **high\_quality(page: *Page*, settings: *Settings* = layout.Settings()) -\> bytes** Returns the HPGL/2 data as 8-bit encoded bytes and all curves as Bézier curves and coordinates are floats rounded to two decimal places. Has the largest file size and the output device must support 8-bit encoding, Bèzier curves and fractional coordinates. Usage: ``` import ezdxf from ezdxf.addons.drawing import Frontend, RenderContext from ezdxf.addons.drawing import layout, hpgl2 doc = ezdxf.readfile("your.dxf") psp = doc.paperspace("Layout1") backend = hpgl2.PlotterBackend() Frontend(RenderContext(doc), backend).draw_layout(psp) page = layout.Page.from_dxf_layout(psp) with open("your.plt", "wb") as fp: fp.write(backend.normal_quality(page) ``` You can check the output by the HPGL/2 viewer: ``` ezdxf hpgl your.plt ``` ### DXFBackend Added in version 1.1. - **class ezdxf.addons.drawing.dxf.DXFBackend(layout: BaseLayout, color\_mode: *ColorMode* = ColorMode.RGB)** The *DXFBackend* creates simple DXF files of POINT, LINE, LWPOLYLINE and HATCH entities. This backend does ot need any additional packages. - **Parameters** - • **layout** -- a DXF *BaseLayout* - • **color\_mode** -- see *ColorMode* - **class ezdxf.addons.drawing.dxf.ColorMode(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** This enum is used to define the color output mode of the *DXFBackend*. - **ACI** the color is set as *AutoCAD Color Index (ACI)* and assigned by layer - **RGB** the color is set as RGB true color value Render a paperspace layout into modelspace: ``` import ezdxf from ezdxf.addons.drawing import Frontend, RenderContext from ezdxf.addons.drawing import layout, dxf doc = ezdxf.readfile("your.dxf") layout1 = doc.paperspace("Layout1") output_doc = ezdxf.new() output_msp = output_doc.modelspace() backend = dxf.DXFBackend(output_msp) Frontend(RenderContext(doc), backend).draw_layout(layout1) output_doc.saveas("layout1_in_modelspace.dxf") ``` ### GeoJSONBackend Added in version 1.3.0. - **class ezdxf.addons.drawing.json.GeoJSONBackend(properties\_maker: Callable\[\[str, float, str\], Dict\[str, Any\]\] = properties\_maker, transform\_func: Callable\[\[*Vec2*\], Tuple\[float, float\]\] = no\_transform)** Creates a JSON-like output according the *GeoJSON* scheme. GeoJSON uses a geographic coordinate reference system, World Geodetic System 1984 *EPSG:4326*, and units of decimal degrees. - • Latitude: -90 to +90 (South/North) - • Longitude: -180 to +180 (East/West) So most DXF files will produce invalid coordinates and it is the job of the **package-user** to provide a function to transfrom the input coordinates to EPSG:4326! The *Recorder* and *Player* classes can help to detect the extents of the DXF content. Default implementation: - **no\_transform(location: *Vec2*) -\> tuple\[float, float\]** Dummy transformation function. Does not apply any transformations and just returns the input coordinates. Factory function to make a transform function from WGS84 World Mercator *EPSG:3395* coordinates to WGS84 (GPS) *EPSG:4326*. - **make\_world\_mercator\_to\_gps\_function(tol: float = 1e-6) -\> Callable\[\[*Vec2*\], Tuple\[float, float\]\]** Returns a function to transform WGS84 World Mercator *EPSG:3395* location given as cartesian 2D coordinates x, y in meters into WGS84 decimal degrees as longitude and latitude *EPSG:4326* as used by GPS. - **Parameters** **tol** -- accuracy for latitude calculation The GeoJSON format supports only straight lines so curved shapes are flattened to polylines and polygons. The properties are handled as a foreign member feature and is therefore not defined in the GeoJSON specs. It is possible to provide a custom function to create these property objects. Default implementation: - **properties\_maker(color: str, stroke\_width: float, layer: str) -\> dict\[str, Any\]** Returns the property dict: ``` { "color": color, "stroke-width": stroke_width, "layer": layer, } ``` Returning an empty dict prevents properties in the GeoJSON output and also avoids wraping entities into "Feature" objects. - **Parameters** **properties\_maker** -- function to create a properties dict. **Class Methods** - **get\_json\_data() -\> dict\[str, Any\]** Returns the result as a JSON-like data structure according the GeoJSON specs. - **get\_string(\*, indent: int \| str = 2) -\> str** Returns the result as a JSON string. Added in version 1.3.0. ### CustomJSONBackend Added in version 1.3.0. - **class ezdxf.addons.drawing.json.CustomJSONBackend(orient\_paths=False)** Creates a JSON-like output with a custom JSON scheme. This scheme supports curved shapes by a SVG-path like structure and coordinates are not limited in any way. This backend can be used to send geometries from a web-backend to a frontend. The JSON scheme is documented in the source code: *https://github.com/mozman/ezdxf/blob/master/src/ezdxf/addons/drawing/json.py* - **Parameters** **orient\_paths** -- orient exterior and hole paths on demand, exterior paths have counter-clockwise orientation and holes have clockwise orientation. **Class Methods** - **get\_json\_data() -\> list\[dict\[str, Any\]\]** Returns the result as a JSON-like data structure. - **get\_string(\*, indent: int \| str = 2) -\> str** Returns the result as a JSON string. Added in version 1.3.0. ### Configuration Additional options for the drawing add-on can be passed by the *config* argument of the **Frontend** constructor **\_\_init\_\_()**. Not every option will be supported by all backends. Usage: ``` my_config = Configuration(lineweight_scaling=2) ``` - **class ezdxf.addons.drawing.config.Configuration(pdsize: int \| None = None, pdmode: int \| None = None, measurement: *Measurement* \| None = None, show\_defpoints: bool = False, proxy\_graphic\_policy: *ProxyGraphicPolicy* = ProxyGraphicPolicy.SHOW, line\_policy: *LinePolicy* = LinePolicy.ACCURATE, hatch\_policy: *HatchPolicy* = HatchPolicy.NORMAL, infinite\_line\_length: float = 20, lineweight\_scaling: float = 1.0, min\_lineweight: float \| None = None, min\_dash\_length: float = 0.1, max\_flattening\_distance: float = 0.01, circle\_approximation\_count: int = 128, hatching\_timeout: float = 30.0, min\_hatch\_line\_distance: float = 0.0001, color\_policy: *ColorPolicy* = ColorPolicy.COLOR, custom\_fg\_color: str = '#000000', background\_policy: *BackgroundPolicy* = BackgroundPolicy.DEFAULT, custom\_bg\_color: str = '#ffffff', lineweight\_policy: *LineweightPolicy* = LineweightPolicy.ABSOLUTE, text\_policy: *TextPolicy* = TextPolicy.FILLING, image\_policy: *ImagePolicy* = ImagePolicy.DISPLAY)** Configuration options for the **drawing** add-on. - **pdsize** the size to draw POINT entities (in drawing units) set to None to use the $PDSIZE value from the dxf document header | | | | --- | --- | | 0 | 5% of draw area height | | \<0 | Specifies a percentage of the viewport size | | \>0 | Specifies an absolute size | | None | use the $PDMODE value from the dxf document header | - **Type** int \| None - **pdmode** point styling mode (see POINT documentation) see *Point* class documentation - **Type** int \| None - **measurement** whether to use metric or imperial units as enum *ezdxf.enums.Measurement* | | | | --- | --- | | 0 | use imperial units (in, ft, yd, ...) | | 1 | use metric units (ISO meters) | | None | use the $MEASUREMENT value from the dxf document header | - **Type** *ezdxf.enums.Measurement* \| None - **show\_defpoints** whether to show or filter out POINT entities on the defpoints layer - **Type** bool - **proxy\_graphic\_policy** the action to take when a proxy graphic is encountered - **Type** *ezdxf.addons.drawing.config.ProxyGraphicPolicy* - **line\_policy** the method to use when drawing styled lines (eg dashed, dotted etc) - **Type** *ezdxf.addons.drawing.config.LinePolicy* - **hatch\_policy** the method to use when drawing HATCH entities - **Type** *ezdxf.addons.drawing.config.HatchPolicy* - **infinite\_line\_length** the length to use when drawing infinite lines - **Type** float - **lineweight\_scaling** multiplies every lineweight by this factor; set this factor to 0.0 for a constant minimum line width defined by the *min\_lineweight* setting for all lineweights; the correct DXF lineweight often looks too thick in SVG, so setting a factor \< 1 can improve the visual appearance - **Type** float - **min\_lineweight** the minimum line width in 1/300 inch; set to **None** for let the backend choose. - **Type** float \| None - **min\_dash\_length** the minimum length for a dash when drawing a styled line (default value is arbitrary) - **Type** float - **max\_flattening\_distance** Max flattening distance in drawing units see Path.flattening documentation. The backend implementation should calculate an appropriate value, like 1 screen- or paper pixel on the output medium, but converted into drawing units. Sets Path() approximation accuracy - **Type** float - **circle\_approximation\_count** Approximate a full circle by *n* segments, arcs have proportional less segments. Only used for approximation of arcs in banded polylines. - **Type** int - **hatching\_timeout** hatching timeout for a single entity, very dense hatching patterns can cause a very long execution time, the default timeout for a single entity is 30 seconds. - **Type** float - **min\_hatch\_line\_distance** minimum hatch line distance to render, narrower pattern lines are rendered as solid filling - **Type** float - **color\_policy** - **Type** *ezdxf.addons.drawing.config.ColorPolicy* - **custom\_fg\_color** Used for **ColorPolicy.custom** policy, custom foreground color as "#RRGGBBAA" color string (RGB+alpha) - **Type** str - **background\_policy** - **Type** *ezdxf.addons.drawing.config.BackgroundPolicy* - **custom\_bg\_color** Used for **BackgroundPolicy.custom** policy, custom background color as "#RRGGBBAA" color string (RGB+alpha) - **Type** str - **lineweight\_policy** - **Type** *ezdxf.addons.drawing.config.LineweightPolicy* - **text\_policy** - **Type** *ezdxf.addons.drawing.config.TextPolicy* - **image\_policy** the method for drawing IMAGE entities - **Type** *ezdxf.addons.drawing.config.ImagePolicy* - **with\_changes()** Returns a new frozen *Configuration* object with modified values. ### BackgroundPolicy - **class ezdxf.addons.drawing.config.BackgroundPolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** This enum is used to define the background color. - **DEFAULT** as resolved by the **Frontend** class - **WHITE** white background - **BLACK** black background - **PAPERSPACE** default paperspace background - **MODELSPACE** default modelspace background - **OFF** fully transparent background - **CUSTOM** custom background color by *Configuration.custom\_bg\_color* ### ColorPolicy - **class ezdxf.addons.drawing.config.ColorPolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** This enum is used to define how to determine the line/fill color. - **COLOR** as resolved by the **Frontend** class - **COLOR\_SWAP\_BW** as resolved by the **Frontend** class but swaps black and white - **COLOR\_NEGATIVE** invert all colors - **MONOCHROME** maps all colors to gray scale in range \[0%, 100%\] - **MONOCHROME\_DARK\_BG** maps all colors to gray scale in range \[30%, 100%\], brightens colors for dark backgrounds - **MONOCHROME\_LIGHT\_BG** maps all colors to gray scale in range \[0%, 70%\], darkens colors for light backgrounds - **BLACK** maps all colors to black - **WHITE** maps all colors to white - **CUSTOM** maps all colors to custom color *Configuration.custom\_fg\_color* ### HatchPolicy - **class ezdxf.addons.drawing.config.HatchPolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The action to take when a HATCH entity is encountered - **NORMAL** render pattern and solid fillings - **IGNORE** do not show HATCH entities at all - **SHOW\_OUTLINE** show only the outline of HATCH entities - **SHOW\_SOLID** show HATCH entities as solid filling regardless of the pattern ### ImagePolicy - **class ezdxf.addons.drawing.config.ImagePolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** This enum is used to define the image rendering. - **DISPLAY** display images as they would appear in a regular CAD application - **RECT** display images as rectangles - **MISSING** images are always rendered as-if they are missing (rectangle + path text) - **PROXY** images are rendered using their proxy representations (rectangle) - **IGNORE** ignore images entirely ### LinePolicy - **class ezdxf.addons.drawing.config.LinePolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** This enum is used to define how to render linetypes. **NOTE:** Text and shapes in linetypes are not supported. - **SOLID** draw all lines as solid regardless of the linetype style - **ACCURATE** render styled lines as accurately as possible - **APPROXIMATE** ignored since v0.18.1 - uses always ACCURATE by default ### LineweightPolicy - **class ezdxf.addons.drawing.config.LineweightPolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** This enum is used to define how to determine the lineweight. - **ABSOLUTE** in mm as resolved by the **Frontend** class - **RELATIVE** lineweight is relative to page size - **RELATIVE\_FIXED** fixed lineweight relative to page size for all strokes ### ProxyGraphicPolicy - **class ezdxf.addons.drawing.config.ProxyGraphicPolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The action to take when an entity with a proxy graphic is encountered **NOTE:** To get proxy graphics support proxy graphics have to be loaded: Set the global option *ezdxf.options.load\_proxy\_graphics* to **True**, which is the default value. This can not prevent drawing proxy graphic inside of blocks, because this is beyond the domain of the drawing add-on! - **IGNORE** do not display proxy graphics (skip\_entity will be called instead) - **SHOW** if the entity cannot be rendered directly (e.g. if not implemented) but a proxy is present: display the proxy - **PREFER** display proxy graphics even for entities where direct rendering is available ### TextPolicy - **class ezdxf.addons.drawing.config.TextPolicy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** This enum is used to define the text rendering. - **FILLING** text is rendered as solid filling (default) - **OUTLINE** text is rendered as outline paths - **REPLACE\_RECT** replace text by a rectangle - **REPLACE\_FILL** replace text by a filled rectangle - **IGNORE** ignore text entirely ### Properties - **class ezdxf.addons.drawing.properties.Properties** An implementation agnostic representation of DXF entity properties like color and linetype. These properties represent the actual values after resolving all DXF specific rules like "by layer", "by block" and so on. - **color** The actual color value of the DXF entity as "#RRGGBB" or "#RRGGBBAA" string. An alpha value of "00" is opaque and "ff" is fully transparent. - **rgb** RGB values extract from the *color* value as tuple of integers. - **luminance** Perceived luminance calculated from the *color* value as float in the range \[0.0, 1.0\]. - **linetype\_name** The actual linetype name as string like "CONTINUOUS" - **linetype\_pattern** The simplified DXF linetype pattern as tuple of floats, all line elements and gaps are values greater than 0.0 and 0.0 represents a point. Line or point elements do always alternate with gap elements: line-gap-line-gap-point-gap and the pattern always ends with a gap. The continuous line is an empty tuple. - **linetype\_scale** The scaling factor as float to apply to the *linetype\_pattern*. - **lineweight** The absolute lineweight to render in mm as float. - **is\_visible** Visibility flag as bool. - **layer** The actual layer name the entity resides on as UPPERCASE string. - **font** The **FontFace** used for text rendering or **None**. - **filling** The actual **Filling** properties of the entity or **None**. - **units** The actual drawing units as *InsertUnits* enum. ### LayerProperties - **class ezdxf.addons.drawing.properties.LayerProperties** Actual layer properties, inherits from class **Properties**. - **is\_visible** Modified meaning: whether entities belonging to this layer should be drawn - **layer** Modified meaning: stores real layer name (mixed case) ### LayoutProperties - **class ezdxf.addons.drawing.properties.LayoutProperties** Actual layout properties. - **name** Layout name as string - **units** Layout units as *InsertUnits* enum. - **property LayoutProperties.background\_color: str** Returns the default layout background color. - **property LayoutProperties.default\_color: str** Returns the default layout foreground color. - **property LayoutProperties.has\_dark\_background: bool** Returns **True** if the actual background-color is "dark". - **LayoutProperties.set\_colors(bg: str, fg: str \| None = None) -\> None** Setup default layout colors. Required color format "#RRGGBB" or including alpha transparency "#RRGGBBAA". ### RenderContext - **class ezdxf.addons.drawing.properties.RenderContext(doc: *Drawing* \| None = None, \*, ctb: str \| CTB = '', export\_mode: bool = False)** The render context for the given DXF document. The *RenderContext* resolves the properties of DXF entities from the context they reside in to actual values like RGB colors, transparency, linewidth and so on. A given *ctb* file (plot style file) overrides the default properties for all layouts, which means the plot style table stored in the layout is always ignored. - **Parameters** - • **doc** -- DXF document - • **ctb** -- path to a plot style table or a *ColorDependentPlotStyles* instance - • **export\_mode** -- Whether to render the document as it would look when exported (plotted) by a CAD application to a file such as pdf, or whether to render the document as it would appear inside a CAD application. - **resolve\_aci\_color(aci: int, resolved\_layer: str) -\> str** Resolve the *aci* color as hex color string: "#RRGGBB" - **resolve\_all(entity: DXFGraphic) -\> *Properties*** Resolve all properties of *entity*. - **resolve\_color(entity: DXFGraphic, \*, resolved\_layer: str \| None = None) -\> str** Resolve the rgb-color of *entity* as hex color string: "#RRGGBB" or "#RRGGBBAA". - **resolve\_filling(entity: DXFGraphic) -\> Filling \| None** Resolve filling properties (SOLID, GRADIENT, PATTERN) of *entity*. - **resolve\_font(entity: DXFGraphic) -\> *FontFace* \| None** Resolve the text style of *entity* to a font name. Returns **None** for the default font. - **resolve\_layer(entity: DXFGraphic) -\> str** Resolve the layer of *entity*, this is only relevant for entities inside of block references. - **resolve\_layer\_properties(layer: Layer) -\> *LayerProperties*** Resolve layer properties. - **resolve\_linetype(entity: DXFGraphic, \*, resolved\_layer: str \| None = None) -\> tuple\[str, Sequence\[float\]\]** Resolve the linetype of *entity*. Returns a tuple of the linetype name as upper-case string and the simplified linetype pattern as tuple of floats. - **resolve\_lineweight(entity: DXFGraphic, \*, resolved\_layer: str \| None = None) -\> float** Resolve the lineweight of *entity* in mm. DXF stores the lineweight in mm times 100 (e.g. 0.13mm = 13). The smallest line weight is 0 and the biggest line weight is 211. The DXF/DWG format is limited to a fixed value table, see: **ezdxf.lldxf.const.VALID\_DXF\_LINEWEIGHTS** CAD applications draw lineweight 0mm as an undefined small value, to prevent backends to draw nothing for lineweight 0mm the smallest return value is 0.01mm. - **resolve\_units() -\> *InsertUnits*** - **resolve\_visible(entity: DXFGraphic, \*, resolved\_layer: str \| None = None) -\> bool** Resolve the visibility state of *entity*. Returns **True** if *entity* is visible. - **set\_current\_layout(layout: *Layout*, ctb: str \| CTB = '')** Set the current layout and update layout specific properties. - **Parameters** - • **layout** -- modelspace or a paperspace layout - • **ctb** -- path to a plot style table or a *ColorDependentPlotStyles* instance - **set\_layer\_properties\_override(func: Callable\[\[Sequence\[*LayerProperties*\]\], None\] \| None = None)** The function *func* is called with the current layer properties as argument after resetting them, so the function can override the layer properties. The **RenderContext** class can be used isolated from the **drawing** add-on to resolve DXF properties. ### Frontend - **class ezdxf.addons.drawing.frontend.Frontend(ctx: *RenderContext*, out: *BackendInterface*, config: *Configuration* = Configuration.defaults(), bbox\_cache: *ezdxf.bbox.Cache* = None)** Drawing frontend for 2D backends, responsible for decomposing entities into graphic primitives and resolving entity properties. By passing the bounding box cache of the modelspace entities can speed up paperspace rendering, because the frontend can filter entities which are not visible in the VIEWPORT. Even passing in an empty cache can speed up rendering time when multiple viewports need to be processed. - **Parameters** - • **ctx** -- the properties relevant to rendering derived from a DXF document - • **out** -- the 2D backend to draw to - • **config** -- settings to configure the drawing frontend and backend - • **bbox\_cache** -- bounding box cache of the modelspace entities or an empty cache which will be filled dynamically when rendering multiple viewports or **None** to disable bounding box caching at all - **log\_message(message: str)** Log given message - override to alter behavior. - **skip\_entity(entity: DXFEntity, msg: str) -\> None** Called for skipped entities - override to alter behavior. - **override\_properties(entity: DXFGraphic, properties: *Properties*) -\> None** This method can change the resolved properties of an DXF entity. The method has access to the DXF entity attributes, the current render context and the resolved properties. It is recommended to modify only the resolved *properties* in this method, because the DXF entities are not copies - except for virtual entities. Changed in version 1.3.0: This method is the first function in the stack of new property override functions. It is possible to push additional override functions onto this stack, see also *push\_property\_override\_function()*. - **push\_property\_override\_function(override\_fn: Callable\[\[DXFGraphic, *Properties*\], None\]) -\> None** The override function can change the resolved properties of an DXF entity. The override function has access to the DXF entity attributes and the resolved properties. It is recommended to modify only the resolved *properties* in this function, because the DXF entities are not copies - except for virtual entities. The override functions are called after resolving the DXF attributes of an entity and before the **Frontend.draw\_entity()** method in the order from first to last. Added in version 1.3.0. - **pop\_property\_override\_function() -\> None** Remove the last function from the property override stack. Does not raise an exception if the override stack is empty. Added in version 1.3.0. - **draw\_layout(layout: Layout, finalize: bool = True, \*, filter\_func: Callable\[\[DXFGraphic\], bool\] \| None = None, layout\_properties: *LayoutProperties* \| None = None) -\> None** Draw all entities of the given *layout*. Draws the entities of the layout in the default or redefined redraw-order and calls the **finalize()** method of the backend if requested. The default redraw order is the ascending handle order not the order the entities are stored in the layout. The method skips invisible entities and entities for which the given filter function returns **False**. - **Parameters** - • **layout** -- layout to draw of type *Layout* - • **finalize** -- **True** if the **finalize()** method of the backend should be called automatically - • **filter\_func** -- function to filter DXf entities, the function should return **False** if a given entity should be ignored - • **layout\_properties** -- override the default layout properties ### BackendInterface - **class ezdxf.addons.drawing.backend.BackendInterface** Public interface definition for 2D rendering backends. For more information read the source code: *backend.py* ### Backend - **class ezdxf.addons.drawing.backend.Backend** Abstract base class for concrete backend implementations and implements some default features. For more information read the source code: *backend.py* ### Details The rendering is performed in two stages. The frontend traverses the DXF document structure, converting each encountered entity into primitive drawing commands. These commands are fed to a backend which implements the interface: *Backend*. Although the resulting images will not be pixel-perfect with AutoCAD (which was taken as the ground truth when developing this add-on) great care has been taken to achieve similar behavior in some areas: - • The algorithm for determining color should match AutoCAD. However, the color palette is not stored in the DXF file, so the chosen colors may be different to what is expected. The *RenderContext* class supports passing a plot style table (*CTB*-file) as custom color palette but uses the same palette as AutoCAD by default. - • Text rendering is quite accurate, text positioning, alignment and word wrapping are very faithful. Differences may occur if a different font from what was used by the CAD application but even in that case, for supported backends, measurements are taken of the font being used to match text as closely as possible. - • Visibility determination (based on which layers are visible) should match AutoCAD **SEE ALSO:** - • *draw\_cad.py* for a simple use of this module - • *cad\_viewer.py* for an advanced use of this module - • *Notes on Rendering DXF Content* for additional behaviours documented during the development of this add-on. ### Geo Interface ### Intended Usage The intended usage of the *ezdxf.addons.geo* module is as tool to work with geospatial data in conjunction with dedicated geospatial applications and libraries and the module can not and should not replicate their functionality. The only reimplemented feature is the most common WSG84 EPSG:3395 World Mercator projection, for everything else use the dedicated packages like: - • *pyproj* - Cartographic projections and coordinate transformations library. - • *Shapely* - Manipulation and analysis of geometric objects in the Cartesian plane. - • *PyShp* - The Python Shapefile Library (PyShp) reads and writes ESRI Shapefiles in pure Python. - • *GeoJSON* - GeoJSON interface for Python. - • *GDAL* - Tools for programming and manipulating the GDAL Geospatial Data Abstraction Library. - • *Fiona* - Fiona is GDAL’s neat and nimble vector API for Python programmers. - • *QGIS* - A free and open source geographic information system. - • and many more … This module provides support for the **\_\_geo\_interface\_\_**: *https://gist.github.com/sgillies/2217756* Which is also supported by *Shapely*, for supported types see the *GeoJSON* Standard and examples in *Appendix-A*. **SEE ALSO:** *Tutorial for the Geo Add-on* for loading GPX data into DXF files with an existing geo location reference and exporting DXF entities as GeoJSON data. ### Proxy From Mapping The *GeoProxy* represents a **\_\_geo\_interface\_\_** mapping, create a new proxy by *GeoProxy.parse()* from an external **\_\_geo\_interface\_\_** mapping. *GeoProxy.to\_dxf\_entities()* returns new DXF entities from this mapping. Returns “Point” as *Point* entity, “LineString” as *LWPolyline* entity and “Polygon” as *Hatch* entity or as separated *LWPolyline* entities (or both) and new in v0.16.6 as *MPolygon*. Supports “MultiPoint”, “MultiLineString”, “MultiPolygon”, “GeometryCollection”, “Feature” and “FeatureCollection”. Add new DXF entities to a layout by the **Layout.add\_entity()** method. ### Proxy From DXF Entity The *proxy()* function or the constructor *GeoProxy.from\_dxf\_entities()* creates a new *GeoProxy* object from a single DXF entity or from an iterable of DXF entities, entities without a corresponding representation will be approximated. Supported DXF entities are: - • POINT as “Point” - • LINE as “LineString” - • LWPOLYLINE as “LineString” if open and “Polygon” if closed - • POLYLINE as “LineString” if open and “Polygon” if closed, supports only 2D and 3D polylines, POLYMESH and POLYFACE are not supported - • SOLID, TRACE, 3DFACE as “Polygon” - • CIRCLE, ARC, ELLIPSE and SPLINE by approximation as “LineString” if open and “Polygon” if closed - • HATCH and MPOLYGON as “Polygon”, holes are supported **WARNING:** This module does no extensive validity checks for “Polygon” objects and because DXF has different requirements for HATCH boundary paths than the *GeoJSON* Standard, it is possible to create invalid “Polygon” objects. It is recommended to check critical objects by a sophisticated geometry library like *Shapely*. ### Module Functions - **ezdxf.addons.geo.proxy(entity: DXFGraphic \| Iterable\[DXFGraphic\], distance: float = MAX\_FLATTENING\_DISTANCE, force\_line\_string: bool = False) -\> *GeoProxy*** Returns a *GeoProxy* object. - **Parameters** - • **entity** – a single DXF entity or iterable of DXF entities - • **distance** – maximum flattening distance for curve approximations - • **force\_line\_string** – by default this function returns Polygon objects for closed geometries like CIRCLE, SOLID, closed POLYLINE and so on, by setting argument *force\_line\_string* to **True**, this entities will be returned as LineString objects. - **ezdxf.addons.geo.dxf\_entities(geo\_mapping: MutableMapping\[str, Any\], polygon=PolygonConversion.HATCH, dxfattribs=None, \*, post\_process: Callable\[\[DXFGraphic, MutableMapping\[str, Any\]\], None\] \| None = None) -\> Iterator\[DXFGraphic\]** Returns **\_\_geo\_interface\_\_** mappings as DXF entities. The enum *polygon* determines the method to convert polygons, use *PolygonConversion.HATCH* for *Hatch* entity, *PolygonConversion.POLYLINE* for *LWPolyline* or *PolygonConversion.HATCH\_AND\_POLYLINE* for both. Option *PolygonConversion.POLYLINE* returns for the exterior path and each hole a separated **LWPolyline** entity. The **Hatch** entity supports holes, but has no explicit borderline. Yields **Hatch** always before **LWPolyline** entities. *PolygonConversion.MPOLYGON* support was added in v0.16.6, which is like a *Hatch* entity with additional borderlines, but the MPOLYGON entity is not a core DXF entity and DXF viewers, applications and libraries my not support this entity. The DXF attribute *color* defines the borderline color and *fill\_color* the color of the solid filling. The returned DXF entities can be added to a layout by the **Layout.add\_entity()** method. - **Parameters** - • **geo\_mapping** – **\_\_geo\_\_interface\_\_** mapping as **dict** or a Python object with a **\_\_geo\_\_interface\_\_** property - • **polygon** – see *PolygonConversion* - • **dxfattribs** – dict with additional DXF attributes - • **post\_process** – post process function of type *PostProcessFunc* that get the created DXF entity and the geo mapping as input, see reference implementation *assign\_layers()* - **ezdxf.addons.geo.gfilter(entities: Iterable\[DXFGraphic\]) -\> Iterator\[DXFGraphic\]** Filter DXF entities from iterable *entities*, which are incompatible to the **\_\_geo\_reference\_\_** interface. ### GeoProxy Class - **class ezdxf.addons.geo.GeoProxy(geo\_mapping: MutableMapping\[str, Any\], places: int = 6)** Stores the **\_\_geo\_interface\_\_** mapping in a parsed and compiled form. Stores coordinates as **Vec3** objects and represents “Polygon” always as tuple (exterior, holes) even without holes. The GeoJSON specification recommends 6 decimal places for latitude and longitude which equates to roughly 10cm of precision. You may need slightly more for certain applications, 9 decimal places would be sufficient for professional survey-grade GPS coordinates. - **Parameters** - • **geo\_mapping** – parsed and compiled **\_\_geo\_interface\_\_** mapping - • **places** – decimal places to round for **\_\_geo\_interface\_\_** export - **\_\_geo\_interface\_\_** Returns the **\_\_geo\_interface\_\_** compatible mapping as **dict**. - **geotype** Property returns the top level entity type or **None**. - **classmethod parse(geo\_mapping: MutableMapping\[str, Any\]) -\> Self** Parse and compile a **\_\_geo\_interface\_\_** mapping as **dict** or a Python object with a **\_\_geo\_interface\_\_** property, does some basic syntax checks, converts all coordinates into **Vec3** objects, represents “Polygon” always as tuple (exterior, holes) even without holes. - **classmethod from\_dxf\_entities(entity: DXFGraphic \| Iterable\[DXFGraphic\], distance: float = MAX\_FLATTENING\_DISTANCE, force\_line\_string: bool = False) -\> *GeoProxy*** Constructor from a single DXF entity or an iterable of DXF entities. - **Parameters** - • **entity** – DXF entity or entities - • **distance** – maximum flattening distance for curve approximations - • **force\_line\_string** – by default this function returns Polygon objects for closed geometries like CIRCLE, SOLID, closed POLYLINE and so on, by setting argument *force\_line\_string* to **True**, this entities will be returned as LineString objects. - **to\_dxf\_entities(polygon=PolygonConversion.HATCH, dxfattribs=None, \*, post\_process: Callable\[\[DXFGraphic, MutableMapping\[str, Any\]\], None\] \| None = None) -\> Iterator\[DXFGraphic\]** Returns stored **\_\_geo\_interface\_\_** mappings as DXF entities. The *polygon* argument determines the method to convert polygons, use 1 for *Hatch* entity, 2 for *LWPolyline* or 3 for both. Option 2 returns for the exterior path and each hole a separated **LWPolyline** entity. The **Hatch** entity supports holes, but has no explicit borderline. Yields **Hatch** always before **LWPolyline** entities. *MPolygon* support was added in v0.16.6, which is like a *Hatch* entity with additional borderlines, but the MPOLYGON entity is not a core DXF entity and DXF viewers, applications and libraries my not support this entity. The DXF attribute *color* defines the borderline color and *fill\_color* the color of the solid filling. The returned DXF entities can be added to a layout by the **Layout.add\_entity()** method. - **Parameters** - • **polygon** – see *PolygonConversion* - • **dxfattribs** – dict with additional DXF attributes - • **post\_process** – post process function of type **PostProcesFunc** that get the created DXF entity and the geo mapping as input, see reference implementation *assign\_layers()* - **copy() -\> *GeoProxy*** Returns a deep copy. - **\_\_iter\_\_() -\> Iterator\[MutableMapping\[str, Any\]\]** Iterate over all geometry entities. Yields only “Point”, “LineString”, “Polygon”, “MultiPoint”, “MultiLineString” and “MultiPolygon” objects, returns the content of “GeometryCollection”, “FeatureCollection” and “Feature” as geometry objects (“Point”, …). - **wcs\_to\_crs(crs: *Matrix44*) -\> None** Transform all coordinates recursive from *WCS* coordinates into Coordinate Reference System (CRS) by transformation matrix *crs* inplace. The CRS is defined by the *GeoData* entity, get the **GeoData** entity from the modelspace by method *get\_geodata()*. The CRS transformation matrix can be acquired form the **GeoData** object by *get\_crs\_transformation()* method: ``` doc = ezdxf.readfile('file.dxf') msp = doc.modelspace() geodata = msp.get_geodata() if geodata: matrix, axis_ordering = geodata.get_crs_transformation() ``` If *axis\_ordering* is **False** the CRS is not compatible with the **\_\_geo\_interface\_\_** or GeoJSON (see chapter 3.1.1). - **Parameters** **crs** – transformation matrix of type *Matrix44* - **crs\_to\_wcs(crs: *Matrix44*) -\> None** Transform all coordinates recursive from CRS into *WCS* coordinates by transformation matrix *crs* inplace, see also *GeoProxy.wcs\_to\_crs()*. - **Parameters** **crs** – transformation matrix of type *Matrix44* - **globe\_to\_map(func: Callable\[\[*Vec3*\], *Vec3*\] \| None = None) -\> None** Transform all coordinates recursive from globe representation in longitude and latitude in decimal degrees into 2D map representation in meters. Default is WGS84 *EPSG:4326* (GPS) to WGS84 *EPSG:3395* World Mercator function *wgs84\_4326\_to\_3395()*. Use the *pyproj* package to write a custom projection function as needed. - **Parameters** **func** – custom transformation function, which takes one **Vec3** object as argument and returns the result as a **Vec3** object. - **map\_to\_globe(func: Callable\[\[*Vec3*\], *Vec3*\] \| None = None) -\> None** Transform all coordinates recursive from 2D map representation in meters into globe representation as longitude and latitude in decimal degrees. Default is WGS84 *EPSG:3395* World Mercator to WGS84 *EPSG:4326* GPS function *wgs84\_3395\_to\_4326()*. Use the *pyproj* package to write a custom projection function as needed. - **Parameters** **func** – custom transformation function, which takes one **Vec3** object as argument and returns the result as a **Vec3** object. - **apply(func: Callable\[\[*Vec3*\], *Vec3*\]) -\> None** Apply the transformation function *func* recursive to all coordinates. - **Parameters** **func** – transformation function as Callable\[\[Vec3\], Vec3\] - **filter(func: Callable\[\[*GeoProxy*\], bool\]) -\> None** Removes all mappings for which *func()* returns **False**. The function only has to handle Point, LineString and Polygon entities, other entities like MultiPolygon are divided into separate entities also any collection. ### Helper Functions - **ezdxf.addons.geo.wgs84\_4326\_to\_3395(location: *Vec3*) -\> *Vec3*** Transform WGS84 *EPSG:4326* location given as latitude and longitude in decimal degrees as used by GPS into World Mercator cartesian 2D coordinates in meters *EPSG:3395*. - **Parameters** **location** – **Vec3** object, x-attribute represents the longitude value (East-West) in decimal degrees and the y-attribute represents the latitude value (North-South) in decimal degrees. - **ezdxf.addons.geo.wgs84\_3395\_to\_4326(location: *Vec3*, tol: float = 1e-6) -\> *Vec3*** Transform WGS84 World Mercator *EPSG:3395* location given as cartesian 2D coordinates x, y in meters into WGS84 decimal degrees as longitude and latitude *EPSG:4326* as used by GPS. - **Parameters** - • **location** – **Vec3** object, z-axis is ignored - • **tol** – accuracy for latitude calculation - **ezdxf.addons.geo.dms2dd(d: float, m: float = 0, s: float = 0) -\> float** Convert degree, minutes, seconds into decimal degrees. - **ezdxf.addons.geo.dd2dms(dd: float) -\> tuple\[float, float, float\]** Convert decimal degrees into degree, minutes, seconds. - **ezdxf.addons.geo.assign\_layers(entity: DXFGraphic, mapping: MutableMapping\[str, Any\]) -\> None** Reference implementation for a **post\_process()** function. **SEE ALSO:** *dxf\_entities()* ``` def assign_layers(entity: DXFGraphic, mapping: GeoMapping) -> None: properties = mapping.get("properties) if properties is None: return layer = properties.get("layer") if layer: entity.dxf.layer = layer ``` ### Types - **class ezdxf.addons.geo.PolygonConversion(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Polygon conversion types as **IntEnum**. - **HATCH** - **POLYLINE** - **HATCH\_AND\_POLYLINE** - **MPOLYGON** - **ezdxf.addons.geo.GeoMapping** alias of **MutableMapping**\[**str**, **Any**\] - **ezdxf.addons.geo.PostProcessFunc** alias of **Callable**\[\[**DXFGraphic**, **MutableMapping**\[**str**, **Any**\]\], **None**\] ### Importer **NOTE:** This module exists for compatibility reasons only and is superseded by the newer and more robust core module *ezdxf.xref*. For information on how to use it, see the *Importing Data and Resources* section. **This add-on is no longer maintained and will not receive updates or bug fixes.** This add-on is meant to import graphical entities from another DXF drawing and their required table entries like LAYER, LTYPE or STYLE. Because of complex extensibility of the DXF format and the lack of sufficient documentation, I decided to remove most of the possible source drawing dependencies from imported entities, therefore imported entities may not look the same as the original entities in the source drawing, but at least the geometry should be the same and the DXF file does not break. Removed data which could contain source drawing dependencies: Extension Dictionaries, AppData and XDATA. **WARNING:** DON’T EXPECT PERFECT RESULTS! The *Importer* supports following data import: - • entities which are really safe to import: LINE, POINT, CIRCLE, ARC, TEXT, SOLID, TRACE, 3DFACE, SHAPE, POLYLINE, ATTRIB, ATTDEF, INSERT, ELLIPSE, MTEXT, LWPOLYLINE, SPLINE, HATCH, MESH, XLINE, RAY, DIMENSION, LEADER, VIEWPORT - • table and table entry import is restricted to LAYER, LTYPE, STYLE, DIMSTYLE - • import of BLOCK definitions is supported - • import of paper space layouts is supported Import of DXF objects from the OBJECTS section is not supported. DIMSTYLE override for entities DIMENSION and LEADER is not supported. Example: ``` import ezdxf from ezdxf.addons import Importer sdoc = ezdxf.readfile('original.dxf') tdoc = ezdxf.new() importer = Importer(sdoc, tdoc) # import all entities from source modelspace into modelspace of the target drawing importer.import_modelspace() # import all paperspace layouts from source drawing importer.import_paperspace_layouts() # import all CIRCLE and LINE entities from source modelspace into an arbitrary target layout. # create target layout tblock = tdoc.blocks.new('SOURCE_ENTS') # query source entities ents = sdoc.modelspace().query('CIRCLE LINE') # import source entities into target block importer.import_entities(ents, tblock) # This is ALWAYS the last & required step, without finalizing the target drawing is maybe invalid! # This step imports all additional required table entries and block definitions. importer.finalize() tdoc.saveas('imported.dxf') ``` - **class ezdxf.addons.importer.Importer(source: *Drawing*, target: *Drawing*)** The *Importer* class is central element for importing data from other DXF documents. - **Parameters** - • **source** – source **Drawing** - • **target** – target **Drawing** - **source** source DXF document - **target** target DXF document - **used\_layers** Set of used layer names as string, AutoCAD accepts layer names without a LAYER table entry. - **used\_linetypes** Set of used linetype names as string, these linetypes require a TABLE entry or AutoCAD will crash. - **used\_styles** Set of used text style names, these text styles require a TABLE entry or AutoCAD will crash. - **used\_dimstyles** Set of used dimension style names, these dimension styles require a TABLE entry or AutoCAD will crash. - **finalize() -\> None** Finalize the import by importing required table entries and BLOCK definitions, without finalization the target document is maybe invalid for AutoCAD. Call the *finalize()* method as last step of the import process. - **import\_block(block\_name: str, rename=True) -\> str** Import one BLOCK definition from source document. If the BLOCK already exist the BLOCK will be renamed if argument *rename* is **True**, otherwise the existing BLOCK in the target document will be used instead of the BLOCK in the source document. Required name resolving for imported block references (INSERT), will be done in the *Importer.finalize()* method. To replace an existing BLOCK in the target document, just delete it before importing data: **target.blocks.delete\_block(block\_name, safe=False)** - **Parameters** - • **block\_name** – name of BLOCK to import - • **rename** – rename BLOCK if a BLOCK with the same name already exist in target document Returns: (renamed) BLOCK name - **Raises** **ValueError** – BLOCK in source document not found (defined) - **import\_blocks(block\_names: Iterable\[str\], rename=False) -\> None** Import all BLOCK definitions from source document. If a BLOCK already exist the BLOCK will be renamed if argument *rename* is **True**, otherwise the existing BLOCK in the target document will be used instead of the BLOCK from the source document. Required name resolving for imported BLOCK references (INSERT), will be done in the *Importer.finalize()* method. - **Parameters** - • **block\_names** – names of BLOCK definitions to import - • **rename** – rename BLOCK if a BLOCK with the same name already exist in target document - **Raises** **ValueError** – BLOCK in source document not found (defined) - **import\_entities(entities: Iterable\[*DXFEntity*\], target\_layout: *BaseLayout* \| None = None) -\> None** Import all *entities* into *target\_layout* or the modelspace of the target document, if *target\_layout* is **None**. - **Parameters** - • **entities** – Iterable of DXF entities - • **target\_layout** – any layout (modelspace, paperspace or block) from the target document - **Raises** *DXFStructureError* – *target\_layout* is not a layout of target document - **import\_entity(entity: *DXFEntity*, target\_layout: *BaseLayout* \| None = None) -\> None** Imports a single DXF *entity* into *target\_layout* or the modelspace of the target document, if *target\_layout* is **None**. - **Parameters** - • **entity** – DXF entity to import - • **target\_layout** – any layout (modelspace, paperspace or block) from the target document - **Raises** *DXFStructureError* – *target\_layout* is not a layout of target document - **import\_modelspace(target\_layout: *BaseLayout* \| None = None) -\> None** Import all entities from source modelspace into *target\_layout* or the modelspace of the target document, if *target\_layout* is **None**. - **Parameters** **target\_layout** – any layout (modelspace, paperspace or block) from the target document - **Raises** *DXFStructureError* – *target\_layout* is not a layout of target document - **import\_paperspace\_layout(name: str) -\> *Layout*** Import paperspace layout *name* into the target document. Recreates the source paperspace layout in the target document, renames the target paperspace if a paperspace with same *name* already exist and imports all entities from the source paperspace into the target paperspace. - **Parameters** **name** – source paper space name as string Returns: new created target paperspace **Layout** - **Raises** - • **KeyError** – source paperspace does not exist - • *DXFTypeError* – invalid modelspace import - **import\_paperspace\_layouts() -\> None** Import all paperspace layouts and their content into the target document. Target layouts will be renamed if a layout with the same name already exist. Layouts will be imported in original tab order. - **import\_shape\_files(fonts: set\[str\]) -\> None** Import shape file table entries from the source document into the target document. Shape file entries are stored in the styles table but without a name. - **import\_table(name: str, entries: str \| Iterable\[str\] = '\*', replace=False) -\> None** Import specific table entries from the source document into the target document. - **Parameters** - • **name** – valid table names are “layers”, “linetypes” and “styles” - • **entries** – Iterable of table names as strings, or a single table name or “\*” for all table entries - • **replace** – **True** to replace the already existing table entry else ignore existing entries - **Raises** **TypeError** – unsupported table type - **import\_tables(table\_names: str \| Iterable\[str\] = '\*', replace=False) -\> None** Import DXF tables from the source document into the target document. - **Parameters** - • **table\_names** – iterable of tables names as strings, or a single table name as string or “\*” for all supported tables - • **replace** – **True** to replace already existing table entries else ignore existing entries - **Raises** **TypeError** – unsupported table type - **recreate\_source\_layout(name: str) -\> *Layout*** Recreate source paperspace layout *name* in the target document. The layout will be renamed if *name* already exist in the target document. Returns target modelspace for layout name “Model”. - **Parameters** **name** – layout name as string - **Raises** **KeyError** – if source layout *name* not exist ### dxf2code Translate DXF entities and structures into Python source code. Short example: ``` import ezdxf from ezdxf.addons.dxf2code import entities_to_code, block_to_code doc = ezdxf.readfile('original.dxf') msp = doc.modelspace() source = entities_to_code(msp) # create source code for a block definition block_source = block_to_code(doc.blocks['MyBlock']) # merge source code objects source.merge(block_source) with open('source.py', mode='wt') as f: f.write(source.import_str()) f.write('\n\n') f.write(source.code_str()) f.write('\n') ``` - **ezdxf.addons.dxf2code.entities\_to\_code(entities: Iterable\[*DXFEntity*\], layout: str = 'layout', ignore: Iterable\[str\] \| None = None) -\> *Code*** Translates DXF entities into Python source code to recreate this entities by ezdxf. - **Parameters** - • **entities** – iterable of DXFEntity - • **layout** – variable name of the layout (model space or block) as string - • **ignore** – iterable of entities types to ignore as strings like **\['IMAGE', 'DIMENSION'\]** - **Returns** *Code* - **ezdxf.addons.dxf2code.block\_to\_code(block: *BlockLayout*, drawing: str = 'doc', ignore: Iterable\[str\] \| None = None) -\> *Code*** Translates a BLOCK into Python source code to recreate the BLOCK by ezdxf. - **Parameters** - • **block** – block definition layout - • **drawing** – variable name of the drawing as string - • **ignore** – iterable of entities types to ignore as strings like \[‘IMAGE’, ‘DIMENSION’\] - **Returns** *Code* - **ezdxf.addons.dxf2code.table\_entries\_to\_code(entities: Iterable\[*DXFEntity*\], drawing='doc') -\> *Code*** - **ezdxf.addons.dxf2code.black(code: str, line\_length=88, fast: bool = True) -\> str** Returns the source *code* as a single string formatted by *Black* Requires the installed *Black* formatter: ``` pip3 install black ``` - **Parameters** - • **code** – source code - • **line\_length** – max. source code line length - • **fast** – **True** for fast mode, **False** to check that the reformatted code is valid - **Raises** **ImportError** – Black is not available - **class ezdxf.addons.dxf2code.Code** Source code container. - **code** Source code line storage, store lines without line ending **\\\\n** - **imports** source code line storage for global imports, store lines without line ending **\\\\n** - **layers** Layers used by the generated source code, AutoCAD accepts layer names without a LAYER table entry. - **linetypes** Linetypes used by the generated source code, these linetypes require a TABLE entry or AutoCAD will crash. - **styles** Text styles used by the generated source code, these text styles require a TABLE entry or AutoCAD will crash. - **dimstyles** Dimension styles used by the generated source code, these dimension styles require a TABLE entry or AutoCAD will crash. - **blocks** Blocks used by the generated source code, these blocks require a BLOCK definition in the BLOCKS section or AutoCAD will crash. - **code\_str(indent: int = 0) -\> str** Returns the source code as a single string. - **Parameters** **indent** – source code indentation count by spaces - **black\_code\_str(line\_length=88) -\> str** Returns the source code as a single string formatted by *Black* - **Parameters** **line\_length** – max. source code line length - **Raises** **ImportError** – Black is not available - **import\_str(indent: int = 0) -\> str** Returns required imports as a single string. - **Parameters** **indent** – source code indentation count by spaces - **merge(code: *Code*, indent: int = 0) -\> None** Add another *Code* object. - **add\_import(statement: str) -\> None** Add import statement, identical import statements are merged together. - **add\_line(code: str, indent: int = 0) -\> None** Add a single source code line without line ending **\\n**. - **add\_lines(code: Iterable\[str\], indent: int = 0) -\> None** Add multiple source code lines without line ending **\\n**. ### iterdxf This add-on allows iterating over entities of the modelspace of really big (\> 5GB) DXF files which do not fit into memory by only loading one entity at the time. Only ASCII DXF files are supported. The entities are regular *DXFGraphic* objects with access to all supported DXF attributes, this entities can be written to new DXF files created by the *IterDXF.export()* method. The new *add\_foreign\_entity()* method allows also to add this entities to new regular *ezdxf* drawings (except for the INSERT entity), but resources like linetype and style are removed, only layer will be preserved but only with default attributes like color **7** and linetype **CONTINUOUS**. The following example shows how to split a big DXF files into several separated DXF files which contains only LINE, TEXT or POLYLINE entities. ``` from ezdxf.addons import iterdxf doc = iterdxf.opendxf('big.dxf') line_exporter = doc.export('line.dxf') text_exporter = doc.export('text.dxf') polyline_exporter = doc.export('polyline.dxf') try: for entity in doc.modelspace(): if entity.dxftype() == 'LINE': line_exporter.write(entity) elif entity.dxftype() == 'TEXT': text_exporter.write(entity) elif entity.dxftype() == 'POLYLINE': polyline_exporter.write(entity) finally: line_exporter.close() text_exporter.close() polyline_exporter.close() doc.close() ``` Supported DXF types: 3DFACE, ARC, ATTDEF, ATTRIB, CIRCLE, DIMENSION, ELLIPSE, HATCH, HELIX, IMAGE, INSERT, LEADER, LINE, LWPOLYLINE, MESH, MLEADER, MLINE, MTEXT, POINT, POLYLINE, RAY, SHAPE, SOLID, SPLINE, TEXT, TRACE, VERTEX, WIPEOUT, XLINE Transfer simple entities to another DXF document, this works for some supported entities, except for entities with strong dependencies to the original document like INSERT look at *add\_foreign\_entity()* for all supported types: ``` newdoc = ezdxf.new() msp = newdoc.modelspace() # line is an entity from a big source file msp.add_foreign_entity(line) # and so on ... msp.add_foreign_entity(lwpolyline) msp.add_foreign_entity(mesh) msp.add_foreign_entity(polyface) ``` Transfer MESH and POLYFACE (dxftype for POLYFACE and POLYMESH is POLYLINE!) entities into a new DXF document by the **MeshTransformer** class: ``` from ezdxf.render import MeshTransformer # mesh is MESH from a big source file t = MeshTransformer.from_mesh(mesh) # create a new MESH entity from MeshTransformer t.render(msp) # polyface is POLYFACE from a big source file t = MeshTransformer.from_polyface(polyface) # create a new POLYMESH entity from MeshTransformer t.render_polyface(msp) ``` Another way to import entities from a big source file into new DXF documents is to split the big file into smaller parts and use the *Importer* add-on for a more safe entity import. - **ezdxf.addons.iterdxf.opendxf(filename: Path \| str, errors: str = 'surrogateescape') -\> *IterDXF*** Open DXF file for iterating, be sure to open valid DXF files, no DXF structure checks will be applied. Use this function to split up big DXF files as shown in the example above. - **Parameters** - • **filename** – DXF filename of a seekable DXF file. - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • *DXFStructureError* – invalid or incomplete DXF file - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs - **ezdxf.addons.iterdxf.modelspace(filename: Path \| str, types: Iterable\[str\] \| None = None, errors: str = 'surrogateescape') -\> Iterable\[DXFGraphic\]** Iterate over all modelspace entities as **DXFGraphic** objects of a seekable file. Use this function to iterate “quick” over modelspace entities of a DXF file, filtering DXF types may speed up things if many entity types will be skipped. - **Parameters** - • **filename** – filename of a seekable DXF file - • **types** – DXF types like **\['LINE', '3DFACE'\]** which should be returned, **None** returns all supported types. - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • *DXFStructureError* – invalid or incomplete DXF file - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs - **ezdxf.addons.iterdxf.single\_pass\_modelspace(stream: BinaryIO, types: Iterable\[str\] \| None = None, errors: str = 'surrogateescape') -\> Iterable\[DXFGraphic\]** Iterate over all modelspace entities as **DXFGraphic** objects in a single pass. Use this function to ‘quick’ iterate over modelspace entities of a **not** seekable binary DXF stream, filtering DXF types may speed up things if many entity types will be skipped. - **Parameters** - • **stream** – (not seekable) binary DXF stream - • **types** – DXF types like **\['LINE', '3DFACE'\]** which should be returned, **None** returns all supported types. - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • *DXFStructureError* – Invalid or incomplete DXF file - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs - **class ezdxf.addons.iterdxf.IterDXF** - **export(name: Path \| str) -\> *IterDXFWriter*** Returns a companion object to export parts from the source DXF file into another DXF file, the new file will have the same HEADER, CLASSES, TABLES, BLOCKS and OBJECTS sections, which guarantees all necessary dependencies are present in the new file. - **Parameters** **name** – filename, no special requirements - **modelspace(types: Iterable\[str\] \| None = None) -\> Iterable\[DXFGraphic\]** Returns an iterator for all supported DXF entities in the modelspace. These entities are regular *DXFGraphic* objects but without a valid document assigned. It is **not** possible to add these entities to other *ezdxf* documents. It is only possible to recreate the objects by factory functions base on attributes of the source entity. For MESH, POLYMESH and POLYFACE it is possible to use the *MeshTransformer* class to render (recreate) this objects as new entities in another document. - **Parameters** **types** – DXF types like **\['LINE', '3DFACE'\]** which should be returned, **None** returns all supported types. - **close()** Safe closing source DXF file. - **class ezdxf.addons.iterdxf.IterDXFWriter** - **write(entity: DXFGraphic)** Write a DXF entity from the source DXF file to the export file. Don’t write entities from different documents than the source DXF file, dependencies and resources will not match, maybe it will work once, but not in a reliable way for different DXF documents. - **close()** Safe closing of exported DXF file. Copying of OBJECTS section happens only at closing the file, without closing the new DXF file is invalid. ### ODA File Converter Support Use an installed *ODA File Converter* for converting between different versions of *.dwg*, *.dxb* and *.dxf*. **WARNING:** Execution of an external application is a big security issue! Especially when the path to the executable can be altered. To avoid this problem delete the **ezdxf.addons.odafc.py** module. ### Install ODA File Converter The *ODA File Converter* has to be installed by the user, the application is available for Windows XP, Windows 7 or later, Mac OS X, and Linux in 32/64-bit RPM and DEB format. ### AppImage Support The option “unix\_exec\_path” defines an executable for Linux and macOS, this executable overrides the default command **ODAFileConverter**. Assign an **absolute** path to the executable to that key and if the executable is not found the add-on falls back to the **ODAFileConverter** command. The option “unix\_exec\_path” also adds support for AppImages provided by the Open Design Alliance. Download the AppImage file and store it in a folder of your choice (e.g. **~/Apps**) and make the file executable: ``` chmod a+x ~/Apps/ODAFileConverter_QT5_lnxX64_8.3dll_23.9.AppImage ``` Add the **absolute** path as config option “unix\_exec\_path” to the “odafc-addon” section: ``` [odafc-addon] win_exec_path = "C:\Program Files\ODA\ODAFileConverter\ODAFileConverter.exe" unix_exec_path = "/home//Apps/ODAFileConverter_QT5_lnxX64_8.3dll_23.9.AppImage" ``` This overrides the default command **ODAFileConverter** and if the executable is not found the add-on falls back to the **ODAFileConverter** command. **SEE ALSO:** For more information about config files see section: *Global Options Object* ### Suppressed GUI On Windows the GUI of the ODA File Converter is suppressed, on Linux you may have to install the **xvfb** package to prevent this, for macOS is no solution known. ### Supported DXF and DWG Versions ODA File Converter version strings, you can use any of this strings to specify a version, **'R..'** and **'AC....'** strings will be automatically mapped to **'ACAD....'** strings: | | | | | --- | --- | --- | | ODAFC | ezdxf | Version | | ACAD9 | not supported | AC1004 | | ACAD10 | not supported | AC1006 | | ACAD12 | R12 | AC1009 | | ACAD13 | R13 | AC1012 | | ACAD14 | R14 | AC1014 | | ACAD2000 | R2000 | AC1015 | | ACAD2004 | R2004 | AC1018 | | ACAD2007 | R2007 | AC1021 | | ACAD2010 | R2010 | AC1024 | | ACAD2013 | R2013 | AC1027 | | ACAD2018 | R2018 | AC1032 | ### Config On Windows the path to the **ODAFileConverter.exe** executable is stored in the config file (see *ezdxf.options*) in the “odafc-addon” section as key “win\_exec\_path”, the default entry is: ``` [odafc-addon] win_exec_path = "C:\Program Files\ODA\ODAFileConverter\ODAFileConverter.exe" unix_exec_path = ``` On Linux and macOS the **ODAFileConverter** command is located by the **shutil.which()** function but can be overridden since version 1.0 by the key “linux\_exec\_path”. ### Usage ``` from ezdxf.addons import odafc # Load a DWG file doc = odafc.readfile('my.dwg') # Use loaded document like any other ezdxf document print(f'Document loaded as DXF version: {doc.dxfversion}.') msp = doc.modelspace() ... # Export document as DWG file for AutoCAD R2018 odafc.export_dwg(doc, 'my_R2018.dwg', version='R2018') ``` - **ezdxf.addons.odafc.win\_exec\_path** Path to installed *ODA File Converter* executable on Windows systems, default is **"C:\\Program Files\\ODA\\ODAFileConverter\\ODAFileConverter.exe"**. - **ezdxf.addons.odafc.unix\_exec\_path** Absolute path to a Linux or macOS executable if set, otherwise an empty string and the default command **ODAFileConverter** is used. - **ezdxf.addons.odafc.is\_installed() -\> bool** Returns **True** if the ODAFileConverter is installed. - **ezdxf.addons.odafc.readfile(filename: str \| PathLike, version: str \| None = None, \*, audit: bool = False) -\> *Drawing*** Uses an installed *ODA File Converter* to convert a DWG/DXB/DXF file into a temporary DXF file and load this file by *ezdxf*. - **Parameters** - • **filename** – file to load by ODA File Converter - • **version** – load file as specific DXF version, by default the same version as the source file or if not detectable the latest by *ezdxf* supported version. - • **audit** – audit source file before loading - **Raises** - • **FileNotFoundError** – source file not found - • **odafc.UnknownODAFCError** – conversion failed for unknown reasons - • **odafc.UnsupportedVersion** – invalid DWG version specified - • **odafc.UnsupportedFileFormat** – unsupported file extension - • **odafc.ODAFCNotInstalledError** – ODA File Converter not installed - **ezdxf.addons.odafc.export\_dwg(doc: *Drawing*, filename: str \| PathLike, version: str \| None = None, \*, audit: bool = False, replace: bool = False) -\> None** Uses an installed *ODA File Converter* to export the DXF document *doc* as a DWG file. A temporary DXF file will be created and converted to DWG by the ODA File Converter. If *version* is not specified the DXF version of the source document is used. - **Parameters** - • **doc** – *ezdxf* DXF document as **Drawing** object - • **filename** – output DWG filename, the extension will be set to “.dwg” - • **version** – DWG version to export, by default the same version as the source document. - • **audit** – audit source file by ODA File Converter at exporting - • **replace** – replace existing DWG file if **True** - **Raises** - • **FileExistsError** – target file already exists, and argument *replace* is\ **False** - • **FileNotFoundError** – parent directory of target file does not exist - • **odafc.UnknownODAFCError** – exporting DWG failed for unknown reasons - • **odafc.ODAFCNotInstalledError** – ODA File Converter not installed - **ezdxf.addons.odafc.convert(source: str \| PathLike, dest: str \| PathLike = '', \*, version='R2018', audit=True, replace=False)** Convert *source* file to *dest* file. The file extension defines the target format e.g. **convert("test.dxf", "Test.dwg")** converts the source file to a DWG file. If *dest* is an empty string the conversion depends on the source file format and is DXF to DWG or DWG to DXF. To convert DXF to DXF an explicit destination filename is required: **convert("r12.dxf", "r2013.dxf", version="R2013")** - **Parameters** - • **source** – source file - • **dest** – destination file, an empty string uses the source filename with the extension of the target format e.g. “test.dxf” -\> “test.dwg” - • **version** – output DXF/DWG version e.g. “ACAD2018”, “R2018”, “AC1032” - • **audit** – audit files - • **replace** – replace existing destination file - **Raises** - • **FileNotFoundError** – source file or destination folder does not exist - • **FileExistsError** – destination file already exists and argument *replace*\ is **False** - • **odafc.UnsupportedVersion** – invalid DXF version specified - • **odafc.UnsupportedFileFormat** – unsupported file extension - • **odafc.UnknownODAFCError** – conversion failed for unknown reasons - • **odafc.ODAFCNotInstalledError** – ODA File Converter not installed ### R12 Export Added in version 1.1. This module exports any DXF file as a simple DXF R12 file. Many complex entities will be converted into DXF primitives. This exporter is intended for creating a simple file format as an input format for other software such as laser cutters. In order to get a file that can be edited well in a CAD application, the results of the ODA file converter are much better. ### Usage ``` import ezdxf from ezdxf.addons import r12export doc = ezdxf.readfile("any.dxf") r12export.saveas(doc, "r12.dxf") ``` ### Converted Entity Types | | | | --- | --- | | LWPOLYLINE | translated to POLYLINE | | MESH | translated to POLYLINE (PolyfaceMesh) | | SPLINE | flattened to POLYLINE | | ELLIPSE | flattened to POLYLINE | | MTEXT | exploded into DXF primitives | | LEADER | exploded into DXF primitives | | MLEADER | exploded into DXF primitives | | MULTILEADER | exploded into DXF primitives | | MLINE | exploded into DXF primitives | | HATCH | exploded into DXF primitives | | MPOLYGON | exploded into DXF primitives | | ACAD\_TABLE | export of pre-rendered BLOCK content | For proxy- or unknown entities the available proxy graphic will be exported as DXF primitives. ### Limitations - • Explosion of MTEXT into DXF primitives is not perfect - • Pattern rendering for complex HATCH entities has issues - • Solid fill rendering for complex HATCH entities has issues ### ODA File Converter The advantage of the *r12export* module is that the ODA file converter isn’t needed, but the ODA file converter will produce a much better result: ``` from ezdxf.addons import odafc odafc.convert("any.dxf", "r12.dxf", version="R12") ``` ### Functions | | | | --- | --- | | *write* | Write a DXF document as DXF version R12 to a text stream. | | *saveas* | Write a DXF document as DXF version R12 to a file. | | *convert* | Export and reload DXF document as DXF version R12. | - **ezdxf.addons.r12export.write(doc: *Drawing*, stream: TextIO, \*, max\_sagitta: float = MAX\_SAGITTA) -\> None** Write a DXF document as DXF version R12 to a text stream. The *max\_sagitta* argument determines the accuracy of the curve flatting for SPLINE and ELLIPSE entities. - **Parameters** - • **doc** – DXF document to export - • **stream** – output stream, use **doc.encoding** as encoding - • **max\_sagitta** – maximum distance from the center of the curve to the center of the line segment between two approximation points to determine if a segment should be subdivided. - **ezdxf.addons.r12export.saveas(doc: *Drawing*, filepath: str \| PathLike, \*, max\_sagitta: float = MAX\_SAGITTA) -\> None** Write a DXF document as DXF version R12 to a file. The *max\_sagitta* argument determines the accuracy of the curve flatting for SPLINE and ELLIPSE entities. - **Parameters** - • **doc** – DXF document to export - • **filepath** – output filename - • **max\_sagitta** – maximum distance from the center of the curve to the center of the line segment between two approximation points to determine if a segment should be subdivided. - **ezdxf.addons.r12export.convert(doc: *Drawing*, \*, max\_sagitta: float = MAX\_SAGITTA) -\> *Drawing*** Export and reload DXF document as DXF version R12. Writes the DXF document into a temporary file at the file-system and reloads this file by the *ezdxf.readfile()* function. ### r12writer The fast file/stream writer creates simple DXF R12 drawings with just an ENTITIES section. The HEADER, TABLES and BLOCKS sections are not present except FIXED-TABLES are written. Only LINE, CIRCLE, ARC, TEXT, POINT, SOLID, 3DFACE and POLYLINE entities are supported. FIXED-TABLES is a predefined TABLES section, which will be written, if the init argument *fixed\_tables* of *R12FastStreamWriter* is **True**. The *R12FastStreamWriter* writes the DXF entities as strings direct to the stream without creating an in-memory drawing and therefore the processing is very fast. Because of the lack of a BLOCKS section, BLOCK/INSERT can not be used. Layers can be used, but this layers have a default setting color = **7** (black/white) and linetype = **'Continuous'**. If writing the FIXED-TABLES, some predefined text styles and line types are available, else text style is always **'STANDARD'** and line type is always **'ByLayer'**. If using FIXED-TABLES, following predefined line types are available: - • CONTINUOUS - • CENTER **\_\_\_\_ \_ \_\_\_\_ \_ \_\_\_\_ \_ \_\_\_\_ \_ \_\_\_\_ \_ \_\_\_\_** - • CENTERX2 **\_\_\_\_\_\_\_\_ \_\_ \_\_\_\_\_\_\_\_ \_\_ \_\_\_\_\_\_\_\_** - • CENTER2 **\_\_\_\_ \_ \_\_\_\_ \_ \_\_\_\_ \_ \_\_\_\_ \_ \_\_\_\_** - • DASHED **\_\_ \_\_ \_\_ \_\_ \_\_ \_\_ \_\_ \_\_ \_\_ \_\_ \_\_ \_\_ \_\_ \_** - • DASHEDX2 **\_\_\_\_ \_\_\_\_ \_\_\_\_ \_\_\_\_ \_\_\_\_ \_\_\_\_** - • DASHED2 **\_ \_ \_ \_ \_ \_ \_ \_ \_ \_ \_ \_ \_ \_** - • PHANTOM **\_\_\_\_\_\_ \_\_ \_\_ \_\_\_\_\_\_ \_\_ \_\_ \_\_\_\_\_\_** - • PHANTOMX2 **\_\_\_\_\_\_\_\_\_\_\_\_ \_\_\_\_ \_\_\_\_ \_\_\_\_\_\_\_\_\_\_\_\_** - • PHANTOM2 **\_\_\_ \_ \_ \_\_\_ \_ \_ \_\_\_ \_ \_ \_\_\_ \_ \_ \_\_\_** - • DASHDOT **\_\_ . \_\_ . \_\_ . \_\_ . \_\_ . \_\_ . \_\_ . \_\_** - • DASHDOTX2 **\_\_\_\_ . \_\_\_\_ . \_\_\_\_ . \_\_\_\_** - • DASHDOT2 **\_ . \_ . \_ . \_ . \_ . \_ . \_ . \_** - • DOT **. . . . . . . . . . . . . . . .** - • DOTX2 **. . . . . . . .** - • DOT2 **. . . . . . . . . . . . . . . . . . .** - • DIVIDE **\_\_ . . \_\_ . . \_\_ . . \_\_ . . \_\_ . . \_\_** - • DIVIDEX2 **\_\_\_\_ . . \_\_\_\_ . . \_\_\_\_ . . \_\_\_\_** - • DIVIDE2 **\_ . \_ . \_ . \_ . \_ . \_ . \_ . \_** If using FIXED-TABLES, following predefined text styles are available: - • OpenSans - • OpenSansCondensed-Light ### Tutorial A simple example with different DXF entities: ``` from random import random from ezdxf.addons import r12writer with r12writer("quick_and_dirty_dxf_r12.dxf") as dxf: dxf.add_line((0, 0), (17, 23)) dxf.add_circle((0, 0), radius=2) dxf.add_arc((0, 0), radius=3, start=0, end=175) dxf.add_solid([(0, 0), (1, 0), (0, 1), (1, 1)]) dxf.add_point((1.5, 1.5)) # 2d polyline, new in v0.12 dxf.add_polyline_2d([(5, 5), (7, 3), (7, 6)]) # 2d polyline with bulge value, new in v0.12 dxf.add_polyline_2d([(5, 5), (7, 3, 0.5), (7, 6)], format='xyb') # 3d polyline only, changed in v0.12 dxf.add_polyline([(4, 3, 2), (8, 5, 0), (2, 4, 9)]) dxf.add_text("test the text entity", align="MIDDLE_CENTER") ``` A simple example of writing really many entities in a short time: ``` from random import random from ezdxf.addons import r12writer MAX_X_COORD = 1000.0 MAX_Y_COORD = 1000.0 CIRCLE_COUNT = 1000000 with r12writer("many_circles.dxf") as dxf: for i in range(CIRCLE_COUNT): dxf.add_circle((MAX_X_COORD*random(), MAX_Y_COORD*random()), radius=2) ``` Show all available line types: ``` import ezdxf LINETYPES = [ 'CONTINUOUS', 'CENTER', 'CENTERX2', 'CENTER2', 'DASHED', 'DASHEDX2', 'DASHED2', 'PHANTOM', 'PHANTOMX2', 'PHANTOM2', 'DASHDOT', 'DASHDOTX2', 'DASHDOT2', 'DOT', 'DOTX2', 'DOT2', 'DIVIDE', 'DIVIDEX2', 'DIVIDE2', ] with r12writer('r12_linetypes.dxf', fixed_tables=True) as dxf: for n, ltype in enumerate(LINETYPES): dxf.add_line((0, n), (10, n), linetype=ltype) dxf.add_text(ltype, (0, n+0.1), height=0.25, style='OpenSansCondensed-Light') ``` ### Reference - **ezdxf.addons.r12writer.r12writer(stream: TextIO \| BinaryIO \| str, fixed\_tables=False, fmt='asc') -\> *R12FastStreamWriter*** Context manager for writing DXF entities to a stream/file. *stream* can be any file like object with a **write()** method or just a string for writing DXF entities to the file system. If *fixed\_tables* is **True**, a standard TABLES section is written in front of the ENTITIES section and some predefined text styles and line types can be used. Set argument *fmt* to “asc” to write ASCII DXF file (default) or “bin” to write Binary DXF files. ASCII DXF require a **TextIO** stream and Binary DXF require a **BinaryIO** stream. - **class ezdxf.addons.r12writer.R12FastStreamWriter(stream: TextIO, fixed\_tables=False)** Fast stream writer to create simple DXF R12 drawings. - **Parameters** - • **stream** – a file like object with a **write()** method. - • **fixed\_tables** – if *fixed\_tables* is **True**, a standard TABLES section is written in front of the ENTITIES section and some predefined text styles and line types can be used. - **close() -\> None** Writes the DXF tail. Call is not necessary when using the context manager *r12writer()*. - **add\_line(start: Sequence\[float\], end: Sequence\[float\], layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a LINE entity from *start* to *end*. - **Parameters** - • **start** – start vertex as **(x, y\[, z\])** tuple - • **end** – end vertex as as **(x, y\[, z\])** tuple - • **layer** – layer name as string, without a layer definition the assigned color = **7** (black/white) and line type is **'Continuous'**. - • **color** – color as *AutoCAD Color Index (ACI)* in the range from **0** to **256**, **0** is *ByBlock* and **256** is *ByLayer*, default is *ByLayer* which is always color = **7** (black/white) without a layer definition. - • **linetype** – line type as string, if FIXED-TABLES are written some predefined line types are available, else line type is always *ByLayer*, which is always **'Continuous'** without a LAYERS table. - **add\_circle(center: Sequence\[float\], radius: float, layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a CIRCLE entity. - **Parameters** - • **center** – circle center point as **(x, y)** tuple - • **radius** – circle radius as float - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_arc(center: Sequence\[float\], radius: float, start: float = 0, end: float = 360, layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add an ARC entity. The arc goes counter-clockwise from *start* angle to *end* angle. - **Parameters** - • **center** – arc center point as **(x, y)** tuple - • **radius** – arc radius as float - • **start** – arc start angle in degrees as float - • **end** – arc end angle in degrees as float - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_point(location: Sequence\[float\], layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a POINT entity. - **Parameters** - • **location** – point location as **(x, y \[,z\])** tuple - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_3dface(vertices: Iterable\[Sequence\[float\]\], invisible: int = 0, layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a 3DFACE entity. 3DFACE is a spatial area with 3 or 4 vertices, all vertices have to be in the same plane. - **Parameters** - • **vertices** – iterable of 3 or 4 **(x, y, z)** vertices. - • **invisible** – bit coded flag to define the invisible edges, - 1\. edge = 1 - 2\. edge = 2 - 3\. edge = 4 - 4\. edge = 8 Add edge values to set multiple edges invisible, 1. edge + 3. edge = 1 + 4 = 5, all edges = 15 - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_solid(vertices: Iterable\[Sequence\[float\]\], layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a SOLID entity. SOLID is a solid filled area with 3 or 4 edges and SOLID is a 2D entity. - **Parameters** - • **vertices** – iterable of 3 or 4 **(x, y\[, z\])** tuples, z-axis will be ignored. - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_polyline\_2d(points: Iterable\[Sequence\], format: str = 'xy', closed: bool = False, start\_width: float = 0, end\_width: float = 0, layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a 2D POLYLINE entity with start width, end width and bulge value support. Format codes: | | | | --- | --- | | x | x-coordinate | | y | y-coordinate | | s | start width | | e | end width | | b | bulge value | | v | (x, y) tuple (z-axis is ignored) | - **Parameters** - • **points** – iterable of (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuple, value order according to the *format* string, unset values default to **0** - • **format** – format: format string, default is **'xy'** - • **closed** – **True** creates a closed polyline - • **start\_width** – default start width, default is **0** - • **end\_width** – default end width, default is **0** - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_polyline(vertices: Iterable\[Sequence\[float\]\], closed: bool = False, layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a 3D POLYLINE entity. - **Parameters** - • **vertices** – iterable of **(x, y\[, z\])** tuples, z-axis is **0** by default - • **closed** – **True** creates a closed polyline - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_polyface(vertices: Iterable\[Sequence\[float\]\], faces: Iterable\[Sequence\[int\]\], layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a POLYFACE entity. The POLYFACE entity supports only faces of maximum 4 vertices, more indices will be ignored. A simple square would be: ``` v0 = (0, 0, 0) v1 = (1, 0, 0) v2 = (1, 1, 0) v3 = (0, 1, 0) dxf.add_polyface(vertices=[v0, v1, v2, v3], faces=[(0, 1, 2, 3)]) ``` All 3D form functions of the *ezdxf.render.forms* module return *MeshBuilder* objects, which provide the required vertex and face lists. See sphere example: *https://github.com/mozman/ezdxf/blob/master/examples/r12writer.py* - **Parameters** - • **vertices** – iterable of **(x, y, z)** tuples - • **faces** – iterable of 3 or 4 vertex indices, indices have to be 0-based - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_polymesh(vertices: Iterable\[Sequence\[float\]\], size: tuple\[int, int\], closed=(False, False), layer: str = '0', color: int \| None = None, linetype: str \| None = None) -\> None** Add a POLYMESH entity. A POLYMESH is a mesh of m rows and n columns, each mesh vertex has its own x-, y- and z coordinates. The mesh can be closed in m- and/or n-direction. The vertices have to be in column order: (m0, n0), (m0, n1), (m0, n2), (m1, n0), (m1, n1), (m1, n2), … See example: *https://github.com/mozman/ezdxf/blob/master/examples/r12writer.py* - **Parameters** - • **vertices** – iterable of **(x, y, z)** tuples, in column order - • **size** – mesh dimension as (m, n)-tuple, requirement: **len(vertices) == m\*n** - • **closed** – (m\_closed, n\_closed) tuple, for closed mesh in m and/or n direction - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* - • **linetype** – line type as string see *add\_line()* - **add\_text(text: str, insert: Sequence\[float\] = (0, 0), height: float = 1.0, width: float = 1.0, align: str = 'LEFT', rotation: float = 0.0, oblique: float = 0.0, style: str = 'STANDARD', layer: str = '0', color: int \| None = None) -\> None** Add a one line TEXT entity. - **Parameters** - • **text** – the text as string - • **insert** – insert location as **(x, y)** tuple - • **height** – text height in drawing units - • **width** – text width as factor - • **align** – text alignment, see table below - • **rotation** – text rotation in degrees as float - • **oblique** – oblique in degrees as float, vertical = **0** (default) - • **style** – text style name as string, if FIXED-TABLES are written some predefined text styles are available, else text style is always **'STANDARD'**. - • **layer** – layer name as string see *add\_line()* - • **color** – color as *AutoCAD Color Index (ACI)* see *add\_line()* | | | | | | --- | --- | --- | --- | | Vert/Horiz | Left | Center | Right | | Top | **TOP\_LEFT** | **TOP\_CENTER** | **TOP\_RIGHT** | | Middle | **MIDDLE\_LEFT** | **MIDDLE\_CENTER** | **MIDDLE\_RIGHT** | | Bottom | **BOTTOM\_LEFT** | **BOTTOM\_CENTER** | **BOTTOM\_RIGHT** | | Baseline | **LEFT** | **CENTER** | **RIGHT** | The special alignments **ALIGNED** and **FIT** are not available. ### text2path Tools to convert text strings and text based DXF entities into outer- and inner linear paths as *Path* objects. At the moment only the TEXT and the ATTRIB entity can be converted into paths and hatches. Added in version 1.1: Text rendering is done by the *fontTools* package, which is a hard dependency of *ezdxf*. Support for stroke fonts, these are the basic vector fonts included in CAD applications, like .shx, .shp or .lff fonts was added but these fonts cannot be rendered as HATCH entities. The required font files are not included with *ezdxf* as they are copyrighted or, in the case of the LibreCAD font format, licensed under the “GPL v2 and later”. Set the paths to such stroke fonts in the config file, see option *ezdxf.options.support\_dirs*: ``` [core] support_dirs = "C:\Program Files\Bricsys\BricsCAD V23 en_US\Fonts", ~/shx_fonts, ~/shp_fonts, ~/lff_fonts, ``` Don’t expect a 100% match compared to CAD applications but the results with *fontTools* are better than the previous *Matplotlib* renderings. ### Text Alignments The text alignments are enums of type *ezdxf.enums.TextEntityAlignment* | | | | | | --- | --- | --- | --- | | Vertical | Left | Center | Right | | Top | TOP\_LEFT | TOP\_CENTER | TOP\_RIGHT | | Middle | MIDDLE\_LEFT | MIDDLE\_CENTER | MIDDLE\_RIGHT | | Bottom | BOTTOM\_LEFT | BOTTOM\_CENTER | BOTTOM\_RIGHT | | Baseline | LEFT | CENTER | RIGHT | The vertical middle alignments (MIDDLE\_XXX), center the text vertically in the middle of the uppercase letter “X” (cap height). Special alignments, where the horizontal alignment is always in the center of the text: - • ALIGNED: text is scaled to match the given *length*, scales x- and y-direction by the same factor. - • FIT: text is scaled to match the given *length*, but scales only in x-direction. - • MIDDLE: insertion point is the center of the total height (cap height + descender height) without scaling, the *length* argument is ignored. ### Font Face Definition A font face is defined by the Matplotlib compatible **FontFace** object by **font-family**, **font-style**, **font-stretch** and **font-weight**. **SEE ALSO:** - • *Font Anatomy* - • *Font Properties* ### String Functions - **ezdxf.addons.text2path.make\_path\_from\_str(s: str, font: *FontFace*, size: float = 1.0, align=TextEntityAlignment.LEFT, length: float = 0, m: *Matrix44* = None) -\> Path** Convert a single line string *s* into a *Multi-Path* object. The text *size* is the height of the uppercase letter “X” (cap height). The paths are aligned about the insertion point at (0, 0). BASELINE means the bottom of the letter “X”. - **Parameters** - • **s** – text to convert - • **font** – font face definition as **FontFace** object - • **size** – text size (cap height) in drawing units - • **align** – alignment as *ezdxf.enums.TextEntityAlignment*, default is **LEFT** - • **length** – target length for the **ALIGNED** and **FIT** alignments - • **m** – transformation *Matrix44* - **ezdxf.addons.text2path.make\_paths\_from\_str(s: str, font: *FontFace*, size: float = 1.0, align=TextEntityAlignment.LEFT, length: float = 0, m: *Matrix44* = None) -\> list\[Path\]** Convert a single line string *s* into a list of *Path* objects. All paths are returned as a list of *Single-Path* objects. The text *size* is the height of the uppercase letter “X” (cap height). The paths are aligned about the insertion point at (0, 0). BASELINE means the bottom of the letter “X”. - **Parameters** - • **s** – text to convert - • **font** – font face definition as **FontFace** object - • **size** – text size (cap height) in drawing units - • **align** – alignment as *ezdxf.enums.TextEntityAlignment*, default is **LEFT** - • **length** – target length for the **ALIGNED** and **FIT** alignments - • **m** – transformation *Matrix44* - **ezdxf.addons.text2path.make\_hatches\_from\_str(s: str, font: *FontFace*, size: float = 1.0, align=TextEntityAlignment.LEFT, length: float = 0, dxfattribs=None, m: *Matrix44* = None) -\> list\[Hatch\]** Convert a single line string *s* into a list of virtual *Hatch* entities. The text *size* is the height of the uppercase letter “X” (cap height). The paths are aligned about the insertion point at (0, 0). The HATCH entities are aligned to this insertion point. BASELINE means the bottom of the letter “X”. **IMPORTANT:** Returns an empty list for .shx, .shp and .lff fonts a.k.a. stroke fonts. - **Parameters** - • **s** – text to convert - • **font** – font face definition as **FontFace** object - • **size** – text size (cap height) in drawing units - • **align** – alignment as *ezdxf.enums.TextEntityAlignment*, default is **LEFT** - • **length** – target length for the **ALIGNED** and **FIT** alignments - • **dxfattribs** – additional DXF attributes - • **m** – transformation *Matrix44* ### Entity Functions - **class ezdxf.addons.text2path.Kind(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The *Kind* enum defines the DXF types to create as bit flags, e.g. 1+2 to get HATCHES as filling and SPLINES and POLYLINES as outline: | | | | | --- | --- | --- | | Int | Enum | Description | | 1 | HATCHES | *Hatch* entities as filling | | 2 | SPLINES | *Spline* and 3D *Polyline* entities as outline | | 4 | LWPOLYLINES | *LWPolyline* entities as approximated (flattened) outline | - **ezdxf.addons.text2path.virtual\_entities(entity: Text \| Attrib, kind: int = Kind.HATCHES) -\> *EntityQuery*** Convert the text content of DXF entities TEXT and ATTRIB into virtual SPLINE and 3D POLYLINE entities or approximated LWPOLYLINE entities as outlines, or as HATCH entities as fillings. Returns the virtual DXF entities as an *EntityQuery* object. - **Parameters** - • **entity** – TEXT or ATTRIB entity - • **kind** – kind of entities to create as bit flags, see enum *Kind* - **ezdxf.addons.text2path.explode(entity: Text \| Attrib, kind: int = Kind.HATCHES, target=None) -\> *EntityQuery*** Explode the text *entity* into virtual entities, see *virtual\_entities()*. The source entity will be destroyed. The target layout is given by the *target* argument, if *target* is **None**, the target layout is the source layout of the text entity. Returns the created DXF entities as an *EntityQuery* object. - **Parameters** - • **entity** – TEXT or ATTRIB entity to explode - • **kind** – kind of entities to create as bit flags, see enum *Kind* - • **target** – target layout for new created DXF entities, **None** for the same layout as the source entity. - **ezdxf.addons.text2path.make\_path\_from\_entity(entity: Text \| Attrib) -\> Path** Convert text content from DXF entities TEXT and ATTRIB into a *Multi-Path* object. The paths are located at the location of the source entity. - **ezdxf.addons.text2path.make\_paths\_from\_entity(entity: Text \| Attrib) -\> list\[Path\]** Convert text content from DXF entities TEXT and ATTRIB into a list of *Path* objects. All paths are returned as a list of *Single-Path* objects. The paths are located at the location of the source entity. ### MTextExplode This tool is meant to explode MTEXT entities into single line TEXT entities by replicating the MTEXT layout as close as possible. This tool requires the optional Matplotlib package to create usable results, nonetheless it also works without Matplotlib, but then uses a mono-spaced replacement font for text size measuring which leads to very inaccurate results. The supported MTEXT features are: - • changing text color - • text strokes: underline, overline and strike through - • changing text size, width and oblique - • changing font faces - • stacked text (fractions) - • multi-column support - • background color - • text frame The tool requires an initialized DXF document io implement all these features by creating additional text styles. When exploding multiple MTEXT entities, they can share this new text styles. Call the **MTextExplode.finalize()** method just once after all MTEXT entities are processed to create the required text styles, or use **MTextExplode** as context manager by using the **with** statement, see examples below. There are also many limitations: - • A 100% accurate result cannot be achieved. - • Character tracking is not supported. - • Tabulator stops have only limited support for LEFT and JUSTIFIED aligned paragraphs to support numbered and bullet lists. An excessive use of tabs will lead to incorrect results. - • The DISTRIBUTED alignment will be replaced by the JUSTIFIED alignment. - • Text flow is always “left to right”. - • The line spacing mostly corresponds to the “EXACT” style, except for stacked text (fractions), which corresponds more to the “AT LEAST” style, but not precisely. This behavior maybe will improve in the future. - • FIELDS are not evaluated by *ezdxf*. - **class ezdxf.addons.MTextExplode(layout, doc=None, spacing\_factor=1.0)** The *MTextExplode* class is a tool to disassemble MTEXT entities into single line TEXT entities and additional LINE entities if required to emulate strokes. The *layout* argument defines the target layout for “exploded” parts of the MTEXT entity. Use argument *doc* if the target layout has no DXF document assigned like virtual layouts. The *spacing\_factor* argument is an advanced tuning parameter to scale the size of space chars. - **explode(mtext: MText, destroy=True)** Explode *mtext* and destroy the source entity if argument *destroy* is **True**. - **finalize()** Create required text styles. This method is called automatically if the class is used as context manager. This method does not work with virtual layouts if no document was assigned at initialization! Example to explode all MTEXT entities in the DXF file “mtext.dxf”: ``` import ezdxf from ezdxf.addons import MTextExplode doc = ezdxf.readfile("mtext.dxf") msp = doc.modelspace() with MTextExplode(msp) as xpl: for mtext in msp.query("MTEXT"): xpl.explode(mtext) doc.saveas("xpl_mtext.dxf") ``` Explode all MTEXT entities into the block “EXPLODE”: ``` import ezdxf from ezdxf.addons import MTextExplode doc = ezdxf.readfile("mtext.dxf") msp = doc.modelspace() blk = doc.blocks.new("EXPLODE") with MTextExplode(blk) as xpl: for mtext in msp.query("MTEXT"): xpl.explode(mtext) msp.add_block_ref("EXPLODE", (0, 0)) doc.saveas("xpl_into_block.dxf") ``` ### HPGL/2 Converter Add-on Added in version 1.1. The **hpgl2** add-on provides tools to process and convert HPGL/2 plot files. ### What are HPGL/2 Plot Files? The Hewlett-Packard Graphics Language (HPGL) is a vector graphics language originally developed by Hewlett-Packard in the 1970s. HPGL is widely used for controlling pen plotters and other output devices, and it has become a de facto standard for communicating between computers and output devices in the field of computer-aided design (CAD) and drafting. HPGL is a command-driven language that consists of a series of commands that control the movement of the plotter pen, the selection of pens and other output parameters, and the drawing of geometric shapes such as lines, arcs, circles, and text. The language is interpreted by the plotter or other output device and translated into physical pen movements on the drawing surface. HPGL has evolved over the years, and various extensions have been added to support more complex graphics operations and to improve compatibility with other graphics languages. Despite the development of newer graphics languages and file formats, HPGL remains a widely used format for vector-based graphics, particularly in the engineering and architectural fields. ### The Goal of This Add-on An HPGL/2 plot file contains all of the data generated by a CAD application that has been sent to a plotter to print an engineering drawing. In the past, the only way to access this data was to view it on a plotter or an specialized application, which could be expensive and impractical for many people. However, this module provides functions and classes to convert HPGL/2 plot files into modern vector graphic formats such as *PDF* and *SVG* and of course DXF, allowing the data to be viewed and processed using a wide range of software tools. **IMPORTANT:** The Python module PyMuPDF is required for the PDF export: *https://pypi.org/project/PyMuPDF/* The *Plotter* class in the **hpgl2** add-on supports only the most commonly used commands of HPGL/2. This is because many CAD applications use only a small subset of HPGL/2 to create their output, typically consisting of polylines and filled polygons. For more information on the supported commands, please refer to the documentation for the *Plotter* class. To use the HPGL2 add-on, the entry point is the *ezdxf.addons.hpgl2.api* module. This module contains the public interface of the add-on and should be imported in the following way: ``` from ezdxf.addons.hpgl2 import api as hpgl2 with open("hpgl2.plt", "rb") as fp: data = fp.read() doc = hpgl2.to_dxf(data, color_mode=hpgl2.ColorMode.ACI) doc.saveas("hpgl2_as.dxf") ``` ### High Level Functions | | | | --- | --- | | *to\_dxf* | Exports the HPGL/2 commands of the byte stream *b* as a DXF document. | | *to\_svg* | Exports the HPGL/2 commands of the byte stream *b* as SVG string. | | *to\_pdf* | Exports the HPGL/2 commands of the byte stream *b* as PDF data. | | *to\_pixmap* | Exports the HPGL/2 commands of the byte stream *b* as pixel image. | - **ezdxf.addons.hpgl2.api.to\_dxf(b: bytes, \*, rotation: int = 0, mirror\_x: bool = False, mirror\_y: bool = False, color\_mode=ColorMode.RGB, merge\_control: *MergeControl* = MergeControl.AUTO) -\> *Drawing*** Exports the HPGL/2 commands of the byte stream *b* as a DXF document. The page content is created at the origin of the modelspace and 1 drawing unit is 1 plot unit (1 plu = 0.025mm) unless scaling values are provided. The content of HPGL files is intended to be plotted on white paper, therefore a white filling will be added as background in color mode **RGB**. All entities are assigned to a layer according to the pen number with the name scheme **PEN\_\<###\>**. In order to be able to process the file better, it is also possible to assign the *ACI* color by layer by setting the argument *color\_mode* to *ColorMode.ACI*, but then the RGB color is lost because the RGB color has always the higher priority over the *ACI*. The first paperspace layout “Layout1” of the DXF document is set up to print the entire modelspace on one sheet, the size of the page is the size of the original plot file in millimeters. HPGL/2’s merge control works at the pixel level and cannot be replicated by DXF, but to prevent fillings from obscuring text, the filled polygons are sorted by luminance - this can be forced or disabled by the argument *merge\_control*, see also *MergeControl* enum. - **Parameters** - • **b** – plot file content as bytes - • **rotation** – rotation angle of 0, 90, 180 or 270 degrees - • **mirror\_x** – mirror in x-axis direction - • **mirror\_y** – mirror in y-axis direction - • **color\_mode** – the color mode controls how color values are assigned to DXF entities, see *ColorMode* - • **merge\_control** – how to order filled polygons, see *MergeControl* Returns: DXF document as instance of class *Drawing* - **ezdxf.addons.hpgl2.api.to\_svg(b: bytes, \*, rotation: int = 0, mirror\_x: bool = False, mirror\_y: bool = False, merge\_control=MergeControl.AUTO) -\> str** Exports the HPGL/2 commands of the byte stream *b* as SVG string. The plot units are mapped 1:1 to **viewBox** units and the size of image is the size of the original plot file in millimeters. HPGL/2’s merge control works at the pixel level and cannot be replicated by the backend, but to prevent fillings from obscuring text, the filled polygons are sorted by luminance - this can be forced or disabled by the argument *merge\_control*, see also *MergeControl* enum. - **Parameters** - • **b** – plot file content as bytes - • **rotation** – rotation angle of 0, 90, 180 or 270 degrees - • **mirror\_x** – mirror in x-axis direction - • **mirror\_y** – mirror in y-axis direction - • **merge\_control** – how to order filled polygons, see *MergeControl* Returns: SVG content as **str** - **ezdxf.addons.hpgl2.api.to\_pdf(b: bytes, \*, rotation: int = 0, mirror\_x: bool = False, mirror\_y: bool = False, merge\_control=MergeControl.AUTO) -\> bytes** Exports the HPGL/2 commands of the byte stream *b* as PDF data. The plot units (1 plu = 0.025mm) are converted to PDF units (1/72 inch) so the image has the size of the original plot file. HPGL/2’s merge control works at the pixel level and cannot be replicated by the backend, but to prevent fillings from obscuring text, the filled polygons are sorted by luminance - this can be forced or disabled by the argument *merge\_control*, see also *MergeControl* enum. Python module PyMuPDF is required: *https://pypi.org/project/PyMuPDF/* - **Parameters** - • **b** – plot file content as bytes - • **rotation** – rotation angle of 0, 90, 180 or 270 degrees - • **mirror\_x** – mirror in x-axis direction - • **mirror\_y** – mirror in y-axis direction - • **merge\_control** – how to order filled polygons, see *MergeControl* Returns: PDF content as **bytes** - **ezdxf.addons.hpgl2.api.to\_pixmap(b: bytes, \*, rotation: int = 0, mirror\_x: bool = False, mirror\_y: bool = False, merge\_control=MergeControl.AUTO, fmt: str = 'png', dpi: int = 96) -\> bytes** Exports the HPGL/2 commands of the byte stream *b* as pixel image. Supported image formats: | | | | --- | --- | | png | Portable Network Graphics | | ppm | Portable Pixmap | | pbm | Portable Bitmap | The plot units (1 plu = 0.025mm) are converted to dot per inch (dpi) so the image has the size of the original plot file. HPGL/2’s merge control works at the pixel level and cannot be replicated by the backend, but to prevent fillings from obscuring text, the filled polygons are sorted by luminance - this can be forced or disabled by the argument *merge\_control*, see also *MergeControl* enum. Python module PyMuPDF is required: *https://pypi.org/project/PyMuPDF/* - **Parameters** - • **b** – plot file content as bytes - • **rotation** – rotation angle of 0, 90, 180 or 270 degrees - • **mirror\_x** – mirror in x-axis direction - • **mirror\_y** – mirror in y-axis direction - • **merge\_control** – how to order filled polygons, see *MergeControl* - • **fmt** – image format - • **dpi** – output resolution in dots per inch Returns: image content as **bytes** - **class ezdxf.addons.hpgl2.api.ColorMode** The color mode controls how color values are assigned to DXF entities - **ACI** Use the pen number as *AutoCAD Color Index (ACI)* for DXF entities, ignores the RGB color values - **RGB** Use the pen number as *AutoCAD Color Index (ACI)* but also set the RGB color for DXF entities, RGB color values have always higher priority than the ACI when displaying DXF content. - **class ezdxf.addons.hpgl2.api.MergeControl** Merge control enumeration. - **NONE** export filled polygons in print order - **LUMINANCE** sort filled polygons by luminance - **AUTO** guess best order of filled polygons ### The Low Level Functions and Classes - **ezdxf.addons.hpgl2.api.hpgl2\_commands(s: bytes) -\> list\[Command\]** Low level plot file parser, extracts the HPGL/2 from the byte stream *b*. **IMPORTANT:** This parser expects the “Enter HPGL/2 mode” escape sequence to recognize HPGL/2 commands. The sequence looks like this: **\[ESC\]%1B**, multiple variants of this sequence are supported. The HPGL/2 commands are often mixed with the Printer Command Language (*PCL*) and/or the Raster Transfer Language (*RTL*) commands in a single plot file. Some plot files that contain pure HPGL/2 code do not contain the escape sequence “Enter HPGL/2 mode”, without this sequence the HPGL/2 parser cannot recognize the beginning of the HPGL/2 code. Add the **ENTER\_HPGL2\_MODE** sequence in front of the bytes stream to switch on the HPGL/2 manually, regardless of whether the file is an HPGL/2 plot file or not, so be careful: ``` commands = hpgl2_commands(hpgl2.ENTER_HPGL2_MODE + data) ``` - **class ezdxf.addons.hpgl2.api.Interpreter(plotter: *Plotter*)** The *Interpreter* is the frontend for the *Plotter* class. The *run()* methods interprets the low level HPGL commands from the *hpgl2\_commands()* parser and sends the commands to the virtual plotter device, which sends his output to a low level **Backend** class. Most CAD application send a very restricted subset of commands to plotters, mostly just polylines and filled polygons. Implementing the whole HPGL/2 command set is not worth the effort - unless reality proofs otherwise. Not implemented commands: - • the whole character group - text is send as filled polygons or polylines - • configuration group: IN, DF, RO, IW - the plotter is initialized by creating a new plotter and page rotation is handled by the add-on itself - • polygon group: EA, ER, EW, FA, RR, WG, the rectangle and wedge commands - • line and fill attributes group: LA, RF, SM, SV, TR, UL, WU, linetypes and hatch patterns are decomposed into simple lines by CAD applications - **Parameters** **plotter** – virtual *Plotter* device - **errors** List of error messages occurred during the interpretation of the HPGL/2 commands. - **not\_implemented\_commands** List of all unsupported/ignored commands from the input stream. - **run(commands: list\[Command\]) -\> None** Interprets the low level HPGL commands from the *hpgl2\_commands()* parser and sends the commands to the virtual plotter device. - **disable\_commands(commands: Iterable\[str\]) -\> None** Disable commands manually, like the scaling command \[“SC”, “IP”, “IR”\]. This is a feature for experts, because disabling commands which changes the pen location may distort or destroy the plotter output. - **class ezdxf.addons.hpgl2.api.Plotter(backend: Backend)** The *Plotter* class represents a virtual plotter device. The HPGL/2 commands send by the *Interpreter* are processed into simple polylines and filled polygons and send to low level **Backend**. HPGL/2 uses a units system called “Plot Units”: - • 1 plot unit (plu) = 0.025mm - • 40 plu = 1 mm - • 1016 plu = 1 inch The Plotter device does not support font rendering and page rotation (RO). The scaling commands IP, RP, SC are supported. ### Recorder - **class ezdxf.addons.hpgl2.api.Recorder** The *Recorder* class records the output of the *Plotter* class. All input coordinates are page coordinates: - • 1 plot unit (plu) = 0.025mm - • 40 plu = 1 mm - • 1016 plu = 1 inch - **player() -\> *Player*** Returns a *Player* instance with the original recordings. Make a copy of this player to protect the original recordings from being modified: ``` safe_player = recorder.player().copy() ``` - **draw\_polyline(properties: *Properties*, points: Sequence\[*Vec2*\]) -\> None** Draws a polyline from a sequence *points*. The input coordinates are page coordinates in plot units. The *points* sequence can contain 0 or more points! - **Parameters** - • **properties** – display **Properties** for the polyline - • **points** – sequence of *ezdxf.math.Vec2* instances - **draw\_paths(properties: *Properties*, paths: Sequence\[Path\], filled: bool) -\> None** Draws filled or outline paths from the sequence of *paths*. The input coordinates are page coordinates in plot units. The *paths* sequence can contain 0 or more single *Path* instances. Draws outline paths if Properties.FillType is NONE and filled paths otherwise. - **Parameters** - • **properties** – display **Properties** for the filled polygon - • **paths** – sequence of single *ezdxf.path.Path* instances - • **filled** – draw filled paths if **True** otherwise outline paths ### Player - **class ezdxf.addons.hpgl2.api.Player(records: list\[DataRecord\], properties: dict\[int, *Properties*\])** This class replays the recordings of the *Recorder* class on another backend. The class can modify the recorded output. - **copy() -\> Self** Returns a new *Player* instance with a copy of recordings. - **recordings() -\> Iterator\[tuple\[RecordType, *Properties*, Any\]\]** Yields all recordings as *(RecordType, Properties, Data)* tuples. The content of the *Data* field is determined by the enum **RecordType**: - • **RecordType.POLYLINE** returns a **NumpyPoints2d** instance - • **RecordType.FILLED\_POLYGON** returns a tuple of **NumpyPath2d** instances - **replay(backend: Backend) -\> None** Replay the recording on another backend. - **bbox() -\> *BoundingBox2d*** Returns the bounding box of all recorded polylines and polygons as *BoundingBox2d*. - **transform(m: *Matrix44*) -\> None** Transforms the recordings by a transformation matrix *m* of type *Matrix44*. - **sort\_filled\_paths() -\> None** Sort filled paths by descending luminance (from light to dark). This also changes the plot order in the way that all filled paths are plotted before polylines and outline paths. ### Properties - **class ezdxf.addons.hpgl2.properties.Properties** Consolidated display properties. - **pen\_index** pen index as int - **pen\_color** pen color as **RGB** tuple - **pen\_width** pen width in millimeters (float) - **fill\_type** *FillType* of filled polygons - **fill\_method** *FillMethod* of filled polygons - **fill\_hatch\_line\_angle** fill hatch line angle in degrees - **fill\_hatch\_line\_spacing** fill hatch line distance in plotter units - **fill\_shading\_density** fill shading density in percent from 0 to 100. - **resolve\_pen\_color() -\> *RGB*** Returns the final RGB pen color. - **resolve\_fill\_color() -\> *RGB*** Returns the final RGB fill color. - **class ezdxf.addons.hpgl2.properties.FillType(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Fill type enumeration. - **NONE** - **SOLID** - **HATCHING** - **CROSS\_HATCHING** - **SHADING** - **class ezdxf.addons.hpgl2.properties.FillMethod(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Fill method enumeration. - **EVEN\_ODD** - **NONE\_ZERO\_WINDING** ### Exceptions - **class ezdxf.addons.hpgl2.api.Hpgl2Error** Base exception for the **hpgl2** add-on. - **class ezdxf.addons.hpgl2.api.Hpgl2DataNotFound** No HPGL/2 data was found, maybe the “Enter HPGL/2 mode” escape sequence is missing. - **class ezdxf.addons.hpgl2.api.EmptyDrawing** The HPGL/2 commands do not produce any content. ### PyCSG Constructive Solid Geometry (CSG) is a modeling technique that uses Boolean operations like union and intersection to combine 3D solids. This library implements CSG operations on meshes elegantly and concisely using BSP trees, and is meant to serve as an easily understandable implementation of the algorithm. All edge cases involving overlapping coplanar polygons in both solids are correctly handled. Example for usage: ``` import ezdxf from ezdxf.render.forms import cube, cylinder_2p from ezdxf.addons.pycsg import CSG # create new DXF document doc = ezdxf.new() msp = doc.modelspace() # create same geometric primitives as MeshTransformer() objects cube1 = cube() cylinder1 = cylinder_2p(count=32, base_center=(0, -1, 0), top_center=(0, 1, 0), radius=.25) # build solid union union = CSG(cube1) + CSG(cylinder1) # convert to mesh and render mesh to modelspace union.mesh().render_mesh(msp, dxfattribs={'color': 1}) # build solid difference difference = CSG(cube1) - CSG(cylinder1) # convert to mesh, translate mesh and render mesh to modelspace difference.mesh().translate(1.5).render_mesh(msp, dxfattribs={'color': 3}) # build solid intersection intersection = CSG(cube1) * CSG(cylinder1) # convert to mesh, translate mesh and render mesh to modelspace intersection.mesh().translate(2.75).render_mesh(msp, dxfattribs={'color': 5}) doc.saveas('csg.dxf') ``` \[image: Cube vs Cylinder\] \[image\] This CSG kernel supports only meshes as *MeshBuilder* objects, which can be created from and converted to DXF *Mesh* entities. This CSG kernel is **not** compatible with ACIS objects like *Solid3d*, *Body*, *Surface* or *Region*. **NOTE:** This is a pure Python implementation, don’t expect great performance and the implementation is based on an unbalanced *BSP tree*, so in the case of **RecursionError**, increase the recursion limit: ``` import sys actual_limit = sys.getrecursionlimit() # default is 1000, increasing too much may cause a seg fault sys.setrecursionlimit(10000) ... # do the CSG stuff sys.setrecursionlimit(actual_limit) ``` CSG works also with spheres, but with really bad runtime behavior and most likely **RecursionError** exceptions, and use *quadrilaterals* as body faces to reduce face count by setting argument *quads* to **True**. ``` import ezdxf from ezdxf.render.forms import sphere, cube from ezdxf.addons.pycsg import CSG doc = ezdxf.new() doc.set_modelspace_vport(6, center=(5, 0)) msp = doc.modelspace() cube1 = cube().translate(-.5, -.5, -.5) sphere1 = sphere(count=32, stacks=16, radius=.5, quads=True) union = (CSG(cube1) + CSG(sphere1)).mesh() union.render_mesh(msp, dxfattribs={'color': 1}) subtract = (CSG(cube1) - CSG(sphere1)).mesh().translate(2.5) subtract.render_mesh(msp, dxfattribs={'color': 3}) intersection = (CSG(cube1) * CSG(sphere1)).mesh().translate(4) intersection.render_mesh(msp, dxfattribs={'color': 5}) ``` \[image: Cube vs Sphere\] \[image\] Hard Core CSG - Menger Sponge Level 3 vs Sphere Required runtime on an old Xeon E5-1620 Workstation @ 3.60GHz (2020), with default recursion limit of 1000 on Windows 10: - • CPython 3.8.1 64bit: ~60 seconds, - • PyPy \[PyPy 7.2.0\] 32bit: ~6 seconds, and using **\_\_slots\_\_** reduced runtime below 5 seconds, yes - PyPy is worth a look for long running scripts! Updated runtime in 2024 on an i7-12700K @ 3.60GHz (peak ~5GHz), Windows 11: - • CPython 3.11.6 64bit: ~3.4 seconds - • PyPy 3.9.18 \[PyPy 7.3.13\] 64bit: ~1.5 seconds ``` from ezdxf.render.forms import sphere from ezdxf.addons import MengerSponge from ezdxf.addons.pycsg import CSG doc = ezdxf.new() doc.layers.new('sponge', dxfattribs={'color': 5}) doc.layers.new('sphere', dxfattribs={'color': 6}) doc.set_modelspace_vport(6, center=(5, 0)) msp = doc.modelspace() sponge1 = MengerSponge(level=3).mesh() sphere1 = sphere(count=32, stacks=16, radius=.5, quads=True).translate(.25, .25, 1) subtract = (CSG(sponge1, meshid=1) - CSG(sphere1, meshid=2)) # get mesh result by id subtract.mesh(1).render_mesh(msp, dxfattribs={'layer': 'sponge'}) subtract.mesh(2).render_mesh(msp, dxfattribs={'layer': 'sphere'}) ``` \[image: Menger Sponge vs Sphere\] \[image\] ### CSG Class - **class ezdxf.addons.pycsg.CSG(mesh: *MeshBuilder*, meshid: int = 0)** Constructive Solid Geometry (CSG) is a modeling technique that uses Boolean operations like union and intersection to combine 3D solids. This class implements CSG operations on meshes. New 3D solids are created from *MeshBuilder* objects and results can be exported as *MeshTransformer* objects to *ezdxf* by method *mesh()*. - **Parameters** - • **mesh** – *ezdxf.render.MeshBuilder* or inherited object - • **meshid** – individual mesh ID to separate result meshes, **0** is default - **mesh(meshid: int = 0) -\> MeshTransformer** Returns a *ezdxf.render.MeshTransformer* object. - **Parameters** **meshid** – individual mesh ID, **0** is default - **union(other: *CSG*) -\> *CSG*** Return a new CSG solid representing space in either this solid or in the solid *other*. Neither this solid nor the solid *other* are modified: ``` A.union(B) +-------+ +-------+ | | | | | A | | | | +--+----+ = | +----+ +----+--+ | +----+ | | B | | | | | | | +-------+ +-------+ ``` - **\_\_add\_\_()** ``` union = A + B ``` - **subtract(other: *CSG*) -\> *CSG*** Return a new CSG solid representing space in this solid but not in the solid *other*. Neither this solid nor the solid *other* are modified: ``` A.subtract(B) +-------+ +-------+ | | | | | A | | | | +--+----+ = | +--+ +----+--+ | +----+ | B | | | +-------+ ``` - **\_\_sub\_\_()** ``` difference = A - B ``` - **intersect(other: *CSG*) -\> *CSG*** Return a new CSG solid representing space both this solid and in the solid *other*. Neither this solid nor the solid *other* are modified: ``` A.intersect(B) +-------+ | | | A | | +--+----+ = +--+ +----+--+ | +--+ | B | | | +-------+ ``` - **\_\_mul\_\_()** ``` intersection = A * B ``` - **inverse() -\> *CSG*** Return a new CSG solid with solid and empty space switched. This solid is not modified. ### License - • Original implementation *csg.js*, Copyright (c) 2011 Evan Wallace (*http://madebyevan.com/*), under the MIT license. - • Python port *pycsg*, Copyright (c) 2012 Tim Knip (*http://www.floorplanner.com*), under the MIT license. - • Additions by Alex Pletzer (Pennsylvania State University) - • Integration as *ezdxf* add-on, Copyright (c) 2020, Manfred Moitzi, MIT License. ### Plot Style Files (CTB/STB) CTB and STB files store plot styles used by AutoCAD and BricsCAD for printing and plotting. If the plot style table is attached to a *Paperspace* or the *Modelspace*, a change of a plot style affects any object that uses that plot style. CTB files contain color dependent plot style tables, STB files contain named plot style tables. **SEE ALSO:** - • *Using plot style tables in AutoCAD* - • *AutoCAD Plot Style Table Editor* - • *BricsCAD Plot Style Table Editor* - • AUTODESK KNOWLEDGE NETWORK: How to *install* CTB files in AutoCAD - **ezdxf.addons.acadctb.load(filename: str \| PathLike) -\> *ColorDependentPlotStyles* \| *NamedPlotStyles*** Load the CTB or STB file *filename* from file system. - **ezdxf.addons.acadctb.new\_ctb() -\> *ColorDependentPlotStyles*** Create a new CTB file. - **ezdxf.addons.acadctb.new\_stb() -\> *NamedPlotStyles*** Create a new STB file. ### ColorDependentPlotStyles Color dependent plot style table (CTB file), table entries are *PlotStyle* objects. - **class ezdxf.addons.acadctb.ColorDependentPlotStyles** - **description** Custom description of plot style file. - **scale\_factor** Specifies the factor by which to scale non-ISO linetypes and fill patterns. - **apply\_factor** Specifies whether or not you want to apply the *scale\_factor*. - **custom\_lineweight\_display\_units** Set **1** for showing lineweight in inch in AutoCAD CTB editor window, but lineweights are always defined in millimeters. - **lineweights** Lineweights table as **array.array** - **\_\_getitem\_\_(aci: int) -\> *PlotStyle*** Returns *PlotStyle* for *AutoCAD Color Index (ACI)* *aci*. - **\_\_iter\_\_()** Iterable of all plot styles. - **new\_style(aci: int, data: dict \| None = None) -\> *PlotStyle*** Set *aci* to new attributes defined by *data* dict. - **Parameters** - • **aci** – *AutoCAD Color Index (ACI)* - • **data** – **dict** of *PlotStyle* attributes: description, color, physical\_pen\_number, virtual\_pen\_number, screen, linepattern\_size, linetype, adaptive\_linetype, lineweight, end\_style, join\_style, fill\_style - **get\_lineweight(aci: int)** Returns the assigned lineweight for *PlotStyle* *aci* in millimeter. - **get\_lineweight\_index(lineweight: float) -\> int** Get index of *lineweight* in the lineweight table or append *lineweight* to lineweight table. - **get\_table\_lineweight(index: int) -\> float** Returns lineweight in millimeters of lineweight table entry *index*. - **Parameters** **index** – lineweight table index = *PlotStyle.lineweight* - **Returns** lineweight in mm or **0.0** for use entity lineweight - **set\_table\_lineweight(index: int, lineweight: float) -\> int** Argument *index* is the lineweight table index, not the *AutoCAD Color Index (ACI)*. - **Parameters** - • **index** – lineweight table index = *PlotStyle.lineweight* - • **lineweight** – in millimeters - **save()** Save CTB file as *filename* to the file system. - **write(stream: BinaryIO) -\> None** Compress and write CTB file to binary *stream*. ### NamedPlotStyles Named plot style table (STB file), table entries are *PlotStyle* objects. - **class ezdxf.addons.acadctb.NamedPlotStyles** - **description** Custom description of plot style file. - **scale\_factor** Specifies the factor by which to scale non-ISO linetypes and fill patterns. - **apply\_factor** Specifies whether or not you want to apply the *scale\_factor*. - **custom\_lineweight\_display\_units** Set **1** for showing lineweight in inch in AutoCAD CTB editor window, but lineweights are always defined in millimeters. - **lineweights** Lineweights table as **array.array** - **\_\_getitem\_\_(name: str) -\> *PlotStyle*** Returns *PlotStyle* by *name*. - **\_\_delitem\_\_(name: str) -\> None** Delete plot style *name*. Plot style **'Normal'** is not deletable. - **\_\_iter\_\_() -\> Iterable\[str\]** Iterable of all plot style names. - **new\_style(name: str, data: dict \| None = None, localized\_name: str \| None = None) -\> *PlotStyle*** Create new class:*PlotStyle* *name* by attribute dict *data*, replaces existing class:*PlotStyle* objects. - **Parameters** - • **name** – plot style name - • **localized\_name** – name shown in plot style editor, uses *name* if **None** - • **data** – **dict** of *PlotStyle* attributes: description, color, physical\_pen\_number, virtual\_pen\_number, screen, linepattern\_size, linetype, adaptive\_linetype, lineweight, end\_style, join\_style, fill\_style - **get\_lineweight(name: str)** Returns the assigned lineweight for *PlotStyle* *name* in millimeter. - **get\_lineweight\_index(lineweight: float) -\> int** Get index of *lineweight* in the lineweight table or append *lineweight* to lineweight table. - **get\_table\_lineweight(index: int) -\> float** Returns lineweight in millimeters of lineweight table entry *index*. - **Parameters** **index** – lineweight table index = *PlotStyle.lineweight* - **Returns** lineweight in mm or **0.0** for use entity lineweight - **set\_table\_lineweight(index: int, lineweight: float) -\> int** Argument *index* is the lineweight table index, not the *AutoCAD Color Index (ACI)*. - **Parameters** - • **index** – lineweight table index = *PlotStyle.lineweight* - • **lineweight** – in millimeters - **save()** Save STB file as *filename* to the file system. - **write()** Compress and write STB file to binary *stream*. ### PlotStyle - **class ezdxf.addons.acadctb.PlotStyle** - **index** Table index (0-based). (int) - **aci** *AutoCAD Color Index (ACI)* in range from **1** to **255**. Has no meaning for named plot styles. (int) - **description** Custom description of plot style. (str) - **physical\_pen\_number** Specifies physical plotter pen, valid range from **1** to **32** or *AUTOMATIC*. (int) - **virtual\_pen\_number** Only used by non-pen plotters and only if they are configured for virtual pens. valid range from **1** to **255** or *AUTOMATIC*. (int) - **screen** Specifies the color intensity of the plot on the paper, valid range is from **0** to **100**. (int) If you select **100** the drawing will plotted with its full color intensity. In order for screening to work, the *dithering* option must be active. - **linetype** Overrides the entity linetype, default value is *OBJECT\_LINETYPE*. (bool) - **adaptive\_linetype** **True** if a complete linetype pattern is more important than a correct linetype scaling, default is **True**. (bool) - **linepattern\_size** Line pattern size, default = **0.5**. (float) - **lineweight** Overrides the entity lineWEIGHT, default value is *OBJECT\_LINEWEIGHT*. This is an index into the **UserStyles.lineweights** table. (int) - **end\_style** Line end cap style, see table below, default is **END\_STYLE\_OBJECT** (int) - **join\_style** Line join style, see table below, default is **JOIN\_STYLE\_OBJECT** (int) - **fill\_style** Line fill style, see table below, default is **FILL\_STYLE\_OBJECT** (int) - **dithering** Depending on the capabilities of your plotter, dithering approximates the colors with dot patterns. When this option is **False**, the colors are mapped to the nearest color, resulting in a smaller range of colors when plotting. Dithering is available only whether you select the object’s color or assign a plot style color. - **grayscale** Plot colors in grayscale. (bool) ### Default Line Weights | | | | --- | --- | | # | \[mm\] | | 0 | 0.00 | | 1 | 0.05 | | 2 | 0.09 | | 3 | 0.10 | | 4 | 0.13 | | 5 | 0.15 | | 6 | 0.18 | | 7 | 0.20 | | 8 | 0.25 | | 9 | 0.30 | | 10 | 0.35 | | 11 | 0.40 | | 12 | 0.45 | | 13 | 0.50 | | 14 | 0.53 | | 15 | 0.60 | | 16 | 0.65 | | 17 | 0.70 | | 18 | 0.80 | | 19 | 0.90 | | 20 | 1.00 | | 21 | 1.06 | | 22 | 1.20 | | 23 | 1.40 | | 24 | 1.58 | | 25 | 2.00 | | 26 | 2.11 | ### Predefined Values - **ezdxf.addons.acadctb.AUTOMATIC** - **ezdxf.addons.acadctb.OBJECT\_LINEWEIGHT** - **ezdxf.addons.acadctb.OBJECT\_LINETYPE** - **ezdxf.addons.acadctb.OBJECT\_COLOR** - **ezdxf.addons.acadctb.OBJECT\_COLOR2** ### Line End Style \[image\] | | | | --- | --- | | END\_STYLE\_BUTT | **0** | | END\_STYLE\_SQUARE | **1** | | END\_STYLE\_ROUND | **2** | | END\_STYLE\_DIAMOND | **3** | | END\_STYLE\_OBJECT | **4** | ### Line Join Style \[image\] | | | | --- | --- | | JOIN\_STYLE\_MITER | **0** | | JOIN\_STYLE\_BEVEL | **1** | | JOIN\_STYLE\_ROUND | **2** | | JOIN\_STYLE\_DIAMOND | **3** | | JOIN\_STYLE\_OBJECT | **5** | ### Fill Style \[image\] | | | | --- | --- | | FILL\_STYLE\_SOLID | **64** | | FILL\_STYLE\_CHECKERBOARD | **65** | | FILL\_STYLE\_CROSSHATCH | **66** | | FILL\_STYLE\_DIAMONDS | **67** | | FILL\_STYLE\_HORIZONTAL\_BARS | **68** | | FILL\_STYLE\_SLANT\_LEFT | **69** | | FILL\_STYLE\_SLANT\_RIGHT | **70** | | FILL\_STYLE\_SQUARE\_DOTS | **71** | | FILL\_STYLE\_VERICAL\_BARS | **72** | | FILL\_STYLE\_OBJECT | **73** | ### Linetypes \[image\] \[image\] | | | | --- | --- | | Linetype name | Value | | Solid | 0 | | Dashed | 1 | | Dotted | 2 | | Dash Dot | 3 | | Short Dash | 4 | | Medium Dash | 5 | | Long Dash | 6 | | Short Dash x2 | 7 | | Medium Dash x2 | 8 | | Long Dash x2 | 9 | | Medium Lang Dash | 10 | | Medium Dash Short Dash Short Dash | 11 | | Long Dash Short Dash | 12 | | Long Dash Dot Dot | 13 | | Long Dash Dot | 14 | | Medium Dash Dot Short Dash Dot | 15 | | Sparse Dot | 16 | | ISO Dash | 17 | | ISO Dash Space | 18 | | ISO Long Dash Dot | 19 | | ISO Long Dash Double Dot | 20 | | ISO Long Dash Triple Dot | 21 | | ISO Dot | 22 | | ISO Long Dash Short Dash | 23 | | ISO Long Dash Double Short Dash | 24 | | ISO Dash Dot | 25 | | ISO Double Dash Dot | 26 | | ISO Dash Double Dot | 27 | | ISO Double Dash Double Dot | 28 | | ISO Dash Triple Dot | 29 | | ISO Double Dash Triple Dot | 30 | | Use entity linetype | 31 | ### Showcase Forms ### MengerSponge Build a 3D *Menger sponge*. - **class ezdxf.addons.MengerSponge(location: *UVec* = (0.0, 0.0, 0.0), length: float = 1.0, level: int = 1, kind: int = 0)** - **Parameters** - • **location** – location of lower left corner as (x, y, z) tuple - • **length** – side length - • **level** – subdivide level - • **kind** – type of menger sponge | | | | --- | --- | | 0 | Original Menger Sponge | | 1 | Variant XOX | | 2 | Variant OXO | | 3 | Jerusalem Cube | - **render(layout: GenericLayoutType, merge: bool = False, dxfattribs=None, matrix: *Matrix44* \| None = None, ucs: *UCS* \| None = None) -\> None** Renders the menger sponge into layout, set *merge* to **True** for rendering the whole menger sponge into one MESH entity, set *merge* to **False** for rendering the individual cubes of the menger sponge as MESH entities. - **Parameters** - • **layout** – DXF target layout - • **merge** – **True** for one MESH entity, **False** for individual MESH entities per cube - • **dxfattribs** – DXF attributes for the MESH entities - • **matrix** – apply transformation matrix at rendering - • **ucs** – apply UCS transformation at rendering - **cubes() -\> Iterator\[MeshTransformer\]** Yields all cubes of the menger sponge as individual **MeshTransformer** objects. - **mesh() -\> MeshTransformer** Returns geometry as one **MeshTransformer** object. Menger Sponge **kind=0**: \[image\] Menger Sponge **kind=1**: \[image\] Menger Sponge **kind=2**: \[image\] Jerusalem Cube **kind=3**: \[image\] ### SierpinskyPyramid Build a 3D *Sierpinsky Pyramid*. - **class ezdxf.addons.SierpinskyPyramid(location: *UVec* = (0.0, 0.0, 0.0), length: float = 1.0, level: int = 1, sides: int = 4)** - **Parameters** - • **location** – location of base center as (x, y, z) tuple - • **length** – side length - • **level** – subdivide level - • **sides** – sides of base geometry - **render(layout: GenericLayoutType, merge: bool = False, dxfattribs=None, matrix: *Matrix44* \| None = None, ucs: *UCS* \| None = None) -\> None** Renders the sierpinsky pyramid into layout, set *merge* to **True** for rendering the whole sierpinsky pyramid into one MESH entity, set *merge* to **False** for individual pyramids as MESH entities. - **Parameters** - • **layout** – DXF target layout - • **merge** – **True** for one MESH entity, **False** for individual MESH entities per pyramid - • **dxfattribs** – DXF attributes for the MESH entities - • **matrix** – apply transformation matrix at rendering - • **ucs** – apply UCS at rendering - **pyramids() -\> Iterable\[MeshTransformer\]** Yields all pyramids of the sierpinsky pyramid as individual **MeshTransformer** objects. - **mesh() -\> MeshTransformer** Returns geometry as one **MeshTransformer** object. Sierpinsky Pyramid with triangle base: \[image\] Sierpinsky Pyramid with square base: \[image\] ### Bin-Packing Add-on This add-on is based on the 3D bin packing module *py3dbp* hosted on *PyPI*. Both sources of this package are MIT licensed like *ezdxf* itself. ### The Bin Packing Problem Quote from the *Wikipedia* article: The bin packing problem is an optimization problem, in which items of different sizes must be packed into a finite number of bins or containers, each of a fixed given capacity, in a way that minimizes the number of bins used. ### Example This code replicates the example used by the *py3dbp* package: ``` from typing import List import ezdxf from ezdxf import colors from ezdxf.addons import binpacking as bp SMALL_ENVELOPE = ("small-envelope", 11.5, 6.125, 0.25, 10) LARGE_ENVELOPE = ("large-envelope", 15.0, 12.0, 0.75, 15) SMALL_BOX = ("small-box", 8.625, 5.375, 1.625, 70.0) MEDIUM_BOX = ("medium-box", 11.0, 8.5, 5.5, 70.0) MEDIUM_BOX2 = ("medium-box-2", 13.625, 11.875, 3.375, 70.0) LARGE_BOX = ("large-box", 12.0, 12.0, 5.5, 70.0) LARGE_BOX2 = ("large-box-2", 23.6875, 11.75, 3.0, 70.0) ALL_BINS = [ SMALL_ENVELOPE, LARGE_ENVELOPE, SMALL_BOX, MEDIUM_BOX, MEDIUM_BOX2, LARGE_BOX, LARGE_BOX2, ] def build_packer(): packer = bp.Packer() packer.add_item("50g [powder 1]", 3.9370, 1.9685, 1.9685, 1) packer.add_item("50g [powder 2]", 3.9370, 1.9685, 1.9685, 2) packer.add_item("50g [powder 3]", 3.9370, 1.9685, 1.9685, 3) packer.add_item("250g [powder 4]", 7.8740, 3.9370, 1.9685, 4) packer.add_item("250g [powder 5]", 7.8740, 3.9370, 1.9685, 5) packer.add_item("250g [powder 6]", 7.8740, 3.9370, 1.9685, 6) packer.add_item("250g [powder 7]", 7.8740, 3.9370, 1.9685, 7) packer.add_item("250g [powder 8]", 7.8740, 3.9370, 1.9685, 8) packer.add_item("250g [powder 9]", 7.8740, 3.9370, 1.9685, 9) return packer def make_doc(): doc = ezdxf.new() doc.layers.add("FRAME", color=colors.YELLOW) doc.layers.add("ITEMS") doc.layers.add("TEXT") return doc def main(filename): bins: List[bp.Bin] = [] for box in ALL_BINS: packer = build_packer() packer.add_bin(*box) packer.pack(bp.PickStrategy.BIGGER_FIRST) bins.extend(packer.bins) doc = make_doc() bp.export_dxf(doc.modelspace(), bins, offset=(0, 20, 0)) doc.saveas(filename) if __name__ == "__main__": main("py3dbp_example.dxf") ``` \[image\] **SEE ALSO:** - • *example1* script - • *example2* script ### Packer Classes - **class ezdxf.addons.binpacking.AbstractPacker** - **bins** List of containers to fill. - **items** List of items to pack into the *bins*. - **property is\_packed: bool** Returns **True** if packer is packed, each packer can only be used once. - **property unfitted\_items: list\[*Item*\]** Returns the unfitted items. - **\_\_str\_\_() -\> str** Return str(self). - **append\_bin(box: *Bin*) -\> None** Append a container. - **append\_item(item: *Item*) -\> None** Append a item. - **get\_fill\_ratio() -\> float** Return the fill ratio of all bins. - **get\_capacity() -\> float** Returns the maximum fill volume of all bins. - **get\_total\_weight() -\> float** Returns the total weight of all fitted items in all bins. - **get\_total\_volume() -\> float** Returns the total volume of all fitted items in all bins. - **pack(pick=PickStrategy.BIGGER\_FIRST) -\> None** Pack items into bins. Distributes all items across all bins. ### Packer - **class ezdxf.addons.binpacking.Packer** 3D Packer inherited from *AbstractPacker*. - **add\_bin(name: str, width: float, height: float, depth: float, max\_weight: float = UNLIMITED\_WEIGHT) -\> *Box*** Add a 3D *Box* container. - **add\_item(payload, width: float, height: float, depth: float, weight: float = 0.0) -\> *Item*** Add a 3D *Item* to pack. ### FlatPacker - **class ezdxf.addons.binpacking.FlatPacker** 2D Packer inherited from *AbstractPacker*. All containers and items used by this packer must have a depth of 1. - **add\_bin(name: str, width: float, height: float, max\_weight: float = UNLIMITED\_WEIGHT) -\> *Envelope*** Add a 2D *Envelope* container. - **add\_item(payload, width: float, height: float, weight: float = 0.0) -\> *Item*** Add a 2D *FlatItem* to pack. ### Bin Classes - **class ezdxf.addons.binpacking.Bin(name, width: float, height: float, depth: float, max\_weight: float = UNLIMITED\_WEIGHT)** - **name** Name of then container as string. - **width** - **height** - **depth** - **max\_weight** - **property is\_empty: bool** - **\_\_str\_\_() -\> str** Return str(self). - **copy()** Returns a copy. - **reset()** Reset the container to empty state. - **put\_item(item: *Item*, pivot: tuple\[float, float, float\]) -\> bool** - **get\_capacity() -\> float** Returns the maximum fill volume of the bin. - **get\_total\_weight() -\> float** Returns the total weight of all fitted items. - **get\_total\_volume() -\> float** Returns the total volume of all fitted items. - **get\_fill\_ratio() -\> float** Return the fill ratio. ### Box Class - **class ezdxf.addons.binpacking.Box(name, width: float, height: float, depth: float, max\_weight: float = UNLIMITED\_WEIGHT)** 3D container inherited from *Bin*. ### Envelope Class - **class ezdxf.addons.binpacking.Envelope(name, width: float, height: float, max\_weight: float = UNLIMITED\_WEIGHT)** 2D container inherited from *Bin*. ### Item Class - **class ezdxf.addons.binpacking.Item(payload, width: float, height: float, depth: float, weight: float = 0.0)** 3D container item. - **payload** Arbitrary Python object. - **width** - **height** - **depth** - **weight** - **property bbox: AbstractBoundingBox** - **property rotation\_type: *RotationType*** - **property position: tuple\[float, float, float\]** Returns the position of then lower left corner of the item in the container, the lower left corner is the origin (0, 0, 0). - **copy()** Returns a copy, all copies have a reference to the same payload object. - **\_\_str\_\_()** Return str(self). - **get\_volume() -\> float** Returns the volume of the item. - **get\_dimension() -\> tuple\[float, float, float\]** Returns the item dimension according the *rotation\_type*. - **get\_transformation() -\> *Matrix44*** Returns the transformation matrix to transform the source entity located with the minimum extension corner of its bounding box in (0, 0, 0) to the final location including the required rotation. ### FlatItem Class - **class ezdxf.addons.binpacking.FlatItem(payload, width: float, height: float, weight: float = 0.0)** 2D container item, inherited from *Item*. Has a default depth of 1.0. ### Functions - **ezdxf.addons.binpacking.shuffle\_pack(packer: *AbstractPacker*, attempts: int) -\> *AbstractPacker*** Random shuffle packing. Returns a new packer with the best packing result, the input packer is unchanged. ### Enums ### RotationType - **class ezdxf.addons.binpacking.RotationType(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Rotation type of an item: - • W = width - • H = height - • D = depth - **WHD** - **HWD** - **HDW** - **DHW** - **DWH** - **WDH** ### PickStrategy - **class ezdxf.addons.binpacking.PickStrategy(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Order of how to pick items for placement. - **BIGGER\_FIRST** - **SMALLER\_FIRST** - **SHUFFLE** ### Credits - • *py3dbp* package by Enzo Ruiz Pelaez - • *bp3d* by *gedex* - github repository on which *py3dbp* is based, written in Go - • Optimizing three-dimensional bin packing through simulation (*PDF*) ### MeshExchange The *ezdxf.addons.meshex* module provides functions to exchange meshes with other tools in the following file formats: - • *STL*: import/export, supports only triangles as faces - • *OFF*: import/export, supports ngons as faces and is more compact than STL - • *OBJ*: import/export, supports ngons as faces and can contain multiple meshes in one file - • *PLY*: export only, supports ngons as faces - • *OpenSCAD*: export as *polyhedron*, supports ngons as faces - • *IFC4*: export only, supports ngons as faces The source or target object is always a *MeshBuilder* instance and therefore the supported features are also limited by this class. Only vertices and faces are exchanged, colors, textures and explicit face- and vertex normals are lost. **NOTE:** This add-on is not a replacement for a proper file format interface for this data formats! It’s just a simple way to exchange meshes with other tools like *OpenSCAD* or *MeshLab*. **WARNING:** The meshes created by the *ezdxf.addons.pycsg* add-on are usually not suitable for export because they often violate the vertex-to-vertex rule: A vertex of a face cannot lie on the edge of another face. This was one of the reasons to create this addon to get an interface to *OpenSCAD*. Example for a simple STL to DXF converter: ``` import sys import ezdxf from ezdxf.addons import meshex try: mesh = meshex.stl_readfile("your.stl") except (meshex.ParsingError, IOError) as e: print(str(e)) sys.exit(1) doc = ezdxf.new() mesh.render_mesh(doc.modelspace()) doc.saveas("your.dxf") ``` **SEE ALSO:** Example script *meshex\_export.py* at github. ### Import - **ezdxf.addons.meshex.stl\_readfile(filename: str \| PathLike) -\> MeshTransformer** Read ascii or binary *STL* file content as *ezdxf.render.MeshTransformer* instance. - **Raises** *ParsingError* – vertex parsing error or invalid/corrupt data - **ezdxf.addons.meshex.stl\_loads(content: str) -\> MeshTransformer** Load a mesh from an ascii *STL* content string as *ezdxf.render.MeshTransformer* instance. - **Raises** *ParsingError* – vertex parsing error - **ezdxf.addons.meshex.stl\_loadb(buffer: bytes) -\> MeshTransformer** Load a mesh from a binary *STL* data *ezdxf.render.MeshTransformer* instance. - **Raises** *ParsingError* – invalid/corrupt data or not a binary STL file - **ezdxf.addons.meshex.off\_readfile(filename: str \| PathLike) -\> MeshTransformer** Read *OFF* file content as *ezdxf.render.MeshTransformer* instance. - **Raises** *ParsingError* – vertex or face parsing error - **ezdxf.addons.meshex.off\_loads(content: str) -\> MeshTransformer** Load a mesh from a *OFF* content string as *ezdxf.render.MeshTransformer* instance. - **Raises** *ParsingError* – vertex or face parsing error - **ezdxf.addons.meshex.obj\_readfile(filename: str \| PathLike) -\> list\[MeshTransformer\]** Read *OBJ* file content as list of *ezdxf.render.MeshTransformer* instances. - **Raises** *ParsingError* – vertex or face parsing error - **ezdxf.addons.meshex.obj\_loads(content: str) -\> list\[MeshTransformer\]** Load one or more meshes from an *OBJ* content string as list of *ezdxf.render.MeshTransformer* instances. - **Raises** *ParsingError* – vertex parsing error ### Export - **ezdxf.addons.meshex.stl\_dumps(mesh: MeshBuilder) -\> str** Returns the *STL* data as string for the given *mesh*. This function triangulates the meshes automatically because the *STL* format supports only triangles as faces. This function does not check if the mesh obey the *STL* format *rules*: - • The direction of the face normal is outward. - • The face vertices are listed in counter-clockwise order when looking at the object from the outside (right-hand rule). - • Each triangle must share two vertices with each of its adjacent triangles. - • The object represented must be located in the all-positive octant (non-negative and nonzero). - **ezdxf.addons.meshex.stl\_dumpb(mesh: MeshBuilder) -\> bytes** Returns the *STL* binary data as bytes for the given *mesh*. For more information see function: *stl\_dumps()* - **ezdxf.addons.meshex.off\_dumps(mesh: MeshBuilder) -\> str** Returns the *OFF* data as string for the given *mesh*. The *OFF* format supports ngons as faces. - **ezdxf.addons.meshex.obj\_dumps(mesh: MeshBuilder) -\> str** Returns the *OBJ* data as string for the given *mesh*. The *OBJ* format supports ngons as faces. - **ezdxf.addons.meshex.ply\_dumpb(mesh: MeshBuilder) -\> bytes** Returns the *PLY* binary data as bytes for the given *mesh*. The *PLY* format supports ngons as faces. - **ezdxf.addons.meshex.scad\_dumps(mesh: MeshBuilder) -\> str** Returns the *OpenSCAD* *polyhedron* definition as string for the given *mesh*. *OpenSCAD* supports ngons as faces. **IMPORTANT:** *OpenSCAD* requires the face normals pointing inwards, the method *flip\_normals()* of the *MeshBuilder* class can flip the normals inplace. - **ezdxf.addons.meshex.ifc4\_dumps(mesh: MeshBuilder, entity\_type=IfcEntityType.POLYGON\_FACE\_SET, \*, layer: str = 'MeshExport', color: tuple\[float, float, float\] = (1.0, 1.0, 1.0)) -\> str** Returns the *IFC4* string for the given *mesh*. The caller is responsible for checking if the mesh is a closed or open surface (e.g. **mesh.diagnose().euler\_characteristic == 2**) and using the appropriate entity type. - **Parameters** - • **mesh** – *MeshBuilder* - • **entity\_type** – *IfcEntityType* - • **layer** – layer name as string - • **color** – entity color as RGB tuple, values in the range \[0,1\] **WARNING:** *IFC4* is a very complex data format and this is a minimal effort exporter, so the exported data may not be importable by all CAD applications. The exported *IFC4* data can be imported by the following applications: - • BricsCAD - • FreeCAD (IfcOpenShell) - • Allplan - • Tekla BIMsight - **ezdxf.addons.meshex.export\_ifcZIP(filename: str \| PathLike, mesh: MeshBuilder, entity\_type=IfcEntityType.POLYGON\_FACE\_SET, \*, layer: str = 'MeshExport', color: tuple\[float, float, float\] = (1.0, 1.0, 1.0))** Export the given *mesh* as zip-compressed *IFC4* file. The filename suffix should be **.ifcZIP**. For more information see function *ifc4\_dumps()*. - **Parameters** - • **filename** – zip filename, the data file has the same name with suffix **.ifc** - • **mesh** – *MeshBuilder* - • **entity\_type** – *IfcEntityType* - • **layer** – layer name as string - • **color** – entity color as RGB tuple, values in the range \[0,1\] - **Raises** **IOError** – IO error when opening the zip-file for writing - **class ezdxf.addons.meshex.IfcEntityType(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **POLYGON\_FACE\_SET** “SurfaceModel” representation usable for open or closed surfaces. - **CLOSED\_SHELL** “Brep” representation usable for closed surfaces. - **OPEN\_SHELL** “SurfaceModel” representation usable for open surfaces. ### OpenSCAD Interface to the *OpenSCAD* application to apply boolean operations to *MeshBuilder* objects. For more information about boolean operations read the documentation of *OpenSCAD*. The *OpenSCAD* application is not bundled with *ezdxf*, you need to install the application yourself. On Windows the path to the **openscad.exe** executable is stored in the config file (see *ezdxf.options*) in the “openscad-addon” section as key “win\_exec\_path”, the default entry is: ``` [openscad-addon] win_exec_path = "C:\Program Files\OpenSCAD\openscad.exe" ``` On Linux and macOS the **openscad** command is located by the **shutil.which()** function. Example: ``` import ezdxf from ezdxf.render import forms from ezdxf.addons import MengerSponge, openscad doc = ezdxf.new() msp = doc.modelspace() # 1. create the meshes: sponge = MengerSponge(level=3).mesh() sponge.flip_normals() # important for OpenSCAD sphere = forms.sphere( count=32, stacks=16, radius=0.5, quads=True ).translate(0.25, 0.25, 1) sphere.flip_normals() # important for OpenSCAD # 2. create the script: script = openscad.boolean_operation(openscad.DIFFERENCE, sponge, sphere) # 3. execute the script by OpenSCAD: result = openscad.run(script) # 4. render the MESH entity: result.render_mesh(msp) doc.set_modelspace_vport(6, center=(5, 0)) doc.saveas("OpenSCAD.dxf") ``` \[image\] ### Functions - **ezdxf.addons.openscad.run(script: str, exec\_path: str \| None = None) -\> MeshTransformer** Executes the given *script* by OpenSCAD and returns the result mesh as *MeshTransformer*. - **Parameters** - • **script** – the OpenSCAD script as string - • **exec\_path** – path to the executable as string or **None** to use the default installation path - **ezdxf.addons.openscad.boolean\_operation(op: Operation, mesh1: MeshBuilder, mesh2: MeshBuilder) -\> str** Returns an *OpenSCAD* script to apply the given boolean operation to the given meshes. The supported operations are: - • UNION - • DIFFERENCE - • INTERSECTION - **ezdxf.addons.openscad.is\_installed() -\> bool** Returns **True** if OpenSCAD is installed. Searches on Windows the path stored in the options as “win\_exec\_path” in section “\[openscad-addon\]” which is “C:Program FilesOpenSCADopenscad.exe” by default. Searches the “openscad” command on Linux and macOS. ### Script Class - **class ezdxf.addons.openscad.Script** Helper class to build OpenSCAD scripts. This is a very simple string building class and does no checks at all! If you need more advanced features to build OpenSCAD scripts look at the packages *solidpython2* and *openpyscad*. - **add(data: str) -\> None** Add a string. - **add\_mirror(v: *UVec*) -\> None** Add a **mirror()** operation. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Transformations#mirror* - **Parameters** **v** – the normal vector of a plane intersecting the origin through which to mirror the object - **add\_multmatrix(m: *Matrix44*) -\> None** Add a transformation matrix of type *Matrix44* as **multmatrix()** operation. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Transformations#multmatrix* - **add\_polyhedron(mesh: MeshBuilder) -\> None** Add *mesh* as **polyhedron()** command. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Primitive\_Solids#polyhedron* - **add\_polygon(path: Iterable\[*UVec*\], holes: Sequence\[Iterable\[*UVec*\]\] \| None = None) -\> None** Add a **polygon()** command. This is a 2D command, all z-axis values of the input vertices are ignored and all paths and holes are closed automatically. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Using\_the\_2D\_Subsystem#polygon* - **Parameters** - • **path** – exterior path - • **holes** – a sequence of one or more holes as vertices, or **None** for no holes - **add\_resize(nx: float, ny: float, nz: float, auto: bool \| tuple\[bool, bool, bool\] \| None = None) -\> None** Add a **resize()** operation. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Transformations#resize* - **Parameters** - • **nx** – new size in x-axis - • **ny** – new size in y-axis - • **nz** – new size in z-axis - • **auto** – If the *auto* argument is set to **True**, the operation auto-scales any 0-dimensions to match. Set the *auto* argument as a 3-tuple of bool values to auto-scale individual axis. - **add\_rotate(ax: float, ay: float, az: float) -\> None** Add a **rotation()** operation. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Transformations#rotate* - **Parameters** - • **ax** – rotation about the x-axis in degrees - • **ay** – rotation about the y-axis in degrees - • **az** – rotation about the z-axis in degrees - **add\_rotate\_about\_axis(a: float, v: *UVec*) -\> None** Add a **rotation()** operation about the given axis *v*. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Transformations#rotate* - **Parameters** - • **a** – rotation angle about axis *v* in degrees - • **v** – rotation axis as *ezdxf.math.UVec* object - **add\_scale(sx: float, sy: float, sz: float) -\> None** Add a **scale()** operation. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Transformations#scale* - **Parameters** - • **sx** – scaling factor for the x-axis - • **sy** – scaling factor for the y-axis - • **sz** – scaling factor for the z-axis - **add\_translate(v: *UVec*) -\> None** Add a **translate()** operation. OpenSCAD docs: *https://en.wikibooks.org/wiki/OpenSCAD\_User\_Manual/Transformations#translate* - **Parameters** **v** – translation vector - **get\_string() -\> str** Returns the OpenSCAD build script. ### Boolean Operation Constants - **ezdxf.addons.openscad.UNION** - **ezdxf.addons.openscad.DIFFERENCE** - **ezdxf.addons.openscad.INTERSECTION** ### openpyscad This add-on is not a complete wrapper around *OpenSCAD*, if you need such a tool look at the *openpyscad* or *solidpython2* packages at PyPI. Not sure if the *openpyscad* package is still maintained, the last commit at *github* is more than a year old and did not pass the CI process! (state June 2022) This code snippet shows how to get the *MeshTransformer* object from the basic *openpyscad* example: ``` from ezdxf.addons import openscad import openpyscad as ops c1 = ops.Cube([10, 20, 10]) c2 = ops.Cube([20, 10, 10]) # dump OpenSCAD script as string: script = (c1 + c2).dumps() # execute script and load the result as MeshTransformer instance: mesh = openscad.run(script) ``` Create an *openpyscad* **Polyhedron** object from an *ezdxf* *MeshBuilder* object: ``` from ezdxf.render import forms import openpyscad as ops # create an ezdxf MeshBuilder() object sphere = forms.sphere() sphere.flip_normals() # required for OpenSCAD # create an openpyscad Polyhedron() object polyhedron = ops.Polyhedron( points=[list(p) for p in sphere.vertices], # convert Vec3 objects to lists! faces=[list(f) for f in sphere.faces], # convert face tuples to face lists! ) # create the OpenSCAD script: script = polyhedron.dumps() ``` The type conversion is needed to get valid *OpenSCAD* code from *openpyscad*! ### solidpython2 The *solidpython2* package seems to be better maintained than the *openpyscad* package, but this is just an opinion based on newer commits at github (*link*) for the *solidpython2* package. Same example for *solidpython2*: ``` from ezdxf.addons import openscad from solid2 import cube, scad_render c1 = cube([10, 20, 10]) c2 = cube([20, 10, 10]) # dump OpenSCAD script as string: script = scad_render(c1 + c2) # execute script and load the result as MeshTransformer instance: mesh = openscad.run(script) ``` Create a *solidpython2* **polyhedron** object from an *ezdxf* *MeshBuilder* object: ``` from ezdxf.render import forms from solid2 import polyhedron, scad_render # create an ezdxf MeshBuilder() object sphere = forms.sphere() sphere.flip_normals() # required for OpenSCAD # create a solidpython2 polyhedron() object ph = polyhedron( points=[v.xyz for v in sphere.vertices], # convert Vec3 objects to tuples! faces=sphere.faces, # types are compatible ) # create the OpenSCAD script: script = scad_render(ph) ``` ### TablePainter This is an add-on for drawing tables build from DXF primitives. This add-on was created for porting **dxfwrite** projects to **ezdxf** and was not officially documented for **ezdxf** versions prior the 1.0 release. For the 1.0 version of **ezdxf**, this class was added as an officially documented add-on because full support for the ACAD\_TABLE entity is very unlikely due to the enormous complexity for both the entity itself, and for the required infrastructure and also the lack of a usable documentation to implement all that features. **IMPORTANT:** This add-on is not related to the ACAD\_TABLE entity at all and and does not create ACAD\_TABLE entities! The table cells can contain multi-line text or BLOCK references. You can create your own cell types by extending the *CustomCell* class. The cells are addressed by zero-based row and column indices. A table cell can span over multiple columns and/or rows. A *TextCell* can contain multi-line text with an arbitrary rotation angle or letters stacked from top to bottom. The *MTextSurrogate* add-on is used to create multi-line text compatible to DXF version R12. A *BlockCell* contains block references (INSERT entities), if the block definition contains attribute definitions as ATTDEF entities, these attributes can be added automatically to the block reference as ATTRIB entities. **NOTE:** The DXF format does not support clipping boxes ot paths, therefore the render method of any cell can render beyond the borders of the cell! ### Tutorial Set up a new DXF document: ``` import ezdxf from ezdxf.enums import MTextEntityAlignment from ezdxf.addons import TablePainter doc = ezdxf.new("R2000") # required for lineweight support doc.header["$LWDISPLAY"] = 1 # show lineweights doc.styles.add("HEAD", font="OpenSans-ExtraBold.ttf") doc.styles.add("CELL", font="OpenSans-Regular.ttf") ``` Create a new *TablePainter* object with four rows and four columns, the insert location is the default render location but can be overriden in the **render()** method: ``` table = TablePainter( insert=(0, 0), nrows=4, ncols=4, cell_width=6.0, cell_height=2.0 ) ``` Create a new *CellStyle* object for the table-header called “head”: ``` table.new_cell_style( "head", text_style="HEAD", text_color=ezdxf.colors.BLUE, char_height=0.7, bg_color=ezdxf.colors.LIGHT_GRAY, align=MTextEntityAlignment.MIDDLE_CENTER, ) ``` Redefine the default *CellStyle* for the content cells: ``` # reset default cell style default_style = table.get_cell_style("default") default_style.text_style = "CELL" default_style.char_height = 0.5 default_style.align = MTextEntityAlignment.BOTTOM_LEFT ``` Set the table-header content: ``` for col in range(4): table.text_cell(0, col, f"Head[{col}]", style="head") ``` Set the cell content: ``` for row in range(1, 4): for col in range(4): # cell style is "default" table.text_cell(row, col, f"Cell[{row}, {col}]") ``` Add a red frame around the table-header: ``` # new cell style is required red_frame = table.new_cell_style("red-frame") red_borderline = table.new_border_style(color=ezdxf.colors.RED, lineweight=35) # set the red borderline style for all cell borders red_frame.set_border_style(red_borderline) # create the frame object table.frame(0, 0, 4, style="red-frame") ``` Render the table into the modelspace and export the DXF file: ``` # render the table, shifting the left-bottom of the table to the origin: table.render(doc.modelspace(), insert=(0, table.table_height)) th = table.table_height tw = table.table_width doc.set_modelspace_vport(height=th * 1.5, center=(tw/2, th/2)) doc.saveas("table_tutorial.dxf") ``` \[image\] **SEE ALSO:** - • Example script: *table\_painter\_addon.py* ### TablePainter - **class ezdxf.addons.tablepainter.TablePainter(insert: *UVec*, nrows: int, ncols: int, cell\_width=DEFAULT\_CELL\_WIDTH, cell\_height=DEFAULT\_CELL\_HEIGHT, default\_grid=True)** The TablePainter class renders tables build from DXF primitives. The TablePainter instance contains all the data cells. - **Parameters** - • **insert** – insert location as or *UVec* - • **nrows** – row count - • **ncols** – column count - • **cell\_width** – default cell width in drawing units - • **cell\_height** – default cell height in drawing units - • **default\_grid** – draw a grid of solid lines if **True**, otherwise draw only explicit defined borders, the default grid has a priority of 50. - **bg\_layer\_name: str** background layer name, layer for the background SOLID entities, default is “TABLEBACKGROUND” - **fg\_layer\_name: str** foreground layer name, layer for the cell content, default is “TABLECONTENT” - **grid\_layer\_name: str** table grid layer name, layer for the cell border lines, default is “TABLEGRID” - **property table\_width: float** Returns the total table width. - **property table\_height: float** Returns the total table height. - **set\_col\_width(index: int, value: float)** Set column width in drawing units of the given column index. - **Parameters** - • **index** – zero based column index - • **value** – new column width in drawing units - **set\_row\_height(index: int, value: float)** Set row height in drawing units of the given row index. - **Parameters** - • **index** – zero based row index - • **value** – new row height in drawing units - **text\_cell(row: int, col: int, text: str, span: tuple\[int, int\] = (1, 1), style='default') -\> *TextCell*** Factory method to create a new text cell at location (row, col), with *text* as content, the *text* can be a line breaks **'\\n'**. The final cell can spread over several cells defined by the argument *span*. - **block\_cell(row: int, col: int, blockdef: *BlockLayout*, span: tuple\[int, int\] = (1, 1), attribs=None, style='default') -\> *BlockCell*** Factory method to Create a new block cell at position (row, col). Content is a block reference inserted by an INSERT entity, attributes will be added if the block definition contains ATTDEF. Assignments are defined by attribs-key to attdef-tag association. Example: attribs = {‘num’: 1} if an ATTDEF with tag==’num’ in the block definition exists, an attrib with text=str(1) will be created and added to the insert entity. The cell spans over ‘span’ cells and has the cell style with the name ‘style’. - **set\_cell(row: int, col: int, cell: T) -\> T** Insert a cell at position (row, col). - **get\_cell(row: int, col: int) -\> *Cell*** Get cell at location (row, col). - **new\_cell\_style(name: str, \*\*kwargs) -\> *CellStyle*** Factory method to create a new *CellStyle* object, overwrites an already existing cell style. - **Parameters** - • **name** – style name as string - • **kwargs** – see attributes of class *CellStyle* - **get\_cell\_style(name: str) -\> *CellStyle*** Get cell style by name. - **static new\_border\_style(color: int = const.BYLAYER, status=True, priority: int = 100, linetype: str = 'BYLAYER', lineweight: int = const.LINEWEIGHT\_BYLAYER) -\> *BorderStyle*** Factory method to create a new border style. - **Parameters** - • **status** – **True** for visible, **False** for invisible - • **color** – *AutoCAD Color Index (ACI)* - • **linetype** – linetype name, default is “BYLAYER” - • **lineweight** – lineweight as int, default is by layer - • **priority** – drawing priority, higher priorities cover lower priorities - **frame(row: int, col: int, width: int = 1, height: int = 1, style='default') -\> Frame** Creates a frame around the give cell area, starting at (row, col) and covering *width* columns and *height* rows. The *style* argument is the name of a *CellStyle*. - **render(layout: GenericLayoutType, insert: *UVec* \| None = None)** Render table to layout. ### Cell - **class ezdxf.addons.tablepainter.Cell** Abstract base class for table cells. ### TextCell - **class ezdxf.addons.tablepainter.TextCell** Implements a cell type containing a multi-line text. Uses the *MTextSurrogate* add-on to render the multi-line text, therefore the content of these cells is compatible to DXF R12. **IMPORTANT:** Use the factory method *TablePainter.text\_cell()* to instantiate text cells. ### BlockCell - **class ezdxf.addons.tablepainter.BlockCell(table: *TablePainter*, blockdef: *BlockLayout*, style='default', attribs=None, span: tuple\[int, int\] = (1, 1))** Implements a cell type containing a block reference. - **Parameters** - • **table** – table object - • **blockdef** – *ezdxf.layouts.BlockLayout* instance - • **attribs** – BLOCK attributes as (tag, value) dictionary - • **style** – cell style name as string - • **span** – tuple(rows, cols) area of cells to cover Implements a cell type containing a block reference. **IMPORTANT:** Use the factory method *TablePainter.block\_cell()* to instantiate block cells. ### CustomCell - **class ezdxf.addons.tablepainter.CustomCell** Base class to implement custom cells. Overwrite the *render()* method to render the cell. The custom cell type has to be instantiated by the user and added to the table by the *TablePainter.set\_cell()* method. - **render(layout: GenericLayoutType, coords: Sequence\[float\], layer: str)** Renders the cell content into the given *layout*. The render space is defined by the argument *coords* which is a tuple of 4 float values in the order: left, right, top, bottom. These values are layout coordinates in drawing units. The DXF format does not support clipping boxes, therefore the render method can render beyond these borders! ### CellStyle - **class ezdxf.addons.tablepainter.CellStyle(data: dict\[str, Any\] \| None = None)** Cell style object. **IMPORTANT:** Always instantiate new styles by the factory method: *TablePainter.new\_cell\_style()* - **text\_style: str** *Textstyle* name as string, ignored by *BlockCell* - **char\_height: float** text height in drawing units, ignored by *BlockCell* - **line\_spacing: float** line spacing in percent, distance of line base points = **char\_height** \* **line\_spacing**, ignored by *BlockCell* - **scale\_x: float** text stretching factor (width factor) or block reference x-scaling factor - **scale\_y: float** block reference y-scaling factor, ignored by *TextCell* - **text\_color: int** *AutoCAD Color Index (ACI)* for text, ignored by *BlockCell* - **rotation: float** text or block rotation in degrees - **stacked: bool** Stacks letters of *TextCell* instances from top to bottom without rotating the characters if **True**, ignored by *BlockCell* - **align: MTextEntityAlignment** text and block alignment, see *ezdxf.enums.MTextEntityAlignment* - **margin\_x: float** left and right cell margin in drawing units - **margin\_y: float** top and bottom cell margin in drawing units - **bg\_color: int** cell background color as *AutoCAD Color Index (ACI)*, ignored by *BlockCell* - **left: BorderStyle** left cell border style - **top: BorderStyle** top cell border style - **right: BorderStyle** right cell border style - **bottom: BorderStyle** bottom cell border style - **set\_border\_status(left=True, right=True, top=True, bottom=True)** Set status of all cell borders at once. - **set\_border\_style(style: *BorderStyle*, left=True, right=True, top=True, bottom=True)** Set border styles of all cell borders at once. - **static get\_default\_border\_style() -\> *BorderStyle*** ### BorderStyle - **class ezdxf.addons.tablepainter.BorderStyle(status: bool = DEFAULT\_BORDER\_STATUS, color: int = DEFAULT\_BORDER\_COLOR, linetype: str = DEFAULT\_BORDER\_LINETYPE, lineweight=const.LINEWEIGHT\_BYLAYER, priority: int = DEFAULT\_BORDER\_PRIORITY)** Border style class. **IMPORTANT:** Always instantiate new border styles by the factory method: *TablePainter.new\_border\_style()* - **status: bool** border status, **True** for visible, **False** for hidden - **color: int** *AutoCAD Color Index (ACI)* - **linetype: str** linetype name as string, default is “BYLAYER” - **lineweight: int** lineweight as int, default is by layer - **priority: int** drawing priority, higher values cover lower values ### MTextSurrogate for DXF R12 - **class ezdxf.addons.MTextSurrogate(text: str, insert: *UVec*, line\_spacing: float = 1.5, align=MTextEntityAlignment.TOP\_LEFT, char\_height: float = 1.0, style='STANDARD', oblique: float = 0.0, rotation: float = 0.0, width\_factor: float = 1.0, mirror=Mirror.NONE, layer='0', color: int = const.BYLAYER)** MTEXT surrogate for DXF R12 build up by TEXT Entities. This add-on was added to simplify the transition from **dxfwrite** to **ezdxf**. The rich-text formatting capabilities for the regular MTEXT entity are not supported, if these features are required use the regular MTEXT entity and the *MTextExplode* add-on to explode the MTEXT entity into DXF primitives. **IMPORTANT:** The align-point is always the insert-point, there is no need for a second align-point because the horizontal alignments FIT, ALIGN, BASELINE\_MIDDLE are not supported. - **Parameters** - • **text** – content as string - • **insert** – insert location in drawing units - • **line\_spacing** – line spacing in percent of height, 1.5 = 150% = 1+1/2 lines - • **align** – text alignment as *MTextEntityAlignment* enum - • **char\_height** – text height in drawing units - • **style** – *Textstyle* name as string - • **oblique** – oblique angle in degrees, where 0 is vertical - • **rotation** – text rotation angle in degrees - • **width\_factor** – text width factor as float - • **mirror** – **MTextSurrogate.MIRROR\_X** to mirror the text horizontal or **MTextSurrogate.MIRROR\_Y** to mirror the text vertical - • **layer** – layer name as string - • **color** – *AutoCAD Color Index (ACI)* - **render(layout: GenericLayoutType) -\> None** Render the multi-line content as separated TEXT entities into the given *layout* instance. ### ASTM-D6673-10 Exporter This add-on creates special DXF files for use by Gerber Technology applications which have a low quality DXF parser and cannot parse/ignore BLOCKS which do not contain data according the ASTM-D6673-10 standard. The function *export\_file()* exports DXF R12 and only DXF R12 files which do not contain the default “$MODEL\_SPACE” and “$PAPER\_SPACE” layout block definitions, have an empty HEADER section and no TABLES section. These special requirements of the Gerber Technology parser are annoying, but correspond to the DXF R12 standard. Autodesk applications maybe complain about invalid BLOCK names such as “Shape 0\_M”, which in my opinion are valid, maybe spaces were not allowed in the original R12 version, but this is just a minor issue and is more a problem of the picky Autodesk DXF parser, which is otherwise very forgiving for DXF R12 files. ``` import ezdxf from ezdxf.addons import gerber_D6673 doc = ezdxf.new("R12") # the export function rejects other DXF versions msp = doc.modelspace() # Create your content according the ASTM-D6673-10 standard # Do not use any linetypes or text styles, the TABLES section will not be exported. # The ASTM-D6673-10 standard supports only 7-bit ASCII characters. gerber_D6673.export_file(doc, "gerber_file.dxf") ``` - **ezdxf.addons.gerber\_D6673.export\_file(doc: *Drawing*, filename: str \| PathLike) -\> None** Exports the specified DXF R12 document, which should contain content conforming to the ASTM-D6673-10 standard, in a special way so that Gerber Technology applications can parse it by their low-quality DXF parser. - **ezdxf.addons.gerber\_D6673.export\_stream(doc: *Drawing*, stream: TextIO) -\> None** Exports the specified DXF R12 document into a *stream* object. ## REFERENCE The *DXF Reference* is online available at *Autodesk*. Quoted from the original DXF 12 Reference which is not available on the web: Since the AutoCAD drawing database (.dwg file) is written in a compact format that changes significantly as new features are added to AutoCAD, we do not document its format and do not recommend that you attempt to write programs to read it directly. To assist in interchanging drawings between AutoCAD and other programs, a Drawing Interchange file format (DXF) has been defined. All implementations of AutoCAD accept this format and are able to convert it to and from their internal drawing file representation. ### DXF Document ### Document Management ### Create New Drawings - **ezdxf.new(dxfversion='AC1027', setup=False, units=6) -\> *Drawing*** Create a new **Drawing** from scratch, *dxfversion* can be either “AC1009” the official DXF version name or “R12” the AutoCAD release name. *new()* can create drawings for following DXF versions: | | | | --- | --- | | Version | AutoCAD Release | | AC1009 | AutoCAD R12 | | AC1015 | AutoCAD R2000 | | AC1018 | AutoCAD R2004 | | AC1021 | AutoCAD R2007 | | AC1024 | AutoCAD R2010 | | AC1027 | AutoCAD R2013 | | AC1032 | AutoCAD R2018 | The *units* argument defines th document and modelspace units. The header variable $MEASUREMENT will be set according to the given *units*, 0 for inch, feet, miles, … and 1 for metric units. For more information go to module *ezdxf.units* - **Parameters** - • **dxfversion** – DXF version specifier as string, default is “AC1027” respectively “R2013” - • **setup** – setup default styles, **False** for no setup, **True** to setup everything or a list of topics as strings, e.g. \[“linetypes”, “styles”\] to setup only some topics: | | | | --- | --- | | Topic | Description | | linetypes | setup line types | | styles | setup text styles | | dimstyles | setup default *ezdxf* dimension styles | | visualstyles | setup 25 standard visual styles | - • **units** – document and modelspace units, default is 6 for meters ### Open Drawings Open DXF drawings from file system or text stream, byte stream usage is not supported. DXF files prior to R2007 requires file encoding defined by header variable $DWGCODEPAGE, DXF R2007 and later requires an UTF-8 encoding. *ezdxf* supports reading of files for following DXF versions: | | | | | | --- | --- | --- | --- | | Version | Release | Encoding | Remarks | | \< AC1009 | | $DWGCODEPAGE | pre AutoCAD R12 upgraded to AC1009 | | AC1009 | R12 | $DWGCODEPAGE | AutoCAD R12 | | AC1012 | R13 | $DWGCODEPAGE | AutoCAD R13 upgraded to AC1015 | | AC1014 | R14 | $DWGCODEPAGE | AutoCAD R14 upgraded to AC1015 | | AC1015 | R2000 | $DWGCODEPAGE | AutoCAD R2000 | | AC1018 | R2004 | $DWGCODEPAGE | AutoCAD R2004 | | AC1021 | R2007 | UTF-8 | AutoCAD R2007 | | AC1024 | R2010 | UTF-8 | AutoCAD R2010 | | AC1027 | R2013 | UTF-8 | AutoCAD R2013 | | AC1032 | R2018 | UTF-8 | AutoCAD R2018 | - **ezdxf.readfile(filename: str \| PathLike, encoding: str \| None = None, errors: str = 'surrogateescape') -\> *Drawing*** Read the DXF document *filename* from the file-system. This is the preferred method to load existing ASCII or Binary DXF files, the required text encoding will be detected automatically and decoding errors will be ignored. Override encoding detection by setting argument *encoding* to the estimated encoding. (use Python encoding names like in the **open()** function). If this function struggles to load the DXF document and raises a **DXFStructureError** exception, try the *ezdxf.recover.readfile()* function to load this corrupt DXF document. - **Parameters** - • **filename** – filename of the ASCII- or Binary DXF document - • **encoding** – use **None** for auto detect (default), or set a specific encoding like “utf-8”, argument is ignored for Binary DXF files - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • **IOError** – not a DXF file or file does not exist - • *DXFStructureError* – for invalid or corrupted DXF structures - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs - **ezdxf.read(stream: TextIO) -\> *Drawing*** Read a DXF document from a text-stream. Open stream in text mode (**mode='rt'**) and set correct text encoding, the stream requires at least a **readline()** method. Since DXF version R2007 (AC1021) file encoding is always “utf-8”, use the helper function **dxf\_stream\_info()** to detect the required text encoding for prior DXF versions. To preserve possible binary data in use **errors='surrogateescape'** as error handler for the import stream. If this function struggles to load the DXF document and raises a **DXFStructureError** exception, try the *ezdxf.recover.read()* function to load this corrupt DXF document. - **Parameters** **stream** – input text stream opened with correct encoding - **Raises** *DXFStructureError* – for invalid or corrupted DXF structures - **ezdxf.readzip(zipfile: str \| PathLike, filename: str \| None = None, errors: str = 'surrogateescape') -\> *Drawing*** Load a DXF document specified by *filename* from a zip archive, or if *filename* is **None** the first DXF document in the zip archive. - **Parameters** - • **zipfile** – name of the zip archive - • **filename** – filename of DXF file, or **None** to load the first DXF document from the zip archive. - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • **IOError** – not a DXF file or file does not exist or\ if *filename* is **None** - no DXF file found - • *DXFStructureError* – for invalid or corrupted DXF structures - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs - **ezdxf.decode\_base64(data: bytes, errors: str = 'surrogateescape') -\> *Drawing*** Load a DXF document from base64 encoded binary data, like uploaded data to web applications. - **Parameters** - • **data** – DXF document base64 encoded binary data - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • *DXFStructureError* – for invalid or corrupted DXF structures - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs **HINT:** This works well with DXF files from trusted sources like AutoCAD or BricsCAD, for loading DXF files with minor or major flaws look at the *ezdxf.recover* module. ### Save Drawings Save the DXF document to the file system by *Drawing* methods *save()* or *saveas()*. Write the DXF document to a text stream with *write()*, the text stream requires at least a **write()** method. Get required output encoding for text streams by property **Drawing.output\_encoding** ### Drawing Settings The *HeaderSection* stores meta data like modelspace extensions, user name or saving time and current application settings, like actual layer, text style or dimension style settings. These settings are not necessary to process DXF data and therefore many of this settings are not maintained by *ezdxf* automatically. ### Header variables set at new | | | | --- | --- | | $ACADVER | DXF version | | $TDCREATE | date/time at creating the drawing | | $FINGERPRINTGUID | every drawing gets a GUID | ### Header variables updated at saving | | | | --- | --- | | $TDUPDATE | actual date/time at saving | | $HANDSEED | next available handle as hex string | | $DWGCODEPAGE | encoding setting | | $VERSIONGUID | every saved version gets a new GUID | **SEE ALSO:** - • Howto: *Set/Get Header Variables* - • Howto: *Set DXF Drawing Units* ### Ezdxf Metadata Store internal metadata like *ezdxf* version and creation time for a new created document as metadata in the DXF file. Only standard DXF features are used to store meta data and this meta data is preserved by Autodesk products, BricsCAD and of course *ezdxf*. Other 3rd party DXF libraries may remove this meta data. For DXF R12 the meta data is stored as XDATA by AppID **EZDXF** in the model space BLOCK entity in the BLOCKS section. For DXF R2000+ the meta data is stored in the “root” DICTIONARY in the OBJECTS section as a DICTIONARY object by the key **EZDXF\_META**. The **MetaData** object has a dict-like interface and can also store custom metadata: ``` metadata = doc.ezdxf_metadata() # set data metadata["MY_CUSTOM_META_DATA"] = "a string with max. length of 254" # get data, raises a KeyError() if key not exist value = metadata["MY_CUSTOM_META_DATA"] # get data, returns an empty string if key not exist value = metadata.get("MY_CUSTOM_META_DATA") # delete entry, raises a KeyError() if key not exist del metadata["MY_CUSTOM_META_DATA"] # discard entry, does not raise a KeyError() if key not exist metadata.discard("MY_CUSTOM_META_DATA") ``` Keys and values are limited to strings with a max. length of 254 characters and line ending **\\n** will be replaced by **\\P**. Keys used by *ezdxf*: - • **WRITTEN\_BY\_EZDXF**: *ezdxf* version and UTC time in ISO format - • **CREATED\_BY\_EZDXF**: *ezdxf* version and UTC time in ISO format Example of the ezdxf marker string: **0.16.4b1 @ 2021-06-12T07:35:34.898808+00:00** - **class ezdxf.document.MetaData** - **abstract MetaData.\_\_contains\_\_(key: str) -\> bool** Returns *key* **in** self. - **abstract MetaData.\_\_getitem\_\_(key: str) -\> str** Returns the value for self\[*key*\]. - **Raises** **KeyError** – *key* does not exist - **MetaData.get(key: str, default: str = '') -\> str** Returns the value for *key*. Returns *default* if *key* not exist. - **abstract MetaData.\_\_setitem\_\_(key: str, value: str) -\> None** Set self\[*key*\] to *value*. - **abstract MetaData.\_\_delitem\_\_(key: str) -\> None** Delete self\[*key*\]. - **Raises** **KeyError** – *key* does not exist - **MetaData.discard(key: str) -\> None** Remove *key*, does **not** raise an exception if *key* not exist. ### Export/Load JSON Encoded Tags Tag format of DXF documents: ``` 0 SECTION 2 HEADER 9 $ACADVER 1 AC1027 ... 9 $LIMMIN 10 0.0 20 0.0 9 $LIMMAX 10 420.0 20 297.0 9 $ORTHOMODE 70 0 9 $REGENMODE 70 1 ... 0 EOF ``` The *compact* format is a list of **\[group-code, value\]** pairs where each pair is a DXF tag. The group-code has to be an integer and the value has to be a string, integer, float or list of floats for vertices. ``` [ [0, "SECTION"], [2, "HEADER"], [9, "$ACADVER"], [1, "AC1027"], ... [9, "$LIMMIN"], [10, [0.0,0.0]], [9, "$LIMMAX"], [10, [420.0,297.0]], [9, "$ORTHOMODE"], [70, 0], [9, "$REGENMODE"], [70, 1] ... [0, "EOF"] ] ``` The *verbose* format (*compact* is **False**) is a list of **\[group-code, value\]** pairs where each pair is a 1:1 representation of a DXF tag. The group-code has to be an integer and the value has to be a string. ``` [ [0, "SECTION"], [2, "HEADER"], [9, "$ACADVER"], [1, "AC1027"], ... [9, "$LIMMIN"], [10, "0.0"], [20, "0.0"], [9, "$LIMMAX"], [10, "420.0"], [20, "297.0"], [9, "$ORTHOMODE"], [70, "0"], [9, "$REGENMODE"], [70, "1"], ... [0, "EOF"] ] ``` - **ezdxf.document.export\_json\_tags(doc: *Drawing*, compact=True) -\> str** Export a DXF document as JSON formatted tags. The *compact* format is a list of **\[group-code, value\]** pairs where each pair is a DXF tag. The group-code has to be an integer and the value has to be a string, integer, float or list of floats for vertices. The *verbose* format (*compact* is **False**) is a list of **\[group-code, value\]** pairs where each pair is a 1:1 representation of a DXF tag. The group-code has to be an integer and the value has to be a string. - **ezdxf.document.load\_json\_tags(data: Sequence\[Any\]) -\> *Drawing*** Load DXF document from JSON formatted tags. The expected JSON format is a list of \[group-code, value\] pairs where each pair is a DXF tag. The *compact* and the *verbose* format is supported. - **Parameters** **data** – JSON data structure as a sequence of \[group-code, value\] pairs ### Drawing Class The *Drawing* class is the central management structure of a DXF document. ### Access Layouts - • *Drawing.modelspace()* - • *Drawing.paperspace()* ### Access Resources - • Application ID Table: *Drawing.appids* - • Block Definition Table: *Drawing.blocks* - • Dimension Style Table: *Drawing.dimstyles* - • Layer Table: *Drawing.layers* - • Linetype Table: *Drawing.linetypes* - • MLeader Style Table: *Drawing.mleader\_styles* - • MLine Style Table: *Drawing.mline\_styles* - • Material Table: *Drawing.materials* - • Text Style Table: *Drawing.styles* - • UCS Table: *Drawing.ucs* - • VPort Table: *Drawing.viewports* - • View Table: *Drawing.views* - • Classes Section: *Drawing.classes* - • Object Section: *Drawing.objects* - • Entity Database: **Drawing.entitydb** - • Entity Groups: *Drawing.groups* - • Header Variables: *Drawing.header* ### Drawing Class - **class ezdxf.document.Drawing** The *Drawing* class is the central management structure of a DXF document. - **dxfversion** Actual DXF version like **'AC1009'**, set by *ezdxf.new()* or *ezdxf.readfile()*. For supported DXF versions see *Document Management* - **acad\_release** The AutoCAD release name like **'R12'** or **'R2000'** for actual *dxfversion*. - **encoding** Text encoding of *Drawing*, the default encoding for new drawings is **'cp1252'**. Starting with DXF R2007 (AC1021), DXF files are written as UTF-8 encoded text files, regardless of the attribute *encoding*. The text encoding can be changed to encodings listed below. see also: *DXF File Encoding* | | | | --- | --- | | supported | encodings | | **'cp874'** | Thai | | **'cp932'** | Japanese | | **'gbk'** | UnifiedChinese | | **'cp949'** | Korean | | **'cp950'** | TradChinese | | **'cp1250'** | CentralEurope | | **'cp1251'** | Cyrillic | | **'cp1252'** | WesternEurope | | **'cp1253'** | Greek | | **'cp1254'** | Turkish | | **'cp1255'** | Hebrew | | **'cp1256'** | Arabic | | **'cp1257'** | Baltic | | **'cp1258'** | Vietnam | - **output\_encoding** Returns required output encoding for saving to filesystem or encoding to binary data. - **filename** *Drawing* filename, if loaded by *ezdxf.readfile()* else **None**. - **rootdict** Reference to the root dictionary of the OBJECTS section. - **header** Reference to the *HeaderSection*, get/set drawing settings as header variables. - **entities** Reference to the **EntitySection** of the drawing, where all graphical entities are stored, but only from modelspace and the *active* paperspace layout. Just for your information: Entities of other paperspace layouts are stored as *BlockLayout* in the *BlocksSection*. - **objects** Reference to the objects section, see also *ObjectsSection*. - **blocks** Reference to the blocks section, see also *BlocksSection*. - **tables** Reference to the tables section, see also *TablesSection*. - **classes** Reference to the classes section, see also *ClassesSection*. - **layouts** Reference to the layout manager, see also *Layouts*. - **groups** Collection of all groups, see also *GroupCollection*. requires DXF R13 or later - **layers** Shortcut for **Drawing.tables.layers** Reference to the layers table, where you can create, get and remove layers, see also *Table* and *Layer* - **styles** Shortcut for **Drawing.tables.styles** Reference to the styles table, see also *Textstyle*. - **dimstyles** Shortcut for **Drawing.tables.dimstyles** Reference to the dimstyles table, see also *DimStyle*. - **linetypes** Shortcut for **Drawing.tables.linetypes** Reference to the linetypes table, see also *Linetype*. - **views** Shortcut for **Drawing.tables.views** Reference to the views table, see also *View*. - **viewports** Shortcut for **Drawing.tables.viewports** Reference to the viewports table, see also *VPort*. - **ucs** Shortcut for **Drawing.tables.ucs** Reference to the ucs table, see also *UCSTableEntry*. - **appids** Shortcut for **Drawing.tables.appids** Reference to the appids table, see also *AppID*. - **materials** **MaterialCollection** of all **Material** objects. - **mline\_styles** **MLineStyleCollection** of all *MLineStyle* objects. - **mleader\_styles** **MLeaderStyleCollection** of all *MLeaderStyle* objects. - **units** Get and set the document/modelspace base units as enum, for more information read this: *DXF Units*. Requires DXF R2000 or newer. - **get\_abs\_filepath = \** - **save(encoding: str \| None = None, fmt: str = 'asc') -\> None** Write drawing to file-system by using the *filename* attribute as filename. Override file encoding by argument *encoding*, handle with care, but this option allows you to create DXF files for applications that handle file encoding different from AutoCAD. - **Parameters** - • **encoding** – override default encoding as Python encoding string like **'utf-8'** - • **fmt** – **'asc'** for ASCII DXF (default) or **'bin'** for Binary DXF - **saveas(filename: PathLike \| str, encoding: str \| None = None, fmt: str = 'asc') -\> None** Set *Drawing* attribute *filename* to *filename* and write drawing to the file system. Override file encoding by argument *encoding*, handle with care, but this option allows you to create DXF files for applications that handles file encoding different than AutoCAD. - **Parameters** - • **filename** – file name as string - • **encoding** – override default encoding as Python encoding string like **'utf-8'** - • **fmt** – **'asc'** for ASCII DXF (default) or **'bin'** for Binary DXF - **write(stream: TextIO \| BinaryIO, fmt: str = 'asc') -\> None** Write drawing as ASCII DXF to a text stream or as Binary DXF to a binary stream. For DXF R2004 (AC1018) and prior open stream with drawing *encoding* and **mode='wt'**. For DXF R2007 (AC1021) and later use **encoding='utf-8'**, or better use the later added *Drawing* property *output\_encoding* which returns the correct encoding automatically. The correct and required error handler is **errors='dxfreplace'**! If writing to a **StringIO** stream, use *Drawing.encode()* to encode the result string from **StringIO.get\_value()**: ``` binary = doc.encode(stream.get_value()) ``` - **Parameters** - • **stream** – output text stream or binary stream - • **fmt** – “asc” for ASCII DXF (default) or “bin” for binary DXF - **encode\_base64() -\> bytes** Returns DXF document as base64 encoded binary data. - **encode(s: str) -\> bytes** Encode string *s* with correct encoding and error handler. - **query(query: str = '\*') -\> *EntityQuery*** Entity query over all layouts and blocks, excluding the OBJECTS section and the resource tables of the TABLES section. - **Parameters** **query** – query string **SEE ALSO:** *Entity Query String* and *Retrieve entities by query language* - **groupby(dxfattrib='', key=None) -\> dict** Groups DXF entities of all layouts and blocks (excluding the OBJECTS section) by a DXF attribute or a key function. - **Parameters** - • **dxfattrib** – grouping DXF attribute like “layer” - • **key** – key function, which accepts a **DXFEntity** as argument and returns a hashable grouping key or **None** to ignore this entity. **SEE ALSO:** *groupby()* documentation - **modelspace() -\> Modelspace** Returns the modelspace layout, displayed as “Model” tab in CAD applications, defined by block record named “\*Model\_Space”. - **paperspace(name: str = '') -\> Paperspace** Returns paperspace layout *name* or the active paperspace if no name is given. - **Parameters** **name** – paperspace name or empty string for the active paperspace - **Raises** **KeyError** – if the modelspace was acquired or layout *name* does not exist - **layout(name: str = '') -\> *Layout*** Returns paperspace layout *name* or the first layout in tab-order if no name is given. - **Parameters** **name** – paperspace name or empty string for the first paperspace in tab-order - **Raises** **KeyError** – layout *name* does not exist - **active\_layout() -\> Paperspace** Returns the active paperspace layout, defined by block record name “\*Paper\_Space”. - **layout\_names() -\> Iterable\[str\]** Returns all layout names in arbitrary order. - **layout\_names\_in\_taborder() -\> Iterable\[str\]** Returns all layout names in tab-order, “Model” is always the first name. - **new\_layout(name, dxfattribs=None) -\> Paperspace** Create a new paperspace layout *name*. Returns a *Paperspace* object. DXF R12 (AC1009) supports only one paperspace layout, only the active paperspace layout is saved, other layouts are dismissed. - **Parameters** - • **name** – unique layout name - • **dxfattribs** – additional DXF attributes for the **DXFLayout** entity - **Raises** *DXFValueError* – paperspace layout *name* already exist - **page\_setup(name: str = 'Layout1', fmt: str = 'ISO A3', landscape=True) -\> Paperspace** Creates a new paperspace layout if *name* does not exist or reset the existing layout. This method requires DXF R2000 or newer. The paper format name *fmt* defines one of the following paper sizes, measures in landscape orientation: | | | | | | --- | --- | --- | --- | | Name | Units | Width | Height | | ISO A0 | mm | 1189 | 841 | | ISO A1 | mm | 841 | 594 | | ISO A2 | mm | 594 | 420 | | ISO A3 | mm | 420 | 297 | | ISO A4 | mm | 297 | 210 | | ANSI A | inch | 11 | 8.5 | | ANSI B | inch | 17 | 11 | | ANSI C | inch | 22 | 17 | | ANSI D | inch | 34 | 22 | | ANSI E | inch | 44 | 34 | | ARCH C | inch | 24 | 18 | | ARCH D | inch | 36 | 24 | | ARCH E | inch | 48 | 36 | | ARCH E1 | inch | 42 | 30 | | Letter | inch | 11 | 8.5 | | Legal | inch | 14 | 8.5 | The layout uses the associated units of the paper format as drawing units, has no margins or offset defined and the scale of the paperspace layout is 1:1. - **Parameters** - • **name** – paperspace layout name - • **fmt** – paper format - • **landscape** – **True** for landscape orientation, **False** for portrait orientation - **delete\_layout(name: str) -\> None** Delete paper space layout *name* and all entities owned by this layout. Available only for DXF R2000 or later, DXF R12 supports only one paperspace, and it can’t be deleted. - **add\_image\_def(filename: str, size\_in\_pixel: tuple\[int, int\], name=None)** Add an image definition to the objects section. Add an **ImageDef** entity to the drawing (objects section). *filename* is the image file name as relative or absolute path and *size\_in\_pixel* is the image size in pixel as (x, y) tuple. To avoid dependencies to external packages, *ezdxf* can not determine the image size by itself. Returns a **ImageDef** entity which is needed to create an image reference. *name* is the internal image name, if set to **None**, name is auto-generated. Absolute image paths works best for AutoCAD but not perfect, you have to update external references manually in AutoCAD, which is not possible in TrueView. If the drawing units differ from 1 meter, you also have to use: *set\_raster\_variables()*. - **Parameters** - • **filename** – image file name (absolute path works best for AutoCAD) - • **size\_in\_pixel** – image size in pixel as (x, y) tuple - • **name** – image name for internal use, None for using filename as name (best for AutoCAD) **SEE ALSO:** *Tutorial for Image and ImageDef* - **set\_raster\_variables(frame: int = 0, quality: int = 1, units: str = 'm')** Set raster variables. - **Parameters** - • **frame** – 0 = do not show image frame; 1 = show image frame - • **quality** – 0 = draft; 1 = high - • **units** – units for inserting images. This defines the real world unit for one drawing unit for the purpose of inserting and scaling images with an associated resolution. | | | | --- | --- | | mm | Millimeter | | cm | Centimeter | | m | Meter (ezdxf default) | | km | Kilometer | | in | Inch | | ft | Foot | | yd | Yard | | mi | Mile | - **set\_wipeout\_variables(frame=0)** Set wipeout variables. - **Parameters** **frame** – 0 = do not show image frame; 1 = show image frame - **add\_underlay\_def(filename: str, fmt: str = 'ext', name: str \| None = None)** Add an **UnderlayDef** entity to the drawing (OBJECTS section). The *filename* is the underlay file name as relative or absolute path and *fmt* as string (pdf, dwf, dgn). The underlay definition is required to create an underlay reference. - **Parameters** - • **filename** – underlay file name - • **fmt** – file format as string “pdf”\|”dwf”\|”dgn” or “ext” for getting file format from filename extension - • **name** – pdf format = page number to display; dgn format = “default”; dwf: ???? **SEE ALSO:** *Tutorial for Underlay and UnderlayDefinition* - **add\_xref\_def(filename: str, name: str, flags: int = BLK\_XREF \| BLK\_EXTERNAL)** Add an external reference (xref) definition to the blocks section. - **Parameters** - • **filename** – external reference filename - • **name** – name of the xref block - • **flags** – block flags - **layouts\_and\_blocks() -\> Iterator\[GenericLayoutType\]** Iterate over all layouts (modelspace and paperspace) and all block definitions. - **chain\_layouts\_and\_blocks() -\> Iterator\[*DXFEntity*\]** Chain entity spaces of all layouts and blocks. Yields an iterator for all entities in all layouts and blocks. - **reset\_fingerprint\_guid()** Reset fingerprint GUID. - **reset\_version\_guid()** Reset version GUID. - **set\_modelspace\_vport(height, center=(0, 0), \*, dxfattribs=None) -\> *VPort*** Set initial view/zoom location for the modelspace, this replaces the current “\*Active” viewport configuration (*VPort*) and reset the coordinate system to the *WCS*. - **Parameters** - • **height** – modelspace area to view - • **center** – modelspace location to view in the center of the CAD application window. - • **dxfattribs** – additional DXF attributes for the VPORT entity - **audit() -\> Auditor** Checks document integrity and fixes all fixable problems, not fixable problems are stored in **Auditor.errors**. If you are messing around with internal structures, call this method before saving to be sure to export valid DXF documents, but be aware this is a long-running task. - **validate(print\_report=True) -\> bool** Simple way to run an audit process. Fixes all fixable problems, return **False** if not fixable errors occurs. Prints a report of resolved and unrecoverable errors, if requested. - **Parameters** **print\_report** – print report to stdout Returns: **False** if unrecoverable errors exist - **ezdxf\_metadata() -\> *MetaData*** Returns the *ezdxf* *ezdxf.document.MetaData* object, which manages *ezdxf* and custom metadata in DXF files. For more information see: *Ezdxf Metadata*. ### Recover This module provides functions to “recover” ASCII DXF documents with structural flaws, which prevents the regular *ezdxf.read()* and *ezdxf.readfile()* functions to load the document. The *read()* and *readfile()* functions will repair as much flaws as possible and run the required audit process automatically afterwards and return the result of this audit process: ``` import sys import ezdxf from ezdxf import recover try: doc, auditor = recover.readfile("messy.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) # DXF file can still have unrecoverable errors, but this is maybe just # a problem when saving the recovered DXF file. if auditor.has_errors: auditor.print_error_report() ``` The loading functions also decode DXF-Unicode encoding automatically e.g. “\\U+00FC” -\> “ü”. All these efforts cost some time, loading the DXF document with *ezdxf.read()* or *ezdxf.readfile()* is faster. **WARNING:** This module will load DXF files which have decoding errors, most likely binary data stored in XRECORD entities, these errors are logged as unrecoverable **AuditError.DECODE\_ERRORS** in the **Auditor.errors** attribute, but no **DXFStructureError** exception will be raised, because for many use cases this errors can be ignored. Writing such files back with *ezdxf* may create **invalid** DXF files, or at least some **information will be lost** - handle with care! To avoid this problem use **recover.readfile(filename, errors='strict')** which raises an **UnicodeDecodeError** exception for such binary data. Catch the exception and handle this DXF files as unrecoverable. ### Loading Scenarios ### 1. It will work Mostly DXF files from AutoCAD or BricsCAD (e.g. for In-house solutions): ``` try: doc = ezdxf.readfile(name) except IOError: print(f'Not a DXF file or a generic I/O error.') sys.exit(1) except ezdxf.DXFStructureError: print(f'Invalid or corrupted DXF file: {name}.') sys.exit(2) ``` ### 2. DXF file with minor flaws DXF files have only minor flaws, like undefined resources: ``` try: doc = ezdxf.readfile(name) except IOError: print(f'Not a DXF file or a generic I/O error.') sys.exit(1) except ezdxf.DXFStructureError: print(f'Invalid or corrupted DXF file: {name}.') sys.exit(2) auditor = doc.audit() if auditor.has_errors: auditor.print_error_report() ``` ### 3. Try Hard From trusted and untrusted sources but with good hopes, the worst case works like a cache miss, you pay for the first try and pay the extra fee for the recover mode: ``` try: # Fast path: doc = ezdxf.readfile(name) except IOError: print(f'Not a DXF file or a generic I/O error.') sys.exit(1) # Catch all DXF errors: except ezdxf.DXFError: try: # Slow path including fixing low level structures: doc, auditor = recover.readfile(name) except ezdxf.DXFStructureError: print(f'Invalid or corrupted DXF file: {name}.') sys.exit(2) # DXF file can still have unrecoverable errors, but this is maybe # just a problem when saving the recovered DXF file. if auditor.has_errors: print(f'Found unrecoverable errors in DXF file: {name}.') auditor.print_error_report() ``` ### 4. Just use the slow recover module Untrusted sources and expecting many invalid or corrupted DXF files, you always pay an extra fee for the recover mode: ``` try: # Slow path including fixing low level structures: doc, auditor = recover.readfile(name) except IOError: print(f'Not a DXF file or a generic I/O error.') sys.exit(1) except ezdxf.DXFStructureError: print(f'Invalid or corrupted DXF file: {name}.') sys.exit(2) # DXF file can still have unrecoverable errors, but this is maybe # just a problem when saving the recovered DXF file. if auditor.has_errors: print(f'Found unrecoverable errors in DXF file: {name}.') auditor.print_error_report() ``` ### 5. Unrecoverable Decoding Errors If files contain binary data which can not be decoded by the document encoding, it is maybe the best to ignore these files, this works in normal and recover mode: ``` try: doc, auditor = recover.readfile(name, errors='strict') except IOError: print(f'Not a DXF file or a generic I/O error.') sys.exit(1) except ezdxf.DXFStructureError: print(f'Invalid or corrupted DXF file: {name}.') sys.exit(2) except UnicodeDecodeError: print(f'Decoding error in DXF file: {name}.') sys.exit(3) ``` ### 6. Ignore/Locate Decoding Errors Sometimes ignoring decoding errors can recover DXF files or at least you can detect where the decoding errors occur: ``` try: doc, auditor = recover.readfile(name, errors='ignore') except IOError: print(f'Not a DXF file or a generic I/O error.') sys.exit(1) except ezdxf.DXFStructureError: print(f'Invalid or corrupted DXF file: {name}.') sys.exit(2) if auditor.has_errors: auditor.print_report() ``` The error messages with code **AuditError.DECODING\_ERROR** shows the approximate line number of the decoding error: “Fixed unicode decoding error near line: xxx.” **HINT:** This functions can handle only ASCII DXF files! - **ezdxf.recover.readfile(filename: str \| *Path*, errors: str = 'surrogateescape') -\> tuple\[*Drawing*, Auditor\]** Read a DXF document from file system similar to *ezdxf.readfile()*, but this function will repair as many flaws as possible, runs the required audit process automatically the DXF document and the **Auditor**. - **Parameters** - • **filename** – file-system name of the DXF document to load - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • *DXFStructureError* – for invalid or corrupted DXF structures - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs - **ezdxf.recover.read(stream: BinaryIO, errors: str = 'surrogateescape') -\> tuple\[*Drawing*, Auditor\]** Read a DXF document from a binary-stream similar to *ezdxf.read()*, but this function will detect the text encoding automatically and repair as many flaws as possible, runs the required audit process afterwards and returns the DXF document and the **Auditor**. - **Parameters** - • **stream** – data stream to load in binary read mode - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • *DXFStructureError* – for invalid or corrupted DXF structures - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs - **ezdxf.recover.explore(filename: str \| *Path*, errors: str = 'ignore') -\> tuple\[*Drawing*, Auditor\]** Read a DXF document from file system similar to *readfile()*, but this function will use a special tag loader, which tries to recover the tag stream if invalid tags occur. This function is intended to load corrupted DXF files and should only be used to explore such files, data loss is very likely. - **Parameters** - • **filename** – file-system name of the DXF document to load - • **errors** – specify decoding error handler - • ”surrogateescape” to preserve possible binary data (default) - • ”ignore” to use the replacement char U+FFFD “�” for invalid data - • ”strict” to raise an **UnicodeDecodeError** exception for invalid data - **Raises** - • *DXFStructureError* – for invalid or corrupted DXF structures - • **UnicodeDecodeError** – if *errors* is “strict” and a decoding error occurs ### r12strict Added in version 1.1. Due to ACAD release 14 the resource names, such as layer-, linetype, text style-, dimstyle- and block names, were limited to 31 characters in length and all names were uppercase. Names can include the letters A to Z, the numerals 0 to 9, and the special characters, dollar sign **"$"**, underscore **"\_"**, hyphen **"-"** and the asterix **"\*"** as first character for special names like anonymous blocks. Most applications do not care about that and work fine with longer names and any characters used in names for some exceptions, but of course Autodesk applications are very picky about that. The function *make\_acad\_compatible()* makes DXF R12 drawings to 100% compatible to Autodesk products and does everything at once, but the different processing steps can be called manually. **IMPORTANT:** This module can only process DXF R12 file and will throw a **DXFVersionError** otherwise. For exporting any DXF document as DXF R12 use the *ezdxf.addons.r12export* add-on. ### Usage ``` import ezdxf from ezdxf import r12strict doc = ezdxf.readfile("r12sloppy.dxf") r12strict.make_acad_compatible(doc) doc.saveas("r12strict.dxf") ``` ### Functions | | | | --- | --- | | *make\_acad\_compatible* | Apply all DXF R12 requirements, so Autodesk products will load the document. | | *translate\_names* | Translate table and block names into strict DXF R12 names. | | *clean* | Removes all features that are not supported for DXF R12 by Autodesk products. | - **ezdxf.r12strict.make\_acad\_compatible(doc: *Drawing*) -\> None** Apply all DXF R12 requirements, so Autodesk products will load the document. - **ezdxf.r12strict.translate\_names(doc: *Drawing*) -\> None** Translate table and block names into strict DXF R12 names. ACAD Releases upto 14 limit names to 31 characters in length and all names are uppercase. Names can include the letters A to Z, the numerals 0 to 9, and the special characters, dollar sign ($), underscore (\_), hyphen (-) and the asterix (\*) as first character for special names like anonymous blocks. Most applications do not care about that and work fine with longer names and any characters used in names for some exceptions, but of course Autodesk applications are very picky about that. **NOTE:** This is a destructive process and modifies the internals of the DXF document. - **ezdxf.r12strict.clean(doc: *Drawing*) -\> None** Removes all features that are not supported for DXF R12 by Autodesk products. - **class ezdxf.r12strict.R12NameTranslator** Translate table and block names into strict DXF R12 names. ACAD Releases upto 14 limit names to 31 characters in length and all names are uppercase. Names can include the letters A to Z, the numerals 0 to 9, and the special characters, dollar sign ($), underscore (\_), hyphen (-) and the asterix (\*) as first character for special names like anonymous blocks. - **reset() -\> None** - **translate(name: str) -\> str** ### DXF Structures ### Sections ### Header Section The drawing settings are stored in the HEADER section, which is accessible by the *header* attribute of the *Drawing* object. See the online documentation from Autodesk for available *header variables*. **SEE ALSO:** DXF Internals: *HEADER Section* - **class ezdxf.sections.header.HeaderSection** - **custom\_vars** Stores the custom drawing properties in a *CustomVars* object. - **\_\_len\_\_() -\> int** Returns count of header variables. - **\_\_contains\_\_(key) -\> bool** Returns **True** if header variable *key* exist. - **varnames() -\> KeysView** Returns an iterable of all header variable names. - **get(key: str, default: Any = None) -\> Any** Returns value of header variable *key* if exist, else the *default* value. - **\_\_getitem\_\_(key: str) -\> Any** Get header variable *key* by index operator like: **drawing.header\['$ACADVER'\]** - **\_\_setitem\_\_(key: str, value: Any) -\> None** Set header variable *key* to *value* by index operator like: **drawing.header\['$ANGDIR'\] = 1** - **\_\_delitem\_\_(key: str) -\> None** Delete header variable *key* by index operator like: **del drawing.header\['$ANGDIR'\]** - **reset\_wcs()** Reset the current UCS settings to the *WCS*. - **class ezdxf.sections.header.CustomVars** The *CustomVars* class stores custom properties in the DXF header as $CUSTOMPROPERTYTAG and $CUSTOMPROPERTY values. Custom properties require DXF R2004 or later, *ezdxf* can create custom properties for older DXF versions as well, but AutoCAD will not show that properties. - **properties** A list of custom header properties, stored as string tuples **(tag, value)**. Multiple occurrence of the same custom tag is allowed, but not well supported by the interface. This is a standard Python list and it’s safe to modify this list as long as you just use tuples of strings. - **\_\_len\_\_() -\> int** Count of custom properties. - **\_\_iter\_\_() -\> Iterator\[tuple\[str, str\]\]** Iterate over all custom properties as **(tag, value)** tuples. - **clear() -\> None** Remove all custom properties. - **get(tag: str, default: str \| None = None)** Returns the value of the first custom property *tag*. - **has\_tag(tag: str) -\> bool** Returns **True** if custom property *tag* exist. - **append(tag: str, value: str) -\> None** Add custom property as **(tag, value)** tuple. - **replace(tag: str, value: str) -\> None** Replaces the value of the first custom property *tag* by a new *value*. Raises **DXFValueError** if *tag* does not exist. - **remove(tag: str, all: bool = False) -\> None** Removes the first occurrence of custom property *tag*, removes all occurrences if *all* is **True**. Raises *:class:\`DXFValueError* if *tag* does not exist. ### Classes Section The CLASSES section in DXF files holds the information for application-defined classes whose instances appear in *Layout* objects. As usual package user there is no need to bother about CLASSES. **SEE ALSO:** DXF Internals: *CLASSES Section* - **class ezdxf.sections.classes.ClassesSection** - **classes** Storage of all *DXFClass* objects, they are not stored in the entities database, because CLASS instances do not have a handle attribute. - **register()** - **add\_class(name: str)** Register a known class by *name*. - **get(name: str) -\> DXFClass** Returns the first class matching *name*. Storage key is the **(name, cpp\_class\_name)** tuple, because there are some classes with the same **name** but different **cpp\_class\_names**. - **add\_required\_classes(dxfversion: str) -\> None** Add all required CLASS definitions for the specified DXF version. - **update\_instance\_counters() -\> None** Update CLASS instance counter for all registered classes, requires DXF R2004+. - **class ezdxf.entities.DXFClass** Information about application-defined classes. - **dxf.name** Class DXF record name. - **dxf.cpp\_class\_name** C++ class name. Used to bind with software that defines object class behavior. - **dxf.app\_name** Application name. Posted in Alert box when a class definition listed in this section is not currently loaded. - **dxf.flags** Proxy capabilities flag | | | | --- | --- | | 0 | No operations allowed (0) | | 1 | Erase allowed (0x1) | | 2 | Transform allowed (0x2) | | 4 | Color change allowed (0x4) | | 8 | Layer change allowed (0x8) | | 16 | Linetype change allowed (0x10) | | 32 | Linetype scale change allowed (0x20) | | 64 | Visibility change allowed (0x40) | | 128 | Cloning allowed (0x80) | | 256 | Lineweight change allowed (0x100) | | 512 | Plot Style Name change allowed (0x200) | | 895 | All operations except cloning allowed (0x37F) | | 1023 | All operations allowed (0x3FF) | | 1024 | Disables proxy warning dialog (0x400) | | 32768 | R13 format proxy (0x8000) | - **dxf.instance\_count** Instance count for a custom class. - **dxf.was\_a\_proxy** Set to **1** if class was not loaded when this DXF file was created, and **0** otherwise. - **dxf.is\_an\_entity** Set to **1** if class was derived from the *DXFGraphic* class and can reside in layouts. If **0**, instances may appear only in the OBJECTS section. - **key** Unique name as **(name, cpp\_class\_name)** tuple. ### Tables Section The TABLES section is the home of all TABLE objects of a DXF document. **SEE ALSO:** DXF Internals: *TABLES Section* - **class ezdxf.sections.tables.TablesSection** - **layers** *LayerTable* maintaining the *Layer* objects - **linetypes** *LinetypeTable* maintaining the *Linetype* objects - **styles** *TextstyleTable* maintaining the *Textstyle* objects - **dimstyles** *DimStyleTable* maintaining the *DimStyle* objects - **appids** *AppIDTable* maintaining the *AppID* objects - **ucs** *UCSTable* maintaining the **UCSTable** objects - **views** *ViewTable* maintaining the *View* objects - **viewports** *ViewportTable* maintaining the *VPort* objects - **block\_records** *BlockRecordTable* maintaining the *BlockRecord* objects ### Blocks Section The BLOCKS section is the home all block definitions (*BlockLayout*) of a DXF document. **WARNING:** Blocks are an essential building block of the DXF format. Most blocks are referenced are by name, and renaming or deleting a block is not as easy as it seems, since there is no overall index where all block references appear, and such block references can also reside in custom data or even custom entities, therefore renaming or deleting block definitions can damage a DXF file! **SEE ALSO:** DXF Internals: *BLOCKS Section* and *Block Management Structures* - **class ezdxf.sections.blocks.BlocksSection** - **\_\_iter\_\_() -\> Iterator\[BlockLayout\]** Iterable of all *BlockLayout* objects. - **\_\_contains\_\_(name: str) -\> bool** Returns **True** if *BlockLayout* *name* exist. - **\_\_getitem\_\_(name: str) -\> BlockLayout** Returns *BlockLayout* *name*, raises **DXFKeyError** if *name* not exist. - **\_\_delitem\_\_(name: str) -\> None** Deletes *BlockLayout* *name* and all of its content, raises **DXFKeyError** if *name* not exist. - **get(name: str, default=None) -\> BlockLayout** Returns *BlockLayout* *name*, returns *default* if *name* not exist. - **new(name: str, base\_point: *UVec* = NULLVEC, dxfattribs=None) -\> BlockLayout** Create and add a new *BlockLayout*, *name* is the BLOCK name, *base\_point* is the insertion point of the BLOCK. - **new\_anonymous\_block(type\_char: str = 'U', base\_point: *UVec* = NULLVEC) -\> BlockLayout** Create and add a new anonymous *BlockLayout*, *type\_char* is the BLOCK type, *base\_point* is the insertion point of the BLOCK. | | | | --- | --- | | type\_char | Anonymous Block Type | | **'U'** | **'\*U###'** anonymous BLOCK | | **'E'** | **'\*E###'** anonymous non-uniformly scaled BLOCK | | **'X'** | **'\*X###'** anonymous HATCH graphic | | **'D'** | **'\*D###'** anonymous DIMENSION graphic | | **'A'** | **'\*A###'** anonymous GROUP | | **'T'** | **'\*T###'** anonymous block for ACAD\_TABLE content | - **rename\_block(old\_name: str, new\_name: str) -\> None** Rename *BlockLayout* *old\_name* to *new\_name* **WARNING:** This is a low-level tool and does not rename the block references, so all block references to *old\_name* are pointing to a non-existing block definition! - **delete\_block(name: str, safe: bool = True) -\> None** Delete block. Applies some safety checks when *safe* is **True**. A **DXFBlockInUseError** will be raised for: - • blocks with active references - • blocks representing existing layouts - • special blocks used internally - **Parameters** - • **name** – block name (case-insensitive) - • **safe** – apply safety checks - **Raises** - • *DXFKeyError* – if block not exists - • *DXFBlockInUseError* – when safe is **True** and block is in use - **delete\_all\_blocks() -\> None** Delete all blocks without references except modelspace- or paperspace layout blocks, special arrow- and anonymous blocks (DIMENSION, ACAD\_TABLE). **WARNING:** There could exist references to blocks which are not documented in the DXF reference, hidden in extended data sections or application defined data, which could invalidate a DXF document if these blocks will be deleted. ### Entities Section The ENTITIES section is the home of all entities of the *Modelspace* and the active *Paperspace* layout. This is a real section in the DXF file but in *ezdxf* the *EntitySection* is just a linked entity space of these two layouts. **SEE ALSO:** DXF Internals: *ENTITIES Section* - **class ezdxf.sections.entities.EntitySection** - **\_\_iter\_\_() -\> Iterator\[*DXFEntity*\]** Returns an iterator for all entities of the modelspace and the active paperspace. - **\_\_len\_\_() -\> int** Returns the count of all entities in the modelspace and the active paperspace. ### Objects Section The OBJECTS section is the home of all none graphical objects of a DXF document. The OBJECTS section is accessible by the **Drawing.objects** attribute. Convenience methods of the *Drawing* object to create essential structures in the OBJECTS section: - • IMAGEDEF: *add\_image\_def()* - • UNDERLAYDEF: *add\_underlay\_def()* - • RASTERVARIABLES: *set\_raster\_variables()* - • WIPEOUTVARIABLES: *set\_wipeout\_variables()* **SEE ALSO:** DXF Internals: *OBJECTS Section* - **class ezdxf.sections.objects.ObjectsSection** - **rootdict** Returns the root DICTIONARY, or as AutoCAD calls it: the named DICTIONARY. - **\_\_len\_\_() -\> int** Returns the count of all DXF objects in the OBJECTS section. - **\_\_iter\_\_() -\> Iterator\[*DXFObject*\]** Returns an iterator of all DXF objects in the OBJECTS section. - **\_\_getitem\_\_(index) -\> *DXFObject*** Get entity at *index*. The underlying data structure for storing DXF objects is organized like a standard Python list, therefore *index* can be any valid list indexing or slicing term, like a single index **objects\[-1\]** to get the last entity, or an index slice **objects\[:10\]** to get the first 10 or fewer objects as **list\[DXFObject\]**. - **\_\_contains\_\_(entity)** Returns **True** if *entity* stored in OBJECTS section. - **Parameters** **entity** – **DXFObject** or handle as hex string - **query(query: str = '\*') -\> *EntityQuery*** Get all DXF objects matching the *Entity Query String*. - **add\_dictionary(owner: str = '0', hard\_owned: bool = True) -\> Dictionary** Add new *Dictionary* object. - **Parameters** - • **owner** – handle to owner as hex string. - • **hard\_owned** – **True** to treat entries as hard owned. - **add\_dictionary\_with\_default(owner='0', default='0', hard\_owned: bool = True) -\> *DictionaryWithDefault*** Add new *DictionaryWithDefault* object. - **Parameters** - • **owner** – handle to owner as hex string. - • **default** – handle to default entry. - • **hard\_owned** – **True** to treat entries as hard owned. - **add\_dictionary\_var(owner: str = '0', value: str = '') -\> *DictionaryVar*** Add a new *DictionaryVar* object. - **Parameters** - • **owner** – handle to owner as hex string. - • **value** – value as string - **add\_geodata(owner: str = '0', dxfattribs=None) -\> *GeoData*** Creates a new **GeoData** entity and replaces existing ones. The GEODATA entity resides in the OBJECTS section and NOT in the layout entity space, and it is linked to the layout by an extension dictionary located in BLOCK\_RECORD of the layout. The GEODATA entity requires DXF version R2010+. The DXF Reference does not document if other layouts than model space supports geo referencing, so getting/setting geo data may only make sense for the model space layout, but it is also available in paper space layouts. - **Parameters** - • **owner** – handle to owner as hex string - • **dxfattribs** – DXF attributes for *GeoData* entity - **add\_image\_def(filename: str, size\_in\_pixel: tuple\[int, int\], name: str \| None = None) -\> *ImageDef*** Add an image definition to the objects section. Add an **ImageDef** entity to the drawing (objects section). *filename* is the image file name as relative or absolute path and *size\_in\_pixel* is the image size in pixel as (x, y) tuple. To avoid dependencies to external packages, *ezdxf* can not determine the image size by itself. Returns a **ImageDef** entity which is needed to create an image reference. *name* is the internal image name, if set to **None**, name is auto-generated. Absolute image paths works best for AutoCAD but not really good, you have to update external references manually in AutoCAD, which is not possible in TrueView. If the drawing units differ from 1 meter, you also have to use: *set\_raster\_variables()*. - **Parameters** - • **filename** – image file name (absolute path works best for AutoCAD) - • **size\_in\_pixel** – image size in pixel as (x, y) tuple - • **name** – image name for internal use, None for using filename as name (best for AutoCAD) - **add\_placeholder(owner: str = '0') -\> *Placeholder*** Add a new *Placeholder* object. - **Parameters** **owner** – handle to owner as hex string. - **add\_underlay\_def(filename: str, fmt: str = 'pdf', name: str \| None = None) -\> *UnderlayDefinition*** Add an **UnderlayDefinition** entity to the drawing (OBJECTS section). *filename* is the underlay file name as relative or absolute path and *fmt* as string (pdf, dwf, dgn). The underlay definition is required to create an underlay reference. - **Parameters** - • **filename** – underlay file name - • **fmt** – file format as string **'pdf'\|'dwf'\|'dgn'** - • **name** – pdf format = page number to display; dgn format = **'default'**; dwf: ???? - **add\_xrecord(owner: str = '0') -\> *XRecord*** Add a new *XRecord* object. - **Parameters** **owner** – handle to owner as hex string. - **set\_raster\_variables(frame: int = 0, quality: int = 1, units: str = 'm') -\> None** Set raster variables. - **Parameters** - • **frame** – **0** = do not show image frame; **1** = show image frame - • **quality** – **0** = draft; **1** = high - • **units** – units for inserting images. This defines the real world unit for one drawing unit for the purpose of inserting and scaling images with an associated resolution. | | | | --- | --- | | mm | Millimeter | | cm | Centimeter | | m | Meter (ezdxf default) | | km | Kilometer | | in | Inch | | ft | Foot | | yd | Yard | | mi | Mile | | none | None | (internal API), public interface **set\_raster\_variables()** - **set\_wipeout\_variables(frame: int = 0) -\> None** Set wipeout variables. - **Parameters** **frame** – **0** = do not show image frame; **1** = show image frame (internal API) ### Tables ### Table Classes ### Generic Table Class - **class ezdxf.sections.table.Table** Generic collection of table entries. Table entry names are case insensitive: “Test” == “TEST”. - **static key(name: str) -\> str** Unified table entry key. - **has\_entry(name: str) -\> bool** Returns **True** if a table entry *name* exist. - **\_\_contains\_\_(name: str) -\> bool** Returns **True** if a table entry *name* exist. - **\_\_len\_\_() -\> int** Count of table entries. - **\_\_iter\_\_() -\> Iterator\[T\]** Iterable of all table entries. - **new(name: str, dxfattribs=None) -\> T** Create a new table entry *name*. - **Parameters** - • **name** – name of table entry - • **dxfattribs** – additional DXF attributes for table entry - **get(name: str) -\> T** Returns table entry *name*. - **Parameters** **name** – name of table entry, case-insensitive - **Raises** *DXFTableEntryError* – table entry does not exist - **remove(name: str) -\> None** Removes table entry *name*. - **Parameters** **name** – name of table entry, case-insensitive - **Raises** *DXFTableEntryError* – table entry does not exist - **duplicate\_entry(name: str, new\_name: str) -\> T** Returns a new table entry *new\_name* as copy of *name*, replaces entry *new\_name* if already exist. - **Parameters** - • **name** – name of table entry, case-insensitive - • **new\_name** – name of duplicated table entry - **Raises** *DXFTableEntryError* – table entry does not exist ### Layer Table - **class ezdxf.sections.table.LayerTable** Subclass of *Table*. Collection of *Layer* objects. - **add(name: str, \*, color: int = const.BYLAYER, true\_color: int \| None = None, linetype: str = 'Continuous', lineweight: int = const.LINEWEIGHT\_BYLAYER, plot: bool = True, transparency: float \| None = None, dxfattribs=None) -\> Layer** Add a new *Layer*. - **Parameters** - • **name** (*str*) – layer name - • **color** (*int*) – *AutoCAD Color Index (ACI)* value, default is BYLAYER - • **true\_color** (*int*) – true color value, use **ezdxf.rgb2int()** to create **int** values from RGB values - • **linetype** (*str*) – line type name, default is “Continuous” - • **lineweight** (*int*) – line weight, default is BYLAYER - • **plot** (*bool*) – plot layer as bool, default is **True** - • **transparency** – transparency value in the range \[0, 1\], where 1 is 100% transparent and 0 is opaque - • **dxfattribs** (*dict*) – additional DXF attributes ### Linetype Table - **class ezdxf.sections.table.LinetypeTable** Subclass of *Table*. Collection of *Linetype* objects. - **add(name: str, pattern: Sequence\[float\] \| str, \*, description: str = '', length: float = 0.0, dxfattribs=None) -\> Linetype** Add a new line type entry. The simple line type pattern is a list of floats **\[total\_pattern\_length, elem1, elem2, ...\]** where an element \> 0 is a line, an element \< 0 is a gap and an element == 0.0 is a dot. The definition for complex line types are strings, like: **'A,.5,-.2,\["GAS",STANDARD,S=.1,U=0.0,X=-0.1,Y=-.05\],-.25'** similar to the line type definitions stored in the line definition *.lin* files, for more information see the tutorial about complex line types. Be aware that not many CAD applications and DXF viewers support complex linetypes. **SEE ALSO:** - • *Tutorial for simple line types* - • *Tutorial for complex line types* - **Parameters** - • **name** (*str*) – line type name - • **pattern** – line type pattern as list of floats or as a string - • **description** (*str*) – line type description, optional - • **length** (*float*) – total pattern length, only for complex line types required - • **dxfattribs** (*dict*) – additional DXF attributes ### Style Table - **class ezdxf.sections.table.TextstyleTable** Subclass of *Table*. Collection of *Textstyle* objects. - **add(name: str, \*, font: str, dxfattribs=None) -\> Textstyle** Add a new text style entry for TTF fonts. The entry must not yet exist, otherwise an **DXFTableEntryError** exception will be raised. Finding the TTF font files is the task of the DXF viewer and each viewer is different (hint: support files). - **Parameters** - • **name** (*str*) – text style name - • **font** (*str*) – TTF font file name like “Arial.ttf”, the real font file name from the file system is required and only the Windows filesystem is case-insensitive. - • **dxfattribs** (*dict*) – additional DXF attributes - **add\_shx(shx\_file\_name: str, \*, dxfattribs=None) -\> Textstyle** Add a new shape font (SHX file) entry. These are special text style entries and have no name. The entry must not yet exist, otherwise an **DXFTableEntryError** exception will be raised. Locating the SHX files in the filesystem is the task of the DXF viewer and each viewer is different (hint: support files). - **Parameters** - • **shx\_file\_name** (*str*) – shape file name like “gdt.shx” - • **dxfattribs** (*dict*) – additional DXF attributes - **get\_shx(shx\_file\_name: str) -\> Textstyle** Get existing entry for a shape file (SHX file), or create a new entry. Locating the SHX files in the filesystem is the task of the DXF viewer and each viewer is different (hint: support files). - **Parameters** **shx\_file\_name** (*str*) – shape file name like “gdt.shx” - **find\_shx(shx\_file\_name: str) -\> Textstyle \| None** Find the shape file (SHX file) text style table entry, by a case-insensitive search. A shape file table entry has no name, so you have to search by the font attribute. - **Parameters** **shx\_file\_name** (*str*) – shape file name like “gdt.shx” - **discard\_shx(shx\_file\_name: str) -\> None** Discard the shape file (SHX file) text style table entry. Does not raise an exception if the entry does not exist. - **Parameters** **shx\_file\_name** (*str*) – shape file name like “gdt.shx” ### DimStyle Table - **class ezdxf.sections.table.DimStyleTable** Subclass of *Table*. Collection of *DimStyle* objects. - **add(name: str, \*, dxfattribs=None) -\> DimStyle** Add a new dimension style table entry. - **Parameters** - • **name** (*str*) – dimension style name - • **dxfattribs** (*dict*) – DXF attributes ### AppID Table - **class ezdxf.sections.table.AppIDTable** Subclass of *Table*. Collection of *AppID* objects. - **add(name: str, \*, dxfattribs=None) -\> AppID** Add a new appid table entry. - **Parameters** - • **name** (*str*) – appid name - • **dxfattribs** (*dict*) – DXF attributes ### UCS Table - **class ezdxf.sections.table.UCSTable** Subclass of *Table*. Collection of *UCSTableEntry* objects. - **add(name: str, \*, dxfattribs=None) -\> UCSTableEntry** Add a new UCS table entry. - **Parameters** - • **name** (*str*) – UCS name - • **dxfattribs** (*dict*) – DXF attributes ### View Table - **class ezdxf.sections.table.ViewTable** Subclass of *Table*. Collection of *View* objects. - **add(name: str, \*, dxfattribs=None) -\> View** Add a new view table entry. - **Parameters** - • **name** (*str*) – view name - • **dxfattribs** (*dict*) – DXF attributes ### Viewport Table - **class ezdxf.sections.table.ViewportTable** The viewport table stores the modelspace viewport configurations. A viewport configuration is a tiled view of multiple viewports or just one viewport. In contrast to other tables the viewport table can have multiple entries with the same name, because all viewport entries of a multi-viewport configuration are having the same name - the viewport configuration name. The name of the actual displayed viewport configuration is “\*ACTIVE”. Duplication of table entries is not supported: **duplicate\_entry()** raises **NotImplementedError** - **add(name: str, \*, dxfattribs=None) -\> VPort** Add a new modelspace viewport entry. A modelspace viewport configuration can consist of multiple viewport entries with the same name. - **Parameters** - • **name** (*str*) – viewport name, multiple entries possible - • **dxfattribs** (*dict*) – additional DXF attributes - **get\_config(self, name: str) -\> List\[*VPort*\]** Returns a list of *VPort* objects, for the multi-viewport configuration *name*. - **delete\_config(name: str) -\> None** Delete all *VPort* objects of the multi-viewport configuration *name*. ### Block Record Table - **class ezdxf.sections.table.BlockRecordTable** Subclass of *Table*. Collection of *BlockRecord* objects. - **add(name: str, \*, dxfattribs=None) -\> BlockRecord** Add a new block record table entry. - **Parameters** - • **name** (*str*) – block record name - • **dxfattribs** (*dict*) – DXF attributes ### Layer LAYER (*DXF Reference*) definition, defines attribute values for entities on this layer for their attributes set to **BYLAYER**. **IMPORTANT:** A layer assignment is just an attribute of a DXF entity, it’s not an entity container, the entities are stored in layouts and blocks and the assigned layer is not important for that. Deleting a layer entry does not delete the entities which reference this layer! | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'LAYER'** | | Factory function | **Drawing.layers.new()** | **SEE ALSO:** Basic concepts of *Layers* and *Tutorial for Layers* - **class ezdxf.entities.Layer** - **dxf.handle** DXF handle (feature for experts) - **dxf.owner** Handle to owner (*LayerTable*). - **dxf.name** Layer name, case insensitive and can not contain any of this characters: **\<\>/\\":;?\*\|=\`** (str) - **dxf.flags** Layer flags (bit-coded values, feature for experts) | | | | --- | --- | | 1 | Layer is frozen; otherwise layer is thawed; use **is\_frozen()**, **freeze()** and **thaw()** | | 2 | Layer is frozen by default in new viewports | | 4 | Layer is locked; use **is\_locked()**, **lock()**, **unlock()** | | 16 | If set, table entry is externally dependent on an xref | | 32 | If both this bit and bit 16 are set, the externally dependent xref has been successfully resolved | | 64 | If set, the table entry was referenced by at least one entity in the drawing the last time the drawing was edited. (This flag is for the benefit of AutoCAD commands. It can be ignored by most programs that read DXF files and need not be set by programs that write DXF files) | - **dxf.color** Layer color, but use property *Layer.color* to get/set color value, because color is negative for layer status *off* (int) - **dxf.true\_color** Layer true color value as int, use property *Layer.rgb* to set/get true color value as (r, g, b) tuple. (requires DXF R2004) - **dxf.linetype** Name of line type (str) - **dxf.plot** Plot flag (int). Whether entities belonging to this layer should be drawn when the document is exported (plotted) to pdf. Does not affect visibility inside the CAD application itself. | | | | --- | --- | | 1 | plot layer (default value) | | 0 | don’t plot layer | - **dxf.lineweight** Line weight in mm times 100 (e.g. 0.13mm = 13). Smallest line weight is 13 and biggest line weight is 200, values outside this range prevents AutoCAD from loading the file. **ezdxf.lldxf.const.LINEWEIGHT\_DEFAULT** for using global default line weight. (requires DXF R13) - **dxf.plotstyle\_handle** Handle to plot style name? (requires DXF R13) - **dxf.material\_handle** Handle to default **Material**. (requires DXF R13) - **rgb** Get/set DXF attribute *dxf.true\_color* as (r, g, b) tuple, returns **None** if attribute *dxf.true\_color* is not set. ``` layer.rgb = (30, 40, 50) r, g, b = layer.rgb ``` This is the recommend method to get/set RGB values, when ever possible do not use the DXF low level attribute *dxf.true\_color*. - **color** Get/set layer color, preferred method for getting the layer color, because *dxf.color* is negative for layer status *off*. - **description** Get/set layer description as string - **transparency** Get/set layer transparency as float value in the range from 0 to 1. 0 for no transparency (opaque) and 1 for 100% transparency. - **is\_frozen() -\> bool** Returns **True** if layer is frozen. - **freeze() -\> None** Freeze layer. - **thaw() -\> None** Thaw layer. - **is\_locked() -\> bool** Returns **True** if layer is locked. - **lock() -\> None** Lock layer, entities on this layer are not editable - just important in CAD applications. - **unlock() -\> None** Unlock layer, entities on this layer are editable - just important in CAD applications. - **is\_off() -\> bool** Returns **True** if layer is off. - **is\_on() -\> bool** Returns **True** if layer is on. - **on() -\> None** Switch layer *on* (visible). - **off() -\> None** Switch layer *off* (invisible). - **get\_color() -\> int** Use property *Layer.color* instead. - **set\_color(value: int) -\> None** Use property *Layer.color* instead. - **rename(name: str) -\> None** Rename layer and all known (documented) references to this layer. **WARNING:** The DXF format is not consistent in storing layer references, the layers are mostly referenced by their case-insensitive name, some later introduced entities do reference layers by handle, which is the safer way in the context of renaming layers. There is no complete overview of where layer references are stored, third-party entities are black-boxes with unknown content and layer names could be stored in the extended data section of any DXF entity or in XRECORD entities. Which means that in some rare cases references to the old layer name can persist, at least this does not invalidate the DXF document. - **Parameters** **name** – new layer name - **Raises** - • **ValueError** – *name* contains invalid characters: \<\>/":;?\*\|=\` - • **ValueError** – layer *name* already exist - • **ValueError** – renaming of layers **'0'** and **'DEFPOINTS'** not\ possible - **get\_vp\_overrides() -\> *LayerOverrides*** Returns the *LayerOverrides* object for this layer. ### LayerOverrides - **class ezdxf.entities.LayerOverrides** This object stores the layer attribute overridden in *Viewport* entities, where each *Viewport* can have individual layer attribute overrides. Layer attributes which can be overridden: - • ACI color - • true color (rgb) - • linetype - • lineweight - • transparency Get the override object for a certain layer by the *Layer.get\_vp\_overrides()* method. It is important to write changes back by calling *commit()*, otherwise the changes are lost. **IMPORTANT:** The implementation of this feature as DXF structures is not documented by the DXF reference, so if you encounter problems or errors, **ALWAYS** provide the DXF files, otherwise it is not possible to help. - **has\_overrides(vp\_handle: str \| None = None) -\> bool** Returns **True** if attribute overrides exist for the given *Viewport* handle. Returns **True** if *any* attribute overrides exist if the given handle is **None**. - **commit() -\> None** Write *Viewport* overrides back into the *Layer* entity. Without a commit() all changes are lost! - **get\_color(vp\_handle: str) -\> int** Returns the *AutoCAD Color Index (ACI)* override or the original layer value if no override exist. - **set\_color(vp\_handle: str, value: int) -\> None** Override the *AutoCAD Color Index (ACI)*. - **Raises** **ValueError** – invalid color value - **get\_rgb(vp\_handle: str) -\> *RGB* \| None** Returns the RGB override or the original layer value if no override exist. Returns **None** if no true color value is set. - **set\_rgb(vp\_handle: str, value: *RGB* \| None)** Set the RGB override as (red, gree, blue) tuple or **None** to remove the true color setting. - **Raises** **ValueError** – invalid RGB value - **get\_transparency(vp\_handle: str) -\> float** Returns the transparency override or the original layer value if no override exist. Returns 0.0 for opaque and 1.0 for fully transparent. - **set\_transparency(vp\_handle: str, value: float) -\> None** Set the transparency override. A transparency of 0.0 is opaque and 1.0 is fully transparent. - **Raises** **ValueError** – invalid transparency value - **get\_linetype(vp\_handle: str) -\> str** Returns the linetype override or the original layer value if no override exist. - **set\_linetype(vp\_handle: str, value: str) -\> None** Set the linetype override. - **Raises** **ValueError** – linetype without a LTYPE table entry - **get\_lineweight(vp\_handle: str) -\> int** Returns the lineweight override or the original layer value if no override exist. - **set\_lineweight(vp\_handle: str, value: int) -\> None** Set the lineweight override. - **Raises** **ValueError** – invalid lineweight value - **discard(vp\_handle: str \| None = None) -\> None** Discard all attribute overrides for the given *Viewport* handle or for all *Viewport* entities if the handle is **None**. ### Style **IMPORTANT:** DXF is not a layout preserving data format like PDF. It is more similar to the MS Word format. Many applications can open MS Word documents, but the displayed or printed document does not look perfect like the result of MS Word. The final rendering of DXF files is highly dependent on the interpretation of DXF entities by the rendering engine, and the DXF reference does not provide any guidelines for rendering entities. The biggest visual differences of CAD applications are the text renderings, therefore the only way to get the exact same result is to use the same CAD application. The DXF format does not and **can not** embed TTF fonts like the PDF format! The *Textstyle* entity defines a text style (*DXF Reference*), and can be used by the entities: *Text*, *Attrib*, **Attdef**, *MText*, *Dimension*, *Leader* and *MultiLeader*. Example to create a new text style “Arial” and to apply this text style: ``` doc.styles.add("Arial", font="Arial.ttf") msp = doc.modelspace() msp.add_text("my text", dxfattribs={"style": "Arial"}) ``` The settings stored in the *Textstyle* entity are the default text style values used by CAD applications if the text settings are not stored in the text entity itself. But not all setting are substituted by the default value. The **height** or **width** attribute must be stored in the text entities itself in order to influence the appearance of the text. It is *recommended* that you do not rely on the default settings in the *Textstyle* entity, set all attributes in the text entity itself if supported. ### Font Settings Just a few settings are available exclusive by the *Textstyle* entity: The most important setting is the **font** attribute, this attribute defines the rendering font as raw TTF file name, e.g. “Arial.ttf” or “OpenSansCondensed-Light.ttf”, this file name is often **not** the name displayed in GUI application and you have to digg down into the fonts folder e.g. (“C:\\Windows\\Fonts”) to get the real file name for the TTF font. Do not include the path! \[image\] AutoCAD supports beyond the legacy SHX fonts **only** TTF fonts. The SHX font format is not documented and only available in some CAD applications. The *ezdxf* *drawing* add-on replaces the SHX fonts by TTF fonts, which look similar to the SHX fonts, unfortunately the license of these fonts is unclear, therefore they can not be packaged with *ezdxf*. They are installed automatically if you use an Autodesk product like *TrueView*, or search the internet at you own risk for these TTF fonts. The extended font data can provide extra information for the font, it is stored in the XDATA section, not well documented and not widely supported. **IMPORTANT:** The DXF format does not and **can not** embed TTF fonts like the PDF format! You need to make sure that the CAD application is properly configured to have access to the system fonts. The DXF format has no setting where the CAD application should search for fonts, and does not guarantee that the text rendering on other computers or operating systems looks the same as on your current system on which you created the DXF. The second exclusive setting is the vertical text flag in **Textstyle.flags**. The vertical text style is enabled for *all* entities using the text style. Vertical text works only for SHX fonts and is not supported for TTF fonts (in AutoCAD) and is works only for the single line entities *Text* and *Attrib*. Most CAD applications beside AutoCAD and BricsCAD do not support vertical text rendering and even AutoCAD and BricsCAD have problems with vertical text rendering in some circumstances. Using the vertical text feature is not recommended. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'STYLE'** | | Factory function | **Drawing.styles.new()** | **SEE ALSO:** *Tutorial for Text* and DXF internals for *DIMSTYLE Table*. - **class ezdxf.entities.Textstyle** - **property is\_backward: bool** Get/set text generation flag BACKWARDS, for mirrored text along the x-axis. - **property is\_upside\_down: bool** Get/set text generation flag UPSIDE\_DOWN, for mirrored text along the y-axis. - **property is\_vertical\_stacked: bool** Get/set style flag VERTICAL\_STACKED, for vertical stacked text. - **property is\_shape\_file: bool** **True** if entry describes a shape. - **dxf.handle** DXF handle (feature for experts). - **dxf.owner** Handle to owner (*TextstyleTable*). - **dxf.name** Style name (str) - **dxf.flags** Style flags (feature for experts). | | | | --- | --- | | 1 | If set, this entry describes a shape | | 4 | Vertical text | | 16 | If set, table entry is externally dependent on an xref | | 32 | If both this bit and bit 16 are set, the externally dependent xref has been successfully resolved | | 64 | If set, the table entry was referenced by at least one entity in the drawing the last time the drawing was edited. (This flag is only for the benefit of AutoCAD)commands. It can be ignored by most programs that read DXF files and need not be set by programs that write DXF files) | - **dxf.height** Fixed height in drawing units as float value, 0 for not fixed. - **dxf.width** Width factor as float value, default value is 1. - **dxf.oblique** Oblique (slanting) angle in degrees as float value, default value is 0 for no slanting. - **dxf.generation\_flags** Text generations flags as int value. | | | | --- | --- | | 2 | text is backward (mirrored along the x-axis) | | 4 | text is upside down (mirrored about the base line) | - **dxf.last\_height** Last height used in drawing units as float value. - **dxf.font** Raw font file name as string without leading path, e.g. “Arial.ttf” for TTF fonts or the SHX font name like “TXT” or “TXT.SHX”. - **dxf.bigfont** Big font name as string, blank if none. No documentation how to use this feature, maybe just a legacy artifact. - **property has\_extended\_font\_data: bool** Returns **True** if extended font data is present. - **get\_extended\_font\_data() -\> tuple\[str, bool, bool\]** Returns extended font data as tuple (font-family, italic-flag, bold-flag). The extended font data is optional and not reliable! Returns (“”, **False**, **False**) if extended font data is not present. - **set\_extended\_font\_data(family: str = '', \*, italic=False, bold=False) -\> None** Set extended font data, the font-family name *family* is not validated by *ezdxf*. Overwrites existing data. - **discard\_extended\_font\_data()** Discard extended font data. - **make\_font(cap\_height: float \| None = None, width\_factor: float \| None = None) -\> *fonts.AbstractFont*** Returns a font abstraction **AbstractFont** for this text style. Returns a font for a cap height of 1, if the text style has auto height (*Textstyle.dxf.height* is 0) and the given *cap\_height* is **None** or 0. Uses the *Textstyle.dxf.width* attribute if the given *width\_factor* is **None** or 0, the default value is 1. The attribute **Textstyle.dxf.big\_font** is ignored. ### Linetype Defines a linetype (*DXF Reference*). | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'LTYPE'** | | Factory function | **Drawing.linetypes.new()** | **SEE ALSO:** *Tutorial for Creating Linetype Pattern* DXF Internals: *LTYPE Table* - **class ezdxf.entities.Linetype** - **dxf.name** Linetype name (str). - **dxf.owner** Handle to owner (*Table*). - **dxf.description** Linetype description (str). - **dxf.length** Total pattern length in drawing units (float). - **dxf.items** Number of linetype elements (int). ### DimStyle \[image\] \[image\] DIMSTYLE (*DXF Reference*) defines the appearance of *Dimension* entities. Each of this dimension variables starting with **"dim..."** can be overridden for any *Dimension* entity individually. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'DIMSTYLE'** | | Factory function | **Drawing.dimstyles.new()** | - **class ezdxf.entities.DimStyle** - **dxf.owner** Handle to owner (*Table*). - **dxf.name** Dimension style name. - **dxf.flags** Standard flag values (bit-coded values): | | | | --- | --- | | 16 | If set, table entry is externally dependent on an xref | | 32 | If both this bit and bit 16 are set, the externally dependent XREF has been successfully resolved | | 64 | If set, the table entry was referenced by at least one entity in the drawing the last time the drawing was edited. (This flag is only for the benefit of AutoCAD) | - **dxf.dimpost** Prefix/suffix for primary units dimension values. - **dxf.dimapost** Prefix/suffix for alternate units dimensions. - **dxf.dimblk** Block type to use for both arrowheads as name string. - **dxf.dimblk1** Block type to use for first arrowhead as name string. - **dxf.dimblk2** Block type to use for second arrowhead as name string. - **dxf.dimscale** Global dimension feature scale factor. (default=1) - **dxf.dimasz** Dimension line and arrowhead size. (default=0.25) - **dxf.dimexo** Distance from origin points to extension lines. (default imperial=0.0625, default metric=0.625) - **dxf.dimdli** Incremental spacing between baseline dimensions. (default imperial=0.38, default metric=3.75) - **dxf.dimexe** Extension line distance beyond dimension line. (default imperial=0.28, default metric=2.25) - **dxf.dimrnd** Rounding value for decimal dimensions. (default=0) Rounds all dimensioning distances to the specified value, for instance, if DIMRND is set to 0.25, all distances round to the nearest 0.25 unit. If you set DIMRND to 1.0, all distances round to the nearest integer. - **dxf.dimdle** Dimension line extension beyond extension lines. (default=0) - **dxf.dimtp** Upper tolerance value for tolerance dimensions. (default=0) - **dxf.dimtm** Lower tolerance value for tolerance dimensions. (default=0) - **dxf.dimtxt** Size of dimension text. (default imperial=0.28, default metric=2.5) - **dxf.dimcen** Controls placement of center marks or centerlines. (default imperial=0.09, default metric=2.5) - **dxf.dimtsz** Controls size of dimension line tick marks drawn instead of arrowheads. (default=0) - **dxf.dimaltf** Alternate units dimension scale factor. (default=25.4) - **dxf.dimlfac** Scale factor for linear dimension values. (default=1) - **dxf.dimtvp** Vertical position of text above or below dimension line if *dimtad* is 0. (default=0) - **dxf.dimtfac** Scale factor for fractional or tolerance text size. (default=1) - **dxf.dimgap** Gap size between dimension line and dimension text. (default imperial=0.09, default metric=0.625) - **dxf.dimaltrnd** Rounding value for alternate dimension units. (default=0) - **dxf.dimtol** Toggles creation of appended tolerance dimensions. (default imperial=1, default metric=0) - **dxf.dimlim** Toggles creation of limits-style dimension text. (default=0) - **dxf.dimtih** Orientation of text inside extension lines. (default imperial=1, default metric=0) - **dxf.dimtoh** Orientation of text outside extension lines. (default imperial=1, default metric=0) - **dxf.dimse1** Toggles suppression of first extension line. (default=0) - **dxf.dimse2** Toggles suppression of second extension line. (default=0) - **dxf.dimtad** Sets vertical text placement relative to dimension line. (default imperial=0, default metric=1) | | | | --- | --- | | 0 | center | | 1 | above | | 2 | outside, handled like above by *ezdxf* | | 3 | JIS, handled like above by *ezdxf* | | 4 | below | - **dxf.dimzin** Zero suppression for primary units dimensions. (default imperial=0, default metric=8) Values 0-3 affect feet-and-inch dimensions only. | | | | --- | --- | | 0 | Suppresses zero feet and precisely zero inches | | 1 | Includes zero feet and precisely zero inches | | 2 | Includes zero feet and suppresses zero inches | | 3 | Includes zero inches and suppresses zero feet | | 4 | Suppresses leading zeros in decimal dimensions (for example, 0.5000 becomes .5000) | | 8 | Suppresses trailing zeros in decimal dimensions (for example, 12.5000 becomes 12.5) | | 12 | Suppresses both leading and trailing zeros (for example, 0.5000 becomes .5) | - **dxf.dimazin** Controls zero suppression for angular dimensions. (default=0) | | | | --- | --- | | 0 | Displays all leading and trailing zeros | | 1 | Suppresses leading zeros in decimal dimensions (for example, 0.5000 becomes .5000) | | 2 | Suppresses trailing zeros in decimal dimensions (for example, 12.5000 becomes 12.5) | | 3 | Suppresses leading and trailing zeros (for example, 0.5000 becomes .5) | - **dxf.dimalt** Enables or disables alternate units dimensioning. (default=0) - **dxf.dimaltd** Controls decimal places for alternate units dimensions. (default imperial=2, default metric=3) - **dxf.dimtofl** Toggles forced dimension line creation. (default imperial=0, default metric=1) - **dxf.dimsah** Toggles appearance of arrowhead blocks. (default=0) - **dxf.dimtix** Toggles forced placement of text between extension lines. (default=0) - **dxf.dimsoxd** Suppresses dimension lines outside extension lines. (default=0) - **dxf.dimclrd** Dimension line, arrowhead, and leader line color. (default=0) - **dxf.dimclre** Dimension extension line color. (default=0) - **dxf.dimclrt** Dimension text color. (default=0) - **dxf.dimadec** Controls the number of decimal places for angular dimensions. - **dxf.dimunit** Obsolete, now use DIMLUNIT AND DIMFRAC - **dxf.dimdec** Decimal places for dimension values. (default imperial=4, default metric=2) - **dxf.dimtdec** Decimal places for primary units tolerance values. (default imperial=4, default metric=2) - **dxf.dimaltu** Units format for alternate units dimensions. (default=2) - **dxf.dimalttd** Decimal places for alternate units tolerance values. (default imperial=4, default metric=2) - **dxf.dimaunit** Unit format for angular dimension values. (default=0) - **dxf.dimfrac** Controls the fraction format used for architectural and fractional dimensions. (default=0) - **dxf.dimlunit** Specifies units for all nonangular dimensions. (default=2) - **dxf.dimdsep** Specifies a single character to use as a decimal separator. (default imperial = “.”, default metric = “,”) This is an integer value, use **ord(".")** to write value. - **dxf.dimtmove** Controls the format of dimension text when it is moved. (default=0) | | | | --- | --- | | 0 | Moves the dimension line with dimension text | | 1 | Adds a leader when dimension text is moved | | 2 | Allows text to be moved freely without a leader | - **dxf.dimjust** Horizontal justification of dimension text. (default=0) | | | | --- | --- | | 0 | Center of dimension line | | 1 | Left side of the dimension line, near first extension line | | 2 | Right side of the dimension line, near second extension line | | 3 | Over first extension line | | 4 | Over second extension line | - **dxf.dimsd1** Toggles suppression of first dimension line. (default=0) - **dxf.dimsd2** Toggles suppression of second dimension line. (default=0) - **dxf.dimtolj** Vertical justification for dimension tolerance text. (default=1) | | | | --- | --- | | 0 | Align with bottom line of dimension text | | 1 | Align vertical centered to dimension text | | 2 | Align with top line of dimension text | - **dxf.dimtzin** Zero suppression for tolerances values, see *DimStyle.dxf.dimzin* - **dxf.dimaltz** Zero suppression for alternate units dimension values. (default=0) - **dxf.dimalttz** Zero suppression for alternate units tolerance values. (default=0) - **dxf.dimfit** Obsolete, now use DIMATFIT and DIMTMOVE - **dxf.dimupt** Controls user placement of dimension line and text. (default=0) - **dxf.dimatfit** Controls placement of text and arrowheads when there is insufficient space between the extension lines. (default=3) - **dxf.dimtxsty** Text style used for dimension text by name. - **dxf.dimtxsty\_handle** Text style used for dimension text by handle of STYLE entry. (use *DimStyle.dxf.dimtxsty* to get/set text style by name) - **dxf.dimldrblk** Specify arrowhead used for leaders by name. - **dxf.dimldrblk\_handle** Specify arrowhead used for leaders by handle of referenced block. (use *DimStyle.dxf.dimldrblk* to get/set arrowhead by name) - **dxf.dimblk\_handle** Block type to use for both arrowheads, handle of referenced block. (use *DimStyle.dxf.dimblk* to get/set arrowheads by name) - **dxf.dimblk1\_handle** Block type to use for first arrowhead, handle of referenced block. (use *DimStyle.dxf.dimblk1* to get/set arrowhead by name) - **dxf.dimblk2\_handle** Block type to use for second arrowhead, handle of referenced block. (use *DimStyle.dxf.dimblk2* to get/set arrowhead by name) - **dxf.dimlwd** Lineweight value for dimension lines. (default=-2, BYBLOCK) - **dxf.dimlwe** Lineweight value for extension lines. (default=-2, BYBLOCK) - **dxf.dimltype** Specifies the linetype used for the dimension line as linetype name, requires DXF R2007+ - **dxf.dimltype\_handle** Specifies the linetype used for the dimension line as handle to LTYPE entry, requires DXF R2007+ (use *DimStyle.dxf.dimltype* to get/set linetype by name) - **dxf.dimltex1** Specifies the linetype used for the extension line 1 as linetype name, requires DXF R2007+ - **dxf.dimlex1\_handle** Specifies the linetype used for the extension line 1 as handle to LTYPE entry, requires DXF R2007+ (use *DimStyle.dxf.dimltex1* to get/set linetype by name) - **dxf.dimltex2** Specifies the linetype used for the extension line 2 as linetype name, requires DXF R2007+ - **dxf.dimlex2\_handle** Specifies the linetype used for the extension line 2 as handle to LTYPE entry, requires DXF R2007+ (use *DimStyle.dxf.dimltex2* to get/set linetype by name) - **dxf.dimfxlon** Extension line has fixed length if set to 1, requires DXF R2007+ - **dxf.dimfxl** Length of extension line below dimension line if fixed (**DimStyle.dxf.dimtfxlon** == 1), **DimStyle.dxf.dimexen** defines the length above the dimension line, requires DXF R2007+ - **dxf.dimtfill** Text fill 0=off; 1=background color; 2=custom color (see *DimStyle.dxf.dimtfillclr*), requires DXF R2007+ - **dxf.dimtfillclr** Text fill custom color as color index (1-255), requires DXF R2007+ - **dxf.dimarcsym** Display arc symbol, supported only by *ArcDimension*: | | | | --- | --- | | 0 | arc symbol preceding the measurement text | | 1 | arc symbol above the measurement text | | 2 | disable arc symbol | - **copy\_to\_header(doc: *Drawing*)** Copy all dimension style variables to HEADER section of *doc*. - **set\_arrows(blk: str = '', blk1: str = '', blk2: str = '', ldrblk: str = '') -\> None** Set arrows by block names or AutoCAD standard arrow names, set DIMTSZ to **0** which disables tick. - **Parameters** - • **blk** – block/arrow name for both arrows, if DIMSAH is 0 - • **blk1** – block/arrow name for first arrow, if DIMSAH is 1 - • **blk2** – block/arrow name for second arrow, if DIMSAH is 1 - • **ldrblk** – block/arrow name for leader - **set\_tick(size: float = 1) -\> None** Set tick *size*, which also disables arrows, a tick is just an oblique stroke as marker. - **Parameters** **size** – arrow size in drawing units - **set\_text\_align(halign: str \| None = None, valign: str \| None = None, vshift: float \| None = None) -\> None** Set measurement text alignment, *halign* defines the horizontal alignment (requires DXF R2000+), *valign* defines the vertical alignment, *above1* and *above2* means above extension line 1 or 2 and aligned with extension line. - **Parameters** - • **halign** – “left”, “right”, “center”, “above1”, “above2”, requires DXF R2000+ - • **valign** – “above”, “center”, “below” - • **vshift** – vertical text shift, if *valign* is “center”; \>0 shift upward, \<0 shift downwards - **set\_text\_format(prefix: str = '', postfix: str = '', rnd: float \| None = None, dec: int \| None = None, sep: str \| None = None, leading\_zeros: bool = True, trailing\_zeros: bool = True)** Set dimension text format, like prefix and postfix string, rounding rule and number of decimal places. - **Parameters** - • **prefix** – Dimension text prefix text as string - • **postfix** – Dimension text postfix text as string - • **rnd** – Rounds all dimensioning distances to the specified value, for instance, if DIMRND is set to 0.25, all distances round to the nearest 0.25 unit. If you set DIMRND to 1.0, all distances round to the nearest integer. - • **dec** – Sets the number of decimal places displayed for the primary units of a dimension, requires DXF R2000+ - • **sep** – “.” or “,” as decimal separator, requires DXF R2000+ - • **leading\_zeros** – Suppress leading zeros for decimal dimensions if **False** - • **trailing\_zeros** – Suppress trailing zeros for decimal dimensions if **False** - **set\_dimline\_format(color: int \| None = None, linetype: str \| None = None, lineweight: int \| None = None, extension: float \| None = None, disable1: bool \| None = None, disable2: bool \| None = None)** Set dimension line properties - **Parameters** - • **color** – color index - • **linetype** – linetype as string, requires DXF R2007+ - • **lineweight** – line weight as int, 13 = 0.13mm, 200 = 2.00mm, requires DXF R2000+ - • **extension** – extension length - • **disable1** – **True** to suppress first part of dimension line, requires DXF R2000+ - • **disable2** – **True** to suppress second part of dimension line, requires DXF R2000+ - **set\_extline\_format(color: int \| None = None, lineweight: int \| None = None, extension: float \| None = None, offset: float \| None = None, fixed\_length: float \| None = None)** Set common extension line attributes. - **Parameters** - • **color** – color index - • **lineweight** – line weight as int, 13 = 0.13mm, 200 = 2.00mm - • **extension** – extension length above dimension line - • **offset** – offset from measurement point - • **fixed\_length** – set fixed length extension line, length below the dimension line - **set\_extline1(linetype: str \| None = None, disable=False)** Set extension line 1 attributes. - **Parameters** - • **linetype** – linetype for extension line 1, requires DXF R2007+ - • **disable** – disable extension line 1 if **True** - **set\_extline2(linetype: str \| None = None, disable=False)** Set extension line 2 attributes. - **Parameters** - • **linetype** – linetype for extension line 2, requires DXF R2007+ - • **disable** – disable extension line 2 if **True** - **set\_tolerance(upper: float, lower: float \| None = None, hfactor: float = 1.0, align: *MTextLineAlignment* \| None = None, dec: int \| None = None, leading\_zeros: bool \| None = None, trailing\_zeros: bool \| None = None) -\> None** Set tolerance text format, upper and lower value, text height factor, number of decimal places or leading and trailing zero suppression. - **Parameters** - • **upper** – upper tolerance value - • **lower** – lower tolerance value, if **None** same as upper - • **hfactor** – tolerance text height factor in relation to the dimension text height - • **align** – tolerance text alignment enum *ezdxf.enums.MTextLineAlignment* requires DXF R2000+ - • **dec** – Sets the number of decimal places displayed, requires DXF R2000+ - • **leading\_zeros** – suppress leading zeros for decimal dimensions if **False**, requires DXF R2000+ - • **trailing\_zeros** – suppress trailing zeros for decimal dimensions if **False**, requires DXF R2000+ - **set\_limits(upper: float, lower: float, hfactor: float = 1.0, dec: int \| None = None, leading\_zeros: bool \| None = None, trailing\_zeros: bool \| None = None) -\> None** Set limits text format, upper and lower limit values, text height factor, number of decimal places or leading and trailing zero suppression. - **Parameters** - • **upper** – upper limit value added to measurement value - • **lower** – lower limit value subtracted from measurement value - • **hfactor** – limit text height factor in relation to the dimension text height - • **dec** – Sets the number of decimal places displayed, requires DXF R2000+ - • **leading\_zeros** – suppress leading zeros for decimal dimensions if **False**, requires DXF R2000+ - • **trailing\_zeros** – suppress trailing zeros for decimal dimensions if **False**, requires DXF R2000+ ### VPort The viewport table (*DXF Reference*) stores the modelspace viewport configurations. So this entries just modelspace viewports, not paperspace viewports, for paperspace viewports see the *Viewport* entity. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'VPORT'** | | Factory function | **Drawing.viewports.new()** | **SEE ALSO:** DXF Internals: *VPORT Configuration Table* - **class ezdxf.entities.VPort** Subclass of *DXFEntity* Defines a viewport configurations for the modelspace. - **dxf.owner** Handle to owner (*ViewportTable*). - **dxf.name** Viewport name - **dxf.flags** Standard flag values (bit-coded values): | | | | --- | --- | | 16 | If set, table entry is externally dependent on an xref | | 32 | If both this bit and bit 16 are set, the externally dependent xref has been successfully resolved | | 64 | If set, the table entry was referenced by at least one entity in the drawing the last time the drawing was edited. (This flag is only for the benefit of AutoCAD) | - **dxf.lower\_left** Lower-left corner of viewport - **dxf.upper\_right** Upper-right corner of viewport - **dxf.center** View center point (in *DCS*) - **dxf.snap\_base** Snap base point (in *DCS*) - **dxf.snap\_spacing** Snap spacing X and Y - **dxf.grid\_spacing** Grid spacing X and Y - **dxf.direction** View direction from target point (in *WCS*) - **dxf.target** View target point (in *WCS*) - **dxf.height** View height - **dxf.aspect\_ratio** - **dxf.lens\_length** Lens focal length in mm - **dxf.front\_clipping** Front clipping plane (offset from target point) - **dxf.back\_clipping** Back clipping plane (offset from target point) - **dxf.snap\_rotation** Snap rotation angle in degrees - **dxf.view\_twist** View twist angle in degrees - **dxf.status** - **dxf.view\_mode** - **dxf.circle\_zoom** - **dxf.fast\_zoom** - **dxf.ucs\_icon** - • bit 0: 0=hide, 1=show - • bit 1: 0=display in lower left corner, 1=display at origin - **dxf.snap\_on** - **dxf.grid\_on** - **dxf.snap\_style** - **dxf.snap\_isopair** - **reset\_wcs() -\> None** Reset coordinate system to the *WCS*. ### View The View table (*DXF Reference*) stores named views of the model or paperspace layouts. This stored views makes parts of the drawing or some view points of the model in a CAD applications more accessible. This views have no influence to the drawing content or to the generated output by exporting PDFs or plotting on paper sheets, they are just for the convenience of CAD application users. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'VIEW'** | | Factory function | **Drawing.views.new()** | **SEE ALSO:** DXF Internals: *VIEW Table* - **class ezdxf.entities.View** - **dxf.owner** Handle to owner (*Table*). - **dxf.name** Name of view. - **dxf.flags** Standard flag values (bit-coded values): | | | | --- | --- | | 1 | If set, this is a paper space view | | 16 | If set, table entry is externally dependent on an xref | | 32 | If both this bit and bit 16 are set, the externally dependent xref has been successfully resolved | | 64 | If set, the table entry was referenced by at least one entity in the drawing the last time the drawing was edited. (This flag is only for the benefit of AutoCAD) | - **dxf.height** View height (in DCS) - **dxf.width** View width (in DCS) - **dxf.center\_point** View center point (in DCS) - **dxf.direction\_point** View direction from target (in WCS) - **dxf.target\_point** Target point (in WCS) - **dxf.lens\_length** Lens length - **dxf.front\_clipping** Front clipping plane (offset from target point) - **dxf.back\_clipping** Back clipping plane (offset from target point) - **dxf.view\_twist** Twist angle in degrees. - **dxf.view\_mode** View mode (see VIEWMODE system variable) - **dxf.render\_mode** | | | | --- | --- | | 0 | 2D Optimized (classic 2D) | | 1 | Wireframe | | 2 | Hidden line | | 3 | Flat shaded | | 4 | Gouraud shaded | | 5 | Flat shaded with wireframe | | 6 | Gouraud shaded with wireframe | - **dxf.ucs** 1 if there is a UCS associated to this view; 0 otherwise - **dxf.ucs\_origin** UCS origin as (x, y, z) tuple (appears only if **ucs** is set to 1) - **dxf.ucs\_xaxis** UCS x-axis as (x, y, z) tuple (appears only if **ucs** is set to 1) - **dxf.ucs\_yaxis** UCS y-axis as (x, y, z) tuple (appears only if **ucs** is set to 1) - **dxf.ucs\_ortho\_type** Orthographic type of UCS (appears only if **ucs** is set to 1) | | | | --- | --- | | 0 | UCS is not orthographic | | 1 | Top | | 2 | Bottom | | 3 | Front | | 4 | Back | | 5 | Left | | 6 | Right | - **dxf.elevation** UCS elevation - **dxf.ucs\_handle** Handle of **UCSTable** if UCS is a named UCS. If not present, then UCS is unnamed (appears only if **ucs** is set to 1) - **dxf.base\_ucs\_handle** Handle of **UCSTable** of base UCS if UCS is orthographic. If not present and **ucs\_ortho\_type** is non-zero, then base UCS is taken to be WORLD (appears only if **ucs** is set to 1) - **dxf.camera\_plottable** 1 if the camera is plottable - **dxf.background\_handle** Handle to background object (optional) - **dxf.live\_selection\_handle** Handle to live section object (optional) - **dxf.visual\_style\_handle** Handle to visual style object (optional) - **dxf.sun\_handle** Sun hard ownership handle. ### AppID Defines an APPID (*DXF Reference*). These table entries maintain a set of names for all registered applications. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'APPID'** | | Factory function | **Drawing.appids.new()** | - **class ezdxf.entities.AppID** - **dxf.owner** Handle to owner (*Table*). - **dxf.name** User-supplied (or application-supplied) application name (for extended data). - **dxf.flags** Standard flag values (bit-coded values): | | | | --- | --- | | 16 | If set, table entry is externally dependent on an xref | | 32 | If both this bit and bit 16 are set, the externally dependent xref has been successfully resolved | | 64 | If set, the table entry was referenced by at least one entity in the drawing the last time the drawing was edited. (This flag is only for the benefit of AutoCAD) | ### UCS Defines an named or unnamed user coordinate system (*DXF Reference*) for usage in CAD applications. This UCS table entry does not interact with *ezdxf* in any way, to do coordinate transformations by *ezdxf* use the *ezdxf.math.UCS* class. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'UCS'** | | Factory function | **Drawing.ucs.new()** | **SEE ALSO:** *UCS* and *OCS* - **class ezdxf.entities.UCSTableEntry** - **dxf.owner** Handle to owner (*Table*). - **dxf.name** UCS name (str). - **dxf.flags** Standard flags (bit-coded values): | | | | --- | --- | | 16 | If set, table entry is externally dependent on an xref | | 32 | If both this bit and bit 16 are set, the externally dependent xref has been successfully resolved | | 64 | If set, the table entry was referenced by at least one entity in the drawing the last time the drawing was edited. (This flag is only for the benefit of AutoCAD) | - **dxf.origin** Origin as (x, y, z) tuple - **dxf.xaxis** X-axis direction as (x, y, z) tuple - **dxf.yaxis** Y-axis direction as (x, y, z) tuple - **ucs() -\> *UCS*** Returns an *ezdxf.math.UCS* object for this UCS table entry. ### BlockRecord BLOCK\_RECORD (*DXF Reference*) is the core management structure for *BlockLayout* and *Layout*. This is an internal DXF structure managed by *ezdxf*, package users don’t have to care about it. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'BLOCK\_RECORD'** | | Factory function | **Drawing.block\_records.new()** | - **class ezdxf.entities.BlockRecord** - **dxf.owner** Handle to owner (*Table*). - **dxf.name** Name of associated BLOCK. - **dxf.layout** Handle to associated **DXFLayout**, if paperspace layout or modelspace else “0” - **dxf.explode** 1 for BLOCK references can be exploded else 0 - **dxf.scale** 1 for BLOCK references can be scaled else 0 - **dxf.units** BLOCK insert units | | | | --- | --- | | 0 | Unitless | | 1 | Inches | | 2 | Feet | | 3 | Miles | | 4 | Millimeters | | 5 | Centimeters | | 6 | Meters | | 7 | Kilometers | | 8 | Microinches | | 9 | Mils | | 10 | Yards | | 11 | Angstroms | | 12 | Nanometers | | 13 | Microns | | 14 | Decimeters | | 15 | Decameters | | 16 | Hectometers | | 17 | Gigameters | | 18 | Astronomical units | | 19 | Light years | | 20 | Parsecs | | 21 | US Survey Feet | | 22 | US Survey Inch | | 23 | US Survey Yard | | 24 | US Survey Mile | - **property is\_active\_paperspace: bool** **True** if is “active” paperspace layout. - **property is\_any\_paperspace: bool** **True** if is any kind of paperspace layout. - **property is\_any\_layout: bool** **True** if is any kind of modelspace or paperspace layout. - **property is\_block\_layout: bool** **True** if not any kind of modelspace or paperspace layout, just a regular block definition. - **property is\_modelspace: bool** **True** if is the modelspace layout. - **property is\_xref: bool** **True** if represents an XREF (external reference) or XREF\_OVERLAY. ### Internal Structure Do not change this structures, this is just an information for experienced developers! The BLOCK\_RECORD is the owner of all the entities in a layout and stores them in an *EntitySpace* object (**BlockRecord.entity\_space**). For each layout exist a BLOCK definition in the BLOCKS section, a reference to the *Block* entity is stored in **BlockRecord.block**. *Modelspace* and *Paperspace* layouts require an additional *DXFLayout* object in the OBJECTS section. **SEE ALSO:** More information about *Block Management Structures* and *Layout Management Structures*. ### Blocks A block definition (*BlockLayout*) is a collection of DXF entities, which can be placed multiply times at different layouts or other blocks as references to the block definition. Block layouts are located in the BLOCKS sections and are accessible by the *blocks* attribute of the *Drawing* class. **SEE ALSO:** *Tutorial for Blocks* and DXF Internals: *Block Management Structures* ### Block BLOCK (*DXF Reference*) entity is embedded into the *BlockLayout* object. The BLOCK entity is accessible by the **BlockLayout.block** attribute. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'BLOCK'** | | Factory function | **Drawing.blocks.new()** (returns a *BlockLayout*) | **SEE ALSO:** *Tutorial for Blocks* and DXF Internals: *Block Management Structures* - **class ezdxf.entities.Block** - **dxf.handle** BLOCK handle as plain hex string. (feature for experts) - **dxf.owner** Handle to owner as plain hex string. (feature for experts) - **dxf.layer** Layer name as string; default value is **'0'** - **dxf.name** BLOCK name as string. (case insensitive) - **dxf.base\_point** BLOCK base point as **(x, y, z)** tuple, default value is **(0, 0, 0)** Insertion location referenced by the *Insert* entity to place the block reference and also the center of rotation and scaling. - **dxf.flags** BLOCK flags (bit-coded) | | | | --- | --- | | 1 | Anonymous block generated by hatching, associative dimensioning, other internal operations, or an application | | 2 | Block has non-constant attribute definitions (this bit is not set if the block has any attribute definitions that are constant, or has no attribute definitions at all) | | 4 | Block is an external reference (xref) | | 8 | Block is an xref overlay | | 16 | Block is externally dependent | | 32 | This is a resolved external reference, or dependent of an external reference (ignored on input) | | 64 | This definition is a referenced external reference (ignored on input) | - **dxf.xref\_path** File system path as string, if this block defines an external reference (XREF). - **is\_layout\_block** Returns **True** if this is a *Modelspace* or *Paperspace* block definition. - **is\_anonymous** Returns **True** if this is an anonymous block generated by hatching, associative dimensioning, other internal operations, or an application. - **is\_xref** Returns **True** if bock is an external referenced file. - **is\_xref\_overlay** Returns **True** if bock is an external referenced overlay file. ### EndBlk ENDBLK entity is embedded into the *BlockLayout* object. The ENDBLK entity is accessible by the **BlockLayout.endblk** attribute. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | | DXF type | **'ENDBLK'** | - **class ezdxf.entities.EndBlk** - **dxf.handle** BLOCK handle as plain hex string. (feature for experts) - **dxf.owner** Handle to owner as plain hex string. (feature for experts) - **dxf.layer** Layer name as string; should always be the same as *Block.dxf.layer* ### Insert The INSERT entity (*DXF Reference*) represents a block reference with optional attached attributes as (*Attrib*) entities. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'INSERT'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_blockref()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **SEE ALSO:** *Tutorial for Blocks* **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Insert** - **dxf.name** BLOCK name (str) - **dxf.insert** Insertion location of the BLOCK base point as (2D/3D Point in *OCS*) - **dxf.xscale** Scale factor for x direction (float) - **dxf.yscale** Scale factor for y direction (float) Not all CAD applications support non-uniform scaling (e.g. LibreCAD). - **dxf.zscale** Scale factor for z direction (float) Not all CAD applications support non-uniform scaling (e.g. LibreCAD). - **dxf.rotation** Rotation angle in degrees (float) - **dxf.row\_count** Count of repeated insertions in row direction, MINSERT entity if \> 1 (int) - **dxf.row\_spacing** Distance between two insert points (MINSERT) in row direction (float) - **dxf.column\_count** Count of repeated insertions in column direction, MINSERT entity if \> 1 (int) - **dxf.column\_spacing** Distance between two insert points (MINSERT) in column direction (float) - **attribs** A list of all attached *Attrib* entities. - **has\_scaling** Returns **True** if scaling is applied to any axis. - **has\_uniform\_scaling** Returns **True** if the scale factor is uniform for x-, y- and z-axis, ignoring reflections e.g. (1, 1, -1) is uniform scaling. - **mcount** Returns the multi-insert count, MINSERT (multi-insert) processing is required if *mcount* \> 1. - **set\_scale(factor: float)** Set a uniform scale factor. - **block() -\> *BlockLayout* \| None** Returns the associated *BlockLayout*. - **place(insert: *UVec* \| None = None, scale: tuple\[float, float, float\] \| None = None, rotation: float \| None = None) -\> Insert** Set the location, scaling and rotation attributes. Arguments which are **None** will be ignored. - **Parameters** - • **insert** – insert location as (x, y \[,z\]) tuple - • **scale** – (x-scale, y-scale, z-scale) tuple - • **rotation** – rotation angle in degrees - **grid(size: tuple\[int, int\] = (1, 1), spacing: tuple\[float, float\] = (1, 1)) -\> Insert** Place block reference in a grid layout, grid *size* defines the row- and column count, *spacing* defines the distance between two block references. - **Parameters** - • **size** – grid size as (row\_count, column\_count) tuple - • **spacing** – distance between placing as (row\_spacing, column\_spacing) tuple - **has\_attrib(tag: str, search\_const: bool = False) -\> bool** Returns **True** if the INSERT entity has an attached ATTRIB entity with the given *tag*. Some applications do not attach constant ATTRIB entities, set *search\_const* to **True**, to check for an associated *AttDef* entity with constant content. - **Parameters** - • **tag** – tag name fo the ATTRIB entity - • **search\_const** – search also const ATTDEF entities - **get\_attrib(tag: str, search\_const: bool = False) -\> *Attrib* \| *AttDef* \| None** Get an attached *Attrib* entity with the given *tag*, returns **None** if not found. Some applications do not attach constant ATTRIB entities, set *search\_const* to **True**, to get at least the associated *AttDef* entity. - **Parameters** - • **tag** – tag name of the ATTRIB entity - • **search\_const** – search also const ATTDEF entities - **get\_attrib\_text(tag: str, default: str = '', search\_const: bool = False) -\> str** Get content text of an attached *Attrib* entity with the given *tag*, returns the *default* value if not found. Some applications do not attach constant ATTRIB entities, set *search\_const* to **True**, to get content text of the associated *AttDef* entity. - **Parameters** - • **tag** – tag name of the ATTRIB entity - • **default** – default value if ATTRIB *tag* is absent - • **search\_const** – search also const ATTDEF entities - **add\_attrib(tag: str, text: str, insert: *UVec* = (0, 0), dxfattribs=None) -\> Attrib** Attach an *Attrib* entity to the block reference. Example for appending an attribute to an INSERT entity: ``` e.add_attrib('EXAMPLETAG', 'example text').set_placement( (3, 7), align=TextEntityAlignment.MIDDLE_CENTER ) ``` - **Parameters** - • **tag** – tag name of the ATTRIB entity - • **text** – content text as string - • **insert** – insert location as (x, y\[, z\]) tuple in *OCS* - • **dxfattribs** – additional DXF attributes for the ATTRIB entity - **add\_auto\_attribs(values: dict\[str, str\]) -\> Insert** Attach for each **Attdef** entity, defined in the block definition, automatically an *Attrib* entity to the block reference and set **tag/value** DXF attributes of the ATTRIB entities by the **key/value** pairs (both as strings) of the *values* dict. The ATTRIB entities are placed relative to the insert location of the block reference, which is identical to the block base point. This method avoids the wrapper block of the *add\_auto\_blockref()* method, but the visual results may not match the results of CAD applications, especially for non-uniform scaling. If the visual result is very important to you, use the **add\_auto\_blockref()** method. - **Parameters** **values** – *Attrib* tag values as **tag/value** pairs - **delete\_attrib(tag: str, ignore=False) -\> None** Delete an attached *Attrib* entity from INSERT. Raises an **DXFKeyError** exception, if no ATTRIB for the given *tag* exist if *ignore* is **False**. - **Parameters** - • **tag** – tag name of the ATTRIB entity - • **ignore** – **False** for raising **DXFKeyError** if ATTRIB *tag* does not exist. - **Raises** *DXFKeyError* – no ATTRIB for the given *tag* exist - **delete\_all\_attribs() -\> None** Delete all *Attrib* entities attached to the INSERT entity. - **transform(m: *Matrix44*) -\> Insert** Transform INSERT entity by transformation matrix *m* inplace. Unlike the transformation matrix *m*, the INSERT entity can not represent a non-orthogonal target coordinate system and an **InsertTransformationError** will be raised in that case. - **translate(dx: float, dy: float, dz: float) -\> Insert** Optimized INSERT translation about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis. - **virtual\_entities(\*, skipped\_entity\_callback: Callable\[\[DXFGraphic, str\], None\] \| None = None, redraw\_order=False) -\> Iterator\[DXFGraphic\]** Yields the transformed referenced block content as virtual entities. This method is meant to examine the block reference entities at the target location without exploding the block reference. These entities are not stored in the entity database, have no handle and are not assigned to any layout. It is possible to convert these entities into regular drawing entities by adding the entities to the entities database and a layout of the same DXF document as the block reference: ``` doc.entitydb.add(entity) msp = doc.modelspace() msp.add_entity(entity) ``` **WARNING:** **Non-uniform scale factors** may return incorrect results for some entities (TEXT, MTEXT, ATTRIB). This method does not resolve the MINSERT attributes, only the sub-entities of the first INSERT will be returned. To resolve MINSERT entities check if multi insert processing is required, that’s the case if the property *Insert.mcount* \> 1, use the *Insert.multi\_insert()* method to resolve the MINSERT entity into multiple INSERT entities. This method does not apply the clipping path created by the XCLIP command. The method returns all entities and ignores the clipping path polygon and no entity is clipped. The *skipped\_entity\_callback()* will be called for all entities which are not processed, signature: **skipped\_entity\_callback(entity: DXFEntity, reason: str)**, *entity* is the original (untransformed) DXF entity of the block definition, the *reason* string is an explanation why the entity was skipped. - **Parameters** - • **skipped\_entity\_callback** – called whenever the transformation of an entity is not supported and so was skipped - • **redraw\_order** – yield entities in ascending redraw order if **True** - **multi\_insert() -\> Iterator\[Insert\]** Yields a virtual INSERT entity for each grid element of a MINSERT entity (multi-insert). - **explode(target\_layout: *BaseLayout* \| None = None, \*, redraw\_order=False) -\> *EntityQuery*** Explodes the block reference entities into the target layout, if target layout is **None**, the layout of the block reference will be used. This method destroys the source block reference entity. Transforms the block entities into the required *WCS* location by applying the block reference attributes *insert*, *extrusion*, *rotation* and the scale factors *xscale*, *yscale* and *zscale*. Attached ATTRIB entities are converted to TEXT entities, this is the behavior of the BURST command of the AutoCAD Express Tools. **WARNING:** **Non-uniform scale factors** may lead to incorrect results some entities (TEXT, MTEXT, ATTRIB). - **Parameters** - • **target\_layout** – target layout for exploded entities, **None** for same layout as source entity. - • **redraw\_order** – create entities in ascending redraw order if **True** - **Returns** *EntityQuery* container referencing all exploded DXF entities. - **ucs()** Returns the block reference coordinate system as *ezdxf.math.UCS* object. - **matrix44() -\> *Matrix44*** Returns a transformation matrix to transform the block entities from the block reference coordinate system into the *WCS*. - **reset\_transformation() -\> None** Reset block reference attributes location, rotation angle and the extrusion vector but preserves the scale factors. ### Attrib The ATTRIB (*DXF Reference*) entity represents a text value associated with a tag. In most cases an ATTRIB is appended to an *Insert* entity, but it can also be used as a standalone entity. | | | | --- | --- | | Subclass of | *ezdxf.entities.Text* | | DXF type | **'ATTRIB'** | | Factory function | **ezdxf.layouts.BaseLayout.add\_attrib()** (stand alone entity) | | Factory function | *Insert.add\_attrib()* (attached to *Insert*) | | Inherited DXF attributes | *Common graphical DXF attributes* | **SEE ALSO:** *Tutorial for Blocks* **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Attrib** ATTRIB supports all DXF attributes and methods of parent class *Text*. - **dxf.tag** Tag to identify the attribute (str) - **dxf.text** Attribute content as text (str) - **property is\_invisible: bool** Attribute is invisible if **True**. - **property is\_const: bool** This is a constant attribute if **True**. - **property is\_verify: bool** Verification is required on input of this attribute. (interactive CAD application feature) - **property is\_preset: bool** No prompt during insertion. (interactive CAD application feature) - **property has\_embedded\_mtext\_entity: bool** Returns **True** if the entity has an embedded MTEXT entity for multi-line support. - **virtual\_mtext\_entity() -\> MText** Returns the embedded MTEXT entity as a regular but virtual *MText* entity with the same graphical properties as the host entity. - **plain\_mtext(fast=True) -\> str** Returns the embedded MTEXT content without formatting codes. Returns an empty string if no embedded MTEXT entity exist. The *fast* mode is accurate if the DXF content was created by reliable (and newer) CAD applications like AutoCAD or BricsCAD. The *accurate* mode is for some rare cases where the content was created by older CAD applications or unreliable DXF libraries and CAD applications. The *accurate* mode is **much** slower than the *fast* mode. - **Parameters** **fast** – uses the *fast* mode to extract the plain MTEXT content if **True** or the *accurate* mode if set to **False** - **set\_mtext(mtext: MText, graphic\_properties=True) -\> None** Set multi-line properties from a *MText* entity. The multi-line ATTRIB/ATTDEF entity requires DXF R2018, otherwise an ordinary single line ATTRIB/ATTDEF entity will be exported. - **Parameters** - • **mtext** – source *MText* entity - • **graphic\_properties** – copy graphic properties (color, layer, …) from source MTEXT if **True** - **embed\_mtext(mtext: MText, graphic\_properties=True) -\> None** Set multi-line properties from a *MText* entity and destroy the source entity afterward. The multi-line ATTRIB/ATTDEF entity requires DXF R2018, otherwise an ordinary single line ATTRIB/ATTDEF entity will be exported. - **Parameters** - • **mtext** – source *MText* entity - • **graphic\_properties** – copy graphic properties (color, layer, …) from source MTEXT if **True** - **discard\_mtext() -\> None** Discard multi-line feature. The embedded MTEXT will be removed and the ATTRIB/ATTDEF will be converted to a single-line attribute. ### AttDef The ATTDEF (*DXF Reference*) entity is a template in a *BlockLayout*, which will be used to create an attached *Attrib* entity for an *Insert* entity. | | | | --- | --- | | Subclass of | *ezdxf.entities.Text* | | DXF type | **'ATTDEF'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_attdef()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **SEE ALSO:** *Tutorial for Blocks* **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.AttDef** ATTDEF supports all DXF attributes and methods of parent class *Text*. - **dxf.tag** Tag to identify the attribute (str) - **dxf.text** Attribute content as text (str) - **dxf.prompt** Attribute prompt string. (CAD application feature) - **dxf.field\_length** Just relevant to CAD programs for validating user input - **property is\_invisible: bool** Attribute is invisible if **True**. - **property is\_const: bool** This is a constant attribute if **True**. - **property is\_verify: bool** Verification is required on input of this attribute. (interactive CAD application feature) - **property is\_preset: bool** No prompt during insertion. (interactive CAD application feature) - **property has\_embedded\_mtext\_entity: bool** Returns **True** if the entity has an embedded MTEXT entity for multi-line support. - **virtual\_mtext\_entity() -\> MText** Returns the embedded MTEXT entity as a regular but virtual *MText* entity with the same graphical properties as the host entity. - **plain\_mtext(fast=True) -\> str** Returns the embedded MTEXT content without formatting codes. Returns an empty string if no embedded MTEXT entity exist. The *fast* mode is accurate if the DXF content was created by reliable (and newer) CAD applications like AutoCAD or BricsCAD. The *accurate* mode is for some rare cases where the content was created by older CAD applications or unreliable DXF libraries and CAD applications. The *accurate* mode is **much** slower than the *fast* mode. - **Parameters** **fast** – uses the *fast* mode to extract the plain MTEXT content if **True** or the *accurate* mode if set to **False** - **set\_mtext(mtext: MText, graphic\_properties=True) -\> None** Set multi-line properties from a *MText* entity. The multi-line ATTRIB/ATTDEF entity requires DXF R2018, otherwise an ordinary single line ATTRIB/ATTDEF entity will be exported. - **Parameters** - • **mtext** – source *MText* entity - • **graphic\_properties** – copy graphic properties (color, layer, …) from source MTEXT if **True** - **embed\_mtext(mtext: MText, graphic\_properties=True) -\> None** Set multi-line properties from a *MText* entity and destroy the source entity afterward. The multi-line ATTRIB/ATTDEF entity requires DXF R2018, otherwise an ordinary single line ATTRIB/ATTDEF entity will be exported. - **Parameters** - • **mtext** – source *MText* entity - • **graphic\_properties** – copy graphic properties (color, layer, …) from source MTEXT if **True** - **discard\_mtext() -\> None** Discard multi-line feature. The embedded MTEXT will be removed and the ATTRIB/ATTDEF will be converted to a single-line attribute. ### Layouts ### Layout Manager The layout manager is unique to each DXF drawing, access the layout manager as *layouts* attribute of the *Drawing* object (e.g. **doc.layouts.rename("Layout1", "PlanView")**). - **class ezdxf.layouts.Layouts** The *Layouts* class manages *Paperspace* layouts and the *Modelspace*. - **\_\_len\_\_() -\> int** Returns count of existing layouts, including the modelspace layout. - **\_\_contains\_\_(name: str) -\> bool** Returns **True** if layout *name* exist. - **\_\_iter\_\_() -\> Iterator\[Layout\]** Returns iterable of all layouts as *Layout* objects, including the modelspace layout. - **names() -\> list\[str\]** Returns a list of all layout names, all names in original case-sensitive form. - **names\_in\_taborder() -\> list\[str\]** Returns all layout names in tab order as shown in *CAD* applications. - **modelspace() -\> Modelspace** Returns the *Modelspace* layout. - **get(name: str \| None) -\> Layout** Returns *Layout* by *name*, case-insensitive “Model” == “MODEL”. - **Parameters** **name** – layout name as shown in tab, e.g. **'Model'** for modelspace - **new(name: str, dxfattribs=None) -\> Paperspace** Returns a new *Paperspace* layout. - **Parameters** - • **name** – layout name as shown in tabs in *CAD* applications - • **dxfattribs** – additional DXF attributes for the **DXFLayout** entity - **Raises** - • *DXFValueError* – Invalid characters in layout name. - • *DXFValueError* – Layout *name* already exist. - **rename(old\_name: str, new\_name: str) -\> None** Rename a layout from *old\_name* to *new\_name*. Can not rename layout **'Model'** and the new name of a layout must not exist. - **Parameters** - • **old\_name** – actual layout name, case-insensitive - • **new\_name** – new layout name, case-insensitive - **Raises** - • *DXFValueError* – try to rename **'Model'** - • *DXFValueError* – Layout *new\_name* already exist. - **delete(name: str) -\> None** Delete layout *name* and destroy all entities in that layout. - **Parameters** **name** (*str*) – layout name as shown in tabs - **Raises** - • *DXFKeyError* – if layout *name* do not exist - • *DXFValueError* – deleting modelspace layout is not possible - • *DXFValueError* – deleting last paperspace layout is not possible - **active\_layout() -\> Paperspace** Returns the active paperspace layout. - **set\_active\_layout(name: str) -\> None** Set layout *name* as active paperspace layout. - **get\_layout\_for\_entity(entity: DXFEntity) -\> Layout** Returns the owner layout for a DXF *entity*. ### Layout Types A Layout represents and manages DXF entities, there are three different layout objects: - • *Modelspace* is the common working space, containing basic drawing entities. - • *Paperspace* is the arrangement of objects for printing and plotting, this layout contains basic drawing entities and viewports to the *Modelspace*. - • *BlockLayout* works on an associated **Block**, Blocks are collections of DXF entities for reusing by block references. **WARNING:** Do not instantiate layout classes by yourself - always use the provided factory functions! ### Entity Ownership A layout owns all entities residing in their entity space, therefore the **dxf.owner** attribute of any *DXFGraphic* entity in this layout is the **dxf.handle** of the layout, and deleting an entity from a layout is the end of life of this entity, because it is also deleted from the *EntityDB*. It’s possible to just unlink an entity from a layout to assign the entity to another layout, use the *move\_to\_layout()* method to move entities between layouts. ### BaseLayout - **class ezdxf.layouts.BaseLayout** *BaseLayout* is the common base class for *Layout* and *BlockLayout*. - **is\_alive** **False** if layout is deleted. - **is\_active\_paperspace** **True** if is active layout. - **is\_any\_paperspace** **True** if is any kind of paperspace layout. - **is\_modelspace** **True** if is modelspace layout. - **is\_any\_layout** **True** if is any kind of modelspace or paperspace layout. - **is\_block\_layout** **True** if not any kind of modelspace or paperspace layout, just a regular block definition. - **units** *set* *drawing units*. - **Type** Get/Set layout/block drawing units as enum, see also - **Type** ref - **\_\_len\_\_() -\> int** Returns count of entities owned by the layout. - **\_\_iter\_\_() -\> Iterator\[*DXFGraphic*\]** Returns iterable of all drawing entities in this layout. - **\_\_getitem\_\_(index)** Get entity at *index*. The underlying data structure for storing entities is organized like a standard Python list, therefore *index* can be any valid list indexing or slicing term, like a single index **layout\[-1\]** to get the last entity, or an index slice **layout\[:10\]** to get the first 10 or less entities as **list\[DXFGraphic\]**. - **get\_extension\_dict() -\> *ExtensionDict*** Returns the associated extension dictionary, creates a new one if necessary. - **delete\_entity(entity: *DXFGraphic*) -\> None** Delete *entity* from layout entity space and the entity database, this destroys the *entity*. - **delete\_all\_entities() -\> None** Delete all entities from this layout and from entity database, this destroys all entities in this layout. - **unlink\_entity(entity: *DXFGraphic*) -\> None** Unlink *entity* from layout but does not delete entity from the entity database, this removes *entity* just from the layout entity space. - **purge()** Remove all destroyed entities from the layout entity space. - **query(query: str = '\*') -\> *EntityQuery*** Get all DXF entities matching the *Entity Query String*. - **groupby(dxfattrib: str = '', key: KeyFunc \| None = None) -\> dict** Returns a **dict** of entity lists, where entities are grouped by a *dxfattrib* or a *key* function. - **Parameters** - • **dxfattrib** – grouping by DXF attribute like **'layer'** - • **key** – key function, which accepts a **DXFGraphic** entity as argument and returns the grouping key of an entity or **None** to ignore the entity. Reason for ignoring: a queried DXF attribute is not supported by entity. - **move\_to\_layout(entity: *DXFGraphic*, layout: *BaseLayout*) -\> None** Move entity to another layout. - **Parameters** - • **entity** – DXF entity to move - • **layout** – any layout (modelspace, paperspace, block) from **same** drawing - **set\_redraw\_order(handles: dict \| Iterable\[tuple\[str, str\]\]) -\> None** If the header variable $SORTENTS *Regen* flag (bit-code value 16) is set, AutoCAD regenerates entities in ascending handles order. To change redraw order associate a different sort-handle to entities, this redefines the order in which the entities are regenerated. The *handles* argument can be a dict of entity\_handle and sort\_handle as (k, v) pairs, or an iterable of (entity\_handle, sort\_handle) tuples. The sort-handle doesn’t have to be unique, some or all entities can share the same sort-handle and a sort-handle can be an existing handle. The “0” handle can be used, but this sort-handle will be drawn as latest (on top of all other entities) and not as first as expected. - **Parameters** **handles** – iterable or dict of handle associations; an iterable of 2-tuples (entity\_handle, sort\_handle) or a dict (k, v) association as (entity\_handle, sort\_handle) - **get\_redraw\_order() -\> Iterable\[tuple\[str, str\]\]** Returns iterable for all existing table entries as (entity\_handle, sort\_handle) pairs, see also *set\_redraw\_order()*. - **entities\_in\_redraw\_order(reverse=False) -\> Iterable\[*DXFGraphic*\]** Yields all entities from layout in ascending redraw order or descending redraw order if *reverse* is **True**. - **add\_entity(entity: *DXFGraphic*) -\> None** Add an existing **DXFGraphic** entity to a layout, but be sure to unlink (*unlink\_entity()*) *entity* from the previous owner layout. Adding entities from a different DXF drawing is not supported. **WARNING:** This is a low-level tool - use it with caution and make sure you understand what you are doing! If used improperly, the DXF document may be damaged. - **add\_foreign\_entity(entity: *DXFGraphic*, copy=True) -\> None** Add a foreign DXF entity to a layout, this foreign entity could be from another DXF document or an entity without an assigned DXF document. The intention of this method is to add **simple** entities from another DXF document or from a DXF iterator, for more complex operations use the *importer* add-on. Especially objects with BLOCK section (INSERT, DIMENSION, MLEADER) or OBJECTS section dependencies (IMAGE, UNDERLAY) can not be supported by this simple method. Not all DXF types are supported and every dependency or resource reference from another DXF document will be removed except attribute layer will be preserved but only with default attributes like color **7** and linetype **CONTINUOUS** because the layer attribute doesn’t need a layer table entry. If the entity is part of another DXF document, it will be unlinked from this document and its entity database if argument *copy* is **False**, else the entity will be copied. Unassigned entities like from DXF iterators will just be added. Supported DXF types: - • POINT - • LINE - • CIRCLE - • ARC - • ELLIPSE - • LWPOLYLINE - • SPLINE - • POLYLINE - • 3DFACE - • SOLID - • TRACE - • SHAPE - • MESH - • ATTRIB - • ATTDEF - • TEXT - • MTEXT - • HATCH - **Parameters** - • **entity** – DXF entity to copy or move - • **copy** – if **True** copy entity from other document else unlink from other document - **Raises** **CopyNotSupported** – copying of *entity* i not supported - **add\_point(location: *UVec*, dxfattribs=None) -\> Point** Add a *Point* entity at *location*. - **Parameters** - • **location** – 2D/3D point in *WCS* - • **dxfattribs** – additional DXF attributes - **add\_line(start: *UVec*, end: *UVec*, dxfattribs=None) -\> Line** Add a *Line* entity from *start* to *end*. - **Parameters** - • **start** – 2D/3D point in *WCS* - • **end** – 2D/3D point in *WCS* - • **dxfattribs** – additional DXF attributes - **add\_circle(center: *UVec*, radius: float, dxfattribs=None) -\> Circle** Add a *Circle* entity. This is an 2D element, which can be placed in space by using *OCS*. - **Parameters** - • **center** – 2D/3D point in *WCS* - • **radius** – circle radius - • **dxfattribs** – additional DXF attributes - **add\_ellipse(center: *UVec*, major\_axis: *UVec* = (1, 0, 0), ratio: float = 1, start\_param: float = 0, end\_param: float = math.tau, dxfattribs=None) -\> *Ellipse*** Add an *Ellipse* entity, *ratio* is the ratio of minor axis to major axis, *start\_param* and *end\_param* defines start and end point of the ellipse, a full ellipse goes from 0 to 2π. The ellipse goes from start to end param in *counter-clockwise* direction. - **Parameters** - • **center** – center of ellipse as 2D/3D point in *WCS* - • **major\_axis** – major axis as vector (x, y, z) - • **ratio** – ratio of minor axis to major axis in range +/-\[1e-6, 1.0\] - • **start\_param** – start of ellipse curve - • **end\_param** – end param of ellipse curve - • **dxfattribs** – additional DXF attributes - **add\_arc(center: *UVec*, radius: float, start\_angle: float, end\_angle: float, is\_counter\_clockwise: bool = True, dxfattribs=None) -\> *Arc*** Add an *Arc* entity. The arc goes from *start\_angle* to *end\_angle* in counter-clockwise direction by default, set parameter *is\_counter\_clockwise* to **False** for clockwise orientation. - **Parameters** - • **center** – center of arc as 2D/3D point in *WCS* - • **radius** – arc radius - • **start\_angle** – start angle in degrees - • **end\_angle** – end angle in degrees - • **is\_counter\_clockwise** – **False** for clockwise orientation - • **dxfattribs** – additional DXF attributes - **add\_solid(points: Iterable\[*UVec*\], dxfattribs=None) -\> *Solid*** Add a *Solid* entity, *points* is an iterable of 3 or 4 points. **HINT:** The last two vertices are in reversed order: a square has the vertex order 0-1-3-2 - **Parameters** - • **points** – iterable of 3 or 4 2D/3D points in *WCS* - • **dxfattribs** – additional DXF attributes - **add\_trace(points: Iterable\[*UVec*\], dxfattribs=None) -\> *Trace*** Add a *Trace* entity, *points* is an iterable of 3 or 4 points. **HINT:** The last two vertices are in reversed order: a square has the vertex order 0-1-3-2 - **Parameters** - • **points** – iterable of 3 or 4 2D/3D points in *WCS* - • **dxfattribs** – additional DXF attributes - **add\_3dface(points: Iterable\[*UVec*\], dxfattribs=None) -\> *Face3d*** Add a **3DFace** entity, *points* is an iterable 3 or 4 2D/3D points. **HINT:** In contrast to SOLID and TRACE, the last two vertices are in regular order: a square has the vertex order 0-1-2-3 - **Parameters** - • **points** – iterable of 3 or 4 2D/3D points in *WCS* - • **dxfattribs** – additional DXF attributes - **add\_text(text: str, \*, height: float \| None = None, rotation: float \| None = None, dxfattribs=None) -\> *Text*** Add a *Text* entity, see also *Textstyle*. - **Parameters** - • **text** – content string - • **height** – text height in drawing units - • **rotation** – text rotation in degrees - • **dxfattribs** – additional DXF attributes - **add\_blockref(name: str, insert: *UVec*, dxfattribs=None) -\> *Insert*** Add an *Insert* entity. When inserting a block reference into the modelspace or another block layout with different units, the scaling factor between these units should be applied as scaling attributes (**xscale**, …) e.g. modelspace in meters and block in centimeters, **xscale** has to be 0.01. - **Parameters** - • **name** – block name as str - • **insert** – insert location as 2D/3D point in *WCS* - • **dxfattribs** – additional DXF attributes - **add\_auto\_blockref(name: str, insert: *UVec*, values: dict\[str, str\], dxfattribs=None) -\> *Insert*** Add an *Insert* entity. This method adds for each **Attdef** entity, defined in the block definition, automatically an **Attrib** entity to the block reference and set (tag, value) DXF attributes of the ATTRIB entities by the (key, value) pairs (both as strings) of the *values* dict. The Attrib entities are placed relative to the insert point, which is equal to the block base point. This method wraps the INSERT and all the ATTRIB entities into an anonymous block, which produces the best visual results, especially for non-uniform scaled block references, because the transformation and scaling is done by the CAD application. But this makes evaluation of block references with attributes more complicated, if you prefer INSERT and ATTRIB entities without a wrapper block use the **add\_blockref\_with\_attribs()** method. - **Parameters** - • **name** – block name - • **insert** – insert location as 2D/3D point in *WCS* - • **values** – *Attrib* tag values as (tag, value) pairs - • **dxfattribs** – additional DXF attributes - **add\_attdef(tag: str, insert: *UVec* = (0, 0), text: str = '', \*, height: float \| None = None, rotation: float \| None = None, dxfattribs=None) -\> *AttDef*** Add an *AttDef* as stand alone DXF entity. Set position and alignment by the idiom: ``` layout.add_attdef("NAME").set_placement( (2, 3), align=TextEntityAlignment.MIDDLE_CENTER ) ``` - **Parameters** - • **tag** – tag name as string - • **insert** – insert location as 2D/3D point in *WCS* - • **text** – tag value as string - • **height** – text height in drawing units - • **rotation** – text rotation in degrees - • **dxfattribs** – additional DXF attributes - **add\_polyline2d(points: Iterable\[*UVec*\], format: str \| None = None, \*, close: bool = False, dxfattribs=None) -\> *Polyline*** Add a 2D *Polyline* entity. - **Parameters** - • **points** – iterable of 2D points in *WCS* - • **close** – **True** for a closed polyline - • **format** – user defined point format like *add\_lwpolyline()*, default is **None** - • **dxfattribs** – additional DXF attributes - **add\_polyline3d(points: Iterable\[*UVec*\], \*, close: bool = False, dxfattribs=None) -\> *Polyline*** Add a 3D *Polyline* entity. - **Parameters** - • **points** – iterable of 3D points in *WCS* - • **close** – **True** for a closed polyline - • **dxfattribs** – additional DXF attributes - **add\_polymesh(size: tuple\[int, int\] = (3, 3), dxfattribs=None) -\> *Polymesh*** Add a *Polymesh* entity, which is a wrapper class for the POLYLINE entity. A polymesh is a grid of *mcount* x *ncount* vertices and every vertex has its own (x, y, z)-coordinates. - **Parameters** - • **size** – 2-tuple (*mcount*, *ncount*) - • **dxfattribs** – additional DXF attributes - **add\_polyface(dxfattribs=None) -\> *Polyface*** Add a *Polyface* entity, which is a wrapper class for the POLYLINE entity. - **Parameters** **dxfattribs** – additional DXF attributes for *Polyline* entity - **add\_shape(name: str, insert: *UVec* = (0, 0), size: float = 1.0, dxfattribs=None) -\> *Shape*** Add a *Shape* reference to an external stored shape. - **Parameters** - • **name** – shape name as string - • **insert** – insert location as 2D/3D point in *WCS* - • **size** – size factor - • **dxfattribs** – additional DXF attributes - **add\_lwpolyline(points: Iterable\[*UVec*\], format: str = 'xyseb', \*, close: bool = False, dxfattribs=None) -\> *LWPolyline*** Add a 2D polyline as *LWPolyline* entity. A points are defined as (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuples, but order can be redefined by the *format* argument. Set *start\_width*, *end\_width* to 0 to be ignored like (x, y, 0, 0, bulge). The *LWPolyline* is defined as a single DXF entity and needs less disk space than a *Polyline* entity. (requires DXF R2000) Format codes: - • **x** = x-coordinate - • **y** = y-coordinate - • **s** = start width - • **e** = end width - • **b** = bulge value - • **v** = (x, y \[,z\]) tuple (z-axis is ignored) - **Parameters** - • **points** – iterable of (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuples - • **format** – user defined point format, default is “xyseb” - • **close** – **True** for a closed polyline - • **dxfattribs** – additional DXF attributes - **add\_mtext(text: str, dxfattribs=None) -\> *MText*** Add a multiline text entity with automatic text wrapping at boundaries as *MText* entity. (requires DXF R2000) - **Parameters** - • **text** – content string - • **dxfattribs** – additional DXF attributes - **add\_mtext\_static\_columns(content: Iterable\[str\], width: float, gutter\_width: float, height: float, dxfattribs=None) -\> *MText*** Add a multiline text entity with static columns as *MText* entity. The content is spread across the columns, the count of content strings determine the count of columns. This factory method adds automatically a column break **"\\N"** at the end of each column text to force a new column. The *height* attribute should be big enough to reserve enough space for the tallest column. Too small values produce valid DXF files, but the visual result will not be as expected. The *height* attribute also defines the total height of the MTEXT entity. (requires DXF R2000) - **Parameters** - • **content** – iterable of column content - • **width** – column width - • **gutter\_width** – distance between columns - • **height** – max. column height - • **dxfattribs** – additional DXF attributes - **add\_mtext\_dynamic\_manual\_height\_columns(content: str, width: float, gutter\_width: float, heights: Sequence\[float\], dxfattribs=None) -\> *MText*** Add a multiline text entity with dynamic columns as *MText* entity. The content is spread across the columns automatically by the CAD application. The *heights* sequence determine the height of the columns, except for the last column, which always takes the remaining content. The height value for the last column is required but can be 0, because the value is ignored. The count of *heights* also determines the count of columns, and **max(heights)** defines the total height of the MTEXT entity, which may be wrong if the last column requires more space. This current implementation works best for DXF R2018, because the content is stored as a continuous text in a single MTEXT entity. For DXF versions prior to R2018 the content should be distributed across multiple MTEXT entities (one entity per column), which is not done by *ezdxf*, but the result is correct for advanced DXF viewers and CAD application, which do the MTEXT content distribution completely by itself. (requires DXF R2000) - **Parameters** - • **content** – column content as a single string - • **width** – column width - • **gutter\_width** – distance between columns - • **heights** – column height for each column - • **dxfattribs** – additional DXF attributes - **add\_mtext\_dynamic\_auto\_height\_columns(content: str, width: float, gutter\_width: float, height: float, count: int, dxfattribs=None) -\> *MText*** Add a multiline text entity with as many columns as needed for the given common fixed *height*. The content is spread across the columns automatically by the CAD application. The *height* argument also defines the total height of the MTEXT entity. To get the correct column *count* requires an **exact** MTEXT rendering like AutoCAD, which is not done by *ezdxf*, therefore passing the expected column *count* is required to calculate the correct total width. This current implementation works best for DXF R2018, because the content is stored as a continuous text in a single MTEXT entity. For DXF versions prior to R2018 the content should be distributed across multiple MTEXT entities (one entity per column), which is not done by *ezdxf*, but the result is correct for advanced DXF viewers and CAD application, which do the MTEXT content distribution completely by itself. Because of the current limitations the use of this method is not recommend. This situation may improve in future releases, but the exact rendering of the content will also slow down the processing speed dramatically. (requires DXF R2000) - **Parameters** - • **content** – column content as a single string - • **width** – column width - • **gutter\_width** – distance between columns - • **height** – max. column height - • **count** – expected column count - • **dxfattribs** – additional DXF attributes - **add\_ray(start: *UVec*, unit\_vector: *UVec*, dxfattribs=None) -\> *Ray*** Add a *Ray* that begins at *start* point and continues to infinity (construction line). (requires DXF R2000) - **Parameters** - • **start** – location 3D point in *WCS* - • **unit\_vector** – 3D vector (x, y, z) - • **dxfattribs** – additional DXF attributes - **add\_xline(start: *UVec*, unit\_vector: *UVec*, dxfattribs=None) -\> *XLine*** Add an infinity *XLine* (construction line). (requires DXF R2000) - **Parameters** - • **start** – location 3D point in *WCS* - • **unit\_vector** – 3D vector (x, y, z) - • **dxfattribs** – additional DXF attributes - **add\_mline(vertices: Iterable\[*UVec*\] \| None = None, \*, close: bool = False, dxfattribs=None) -\> *MLine*** Add a *MLine* entity - **Parameters** - • **vertices** – MLINE vertices (in *WCS*) - • **close** – **True** to add a closed MLINE - • **dxfattribs** – additional DXF attributes - **add\_spline(fit\_points: Iterable\[*UVec*\] \| None = None, degree: int = 3, dxfattribs=None) -\> Spline** Add a B-spline (*Spline* entity) defined by the given *fit\_points* - the control points and knot values are created by the CAD application, therefore it is not predictable how the rendered spline will look like, because for every set of fit points exists an infinite set of B-splines. If *fit\_points* is **None**, an “empty” spline will be created, all data has to be set by the user. The SPLINE entity requires DXF R2000. AutoCAD creates a spline through fit points by a global curve interpolation and an unknown method to estimate the direction of the start- and end tangent. **SEE ALSO:** - • *Tutorial for Spline* - • *ezdxf.math.fit\_points\_to\_cad\_cv()* - **Parameters** - • **fit\_points** – iterable of fit points as **(x, y\[, z\])** in *WCS*, creates an empty *Spline* if **None** - • **degree** – degree of B-spline, max. degree supported by AutoCAD is 11 - • **dxfattribs** – additional DXF attributes - **add\_cad\_spline\_control\_frame(fit\_points: Iterable\[*UVec*\], tangents: Iterable\[*UVec*\] \| None = None, dxfattribs=None) -\> Spline** Add a *Spline* entity passing through the given fit points. This method creates the same control points as CAD applications. - **Parameters** - • **fit\_points** – iterable of fit points as (x, y\[, z\]) in *WCS* - • **tangents** – start- and end tangent, default is autodetect - • **dxfattribs** – additional DXF attributes - **add\_spline\_control\_frame(fit\_points: Iterable\[*UVec*\], degree: int = 3, method: str = 'chord', dxfattribs=None) -\> Spline** Add a *Spline* entity passing through the given *fit\_points*, the control points are calculated by a global curve interpolation without start- and end tangent constrains. The new SPLINE entity is defined by control points and not by the fit points, therefore the SPLINE looks always the same, no matter which CAD application renders the SPLINE. - • “uniform”: creates a uniform t vector, from 0 to 1 evenly spaced, see *uniform* method - • “distance”, “chord”: creates a t vector with values proportional to the fit point distances, see *chord length* method - • “centripetal”, “sqrt\_chord”: creates a t vector with values proportional to the fit point sqrt(distances), see *centripetal* method - • “arc”: creates a t vector with values proportional to the arc length between fit points. Use function *add\_cad\_spline\_control\_frame()* to create SPLINE entities from fit points similar to CAD application including start- and end tangent constraints. - **Parameters** - • **fit\_points** – iterable of fit points as (x, y\[, z\]) in *WCS* - • **degree** – degree of B-spline, max. degree supported by AutoCAD is 11 - • **method** – calculation method for parameter vector t - • **dxfattribs** – additional DXF attributes - **add\_open\_spline(control\_points: Iterable\[*UVec*\], degree: int = 3, knots: Iterable\[float\] \| None = None, dxfattribs=None) -\> Spline** Add an open uniform *Spline* defined by *control\_points*. (requires DXF R2000) Open uniform B-splines start and end at your first and last control point. - **Parameters** - • **control\_points** – iterable of 3D points in *WCS* - • **degree** – degree of B-spline, max. degree supported by AutoCAD is 11 - • **knots** – knot values as iterable of floats - • **dxfattribs** – additional DXF attributes - **add\_rational\_spline(control\_points: Iterable\[*UVec*\], weights: Sequence\[float\], degree: int = 3, knots: Iterable\[float\] \| None = None, dxfattribs=None) -\> Spline** Add an open rational uniform *Spline* defined by *control\_points*. (requires DXF R2000) *weights* has to be an iterable of floats, which defines the influence of the associated control point to the shape of the B-spline, therefore for each control point is one weight value required. Open rational uniform B-splines start and end at the first and last control point. - **Parameters** - • **control\_points** – iterable of 3D points in *WCS* - • **weights** – weight values as iterable of floats - • **degree** – degree of B-spline, max. degree supported by AutoCAD is 11 - • **knots** – knot values as iterable of floats - • **dxfattribs** – additional DXF attributes - **add\_hatch(color: int = 7, dxfattribs=None) -\> *Hatch*** Add a *Hatch* entity. (requires DXF R2000) - **Parameters** - • **color** – fill color as :ref\`ACI\`, default is 7 (black/white). - • **dxfattribs** – additional DXF attributes - **add\_helix(radius: float, pitch: float, turns: float, ccw=True, dxfattribs=None) -\> *Helix*** Add a *Helix* entity. The center of the helix is always (0, 0, 0) and the helix axis direction is the +z-axis. Transform the new HELIX by the *transform()* method to your needs. - **Parameters** - • **radius** – helix radius - • **pitch** – the height of one complete helix turn - • **turns** – count of turns - • **ccw** – creates a counter-clockwise turning (right-handed) helix if **True** - • **dxfattribs** – additional DXF attributes - **add\_mpolygon(color: int = const.BYLAYER, fill\_color: int \| None = None, dxfattribs=None) -\> *MPolygon*** Add a *MPolygon* entity. (requires DXF R2000) The MPOLYGON entity is not a core DXF entity and is not supported by every CAD application or DXF library. DXF version R2004+ is required to use a fill color different from BYLAYER. For R2000 the fill color is always BYLAYER, set any ACI value to create a filled MPOLYGON entity. - **Parameters** - • **color** – boundary color as *AutoCAD Color Index (ACI)*, default is BYLAYER. - • **fill\_color** – fill color as *AutoCAD Color Index (ACI)*, default is **None** - • **dxfattribs** – additional DXF attributes - **add\_mesh(dxfattribs=None) -\> *Mesh*** Add a *Mesh* entity. (requires DXF R2007) - **Parameters** **dxfattribs** – additional DXF attributes - **add\_image(image\_def: *ImageDef*, insert: *UVec*, size\_in\_units: tuple\[float, float\], rotation: float = 0.0, dxfattribs=None) -\> *Image*** Add an *Image* entity, requires a *ImageDef* entity, see *Tutorial for Image and ImageDef*. (requires DXF R2000) - **Parameters** - • **image\_def** – required image definition as *ImageDef* - • **insert** – insertion point as 3D point in *WCS* - • **size\_in\_units** – size as (x, y) tuple in drawing units - • **rotation** – rotation angle around the extrusion axis, default is the z-axis, in degrees - • **dxfattribs** – additional DXF attributes - **add\_wipeout(vertices: Iterable\[*UVec*\], dxfattribs=None) -\> *Wipeout*** Add a *ezdxf.entities.Wipeout* entity, the masking area is defined by WCS *vertices*. This method creates only a 2D entity in the xy-plane of the layout, the z-axis of the input vertices are ignored. - **add\_underlay(underlay\_def: *UnderlayDefinition*, insert: *UVec* = (0, 0, 0), scale=(1, 1, 1), rotation: float = 0.0, dxfattribs=None) -\> *Underlay*** Add an *Underlay* entity, requires a *UnderlayDefinition* entity, see *Tutorial for Underlay and UnderlayDefinition*. (requires DXF R2000) - **Parameters** - • **underlay\_def** – required underlay definition as *UnderlayDefinition* - • **insert** – insertion point as 3D point in *WCS* - • **scale** – underlay scaling factor as (x, y, z) tuple or as single value for uniform scaling for x, y and z - • **rotation** – rotation angle around the extrusion axis, default is the z-axis, in degrees - • **dxfattribs** – additional DXF attributes - **add\_linear\_dim(base: *UVec*, p1: *UVec*, p2: *UVec*, location: *UVec* \| None = None, text: str = '\<\>', angle: float = 0, text\_rotation: float \| None = None, dimstyle: str = 'EZDXF', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Add horizontal, vertical and rotated *Dimension* line. If an *UCS* is used for dimension line rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. See also: *Tutorial for Linear Dimensions* This method returns a *DimStyleOverride* object - to create the necessary dimension geometry, you have to call *render()* manually, this two-step process allows additional processing steps on the *Dimension* entity between creation and rendering. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. - **Parameters** - • **base** – location of dimension line, any point on the dimension line or its extension will do (in UCS) - • **p1** – measurement point 1 and start point of extension line 1 (in UCS) - • **p2** – measurement point 2 and start point of extension line 2 (in UCS) - • **location** – user defined location for the text midpoint (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZDXF” - • **angle** – angle from ucs/wcs x-axis to dimension line in degrees - • **text\_rotation** – rotation angle of the dimension text as absolute angle (x-axis=0, y-axis=90) in degrees - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_multi\_point\_linear\_dim(base: *UVec*, points: Iterable\[*UVec*\], angle: float = 0, ucs: *UCS* \| None = None, avoid\_double\_rendering: bool = True, dimstyle: str = 'EZDXF', override: dict \| None = None, dxfattribs=None, discard=False) -\> None** Add multiple linear dimensions for iterable *points*. If an *UCS* is used for dimension line rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. See also: *Tutorial for Linear Dimensions* This method sets many design decisions by itself, the necessary geometry will be generated automatically, no required nor possible *render()* call. This method is easy to use, but you get what you get. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. - **Parameters** - • **base** – location of dimension line, any point on the dimension line or its extension will do (in UCS) - • **points** – iterable of measurement points (in UCS) - • **angle** – angle from ucs/wcs x-axis to dimension line in degrees (0 = horizontal, 90 = vertical) - • **ucs** – user defined coordinate system - • **avoid\_double\_rendering** – suppresses the first extension line and the first arrow if possible for continued dimension entities - • **dimstyle** – dimension style name (DimStyle table entry), default is “EZDXF” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity - • **discard** – discard rendering result for friendly CAD applications like BricsCAD to get a native and likely better rendering result. (does not work with AutoCAD) - **add\_aligned\_dim(p1: *UVec*, p2: *UVec*, distance: float, text: str = '\<\>', dimstyle: str = 'EZDXF', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Add linear dimension aligned with measurement points *p1* and *p2*. If an *UCS* is used for dimension line rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. See also: *Tutorial for Linear Dimensions* This method returns a *DimStyleOverride* object, to create the necessary dimension geometry, you have to call **DimStyleOverride.render()** manually, this two-step process allows additional processing steps on the *Dimension* entity between creation and rendering. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. - **Parameters** - • **p1** – measurement point 1 and start point of extension line 1 (in UCS) - • **p2** – measurement point 2 and start point of extension line 2 (in UCS) - • **distance** – distance of dimension line from measurement points - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZDXF” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_radius\_dim(center: *UVec*, mpoint: *UVec* \| None = None, radius: float \| None = None, angle: float \| None = None, \*, location: *UVec* \| None = None, text: str = '\<\>', dimstyle: str = 'EZ\_RADIUS', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Add a radius *Dimension* line. The radius dimension line requires a *center* point and a point *mpoint* on the circle or as an alternative a *radius* and a dimension line *angle* in degrees. See also: *Tutorial for Radius Dimensions* If a *UCS* is used for dimension line rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. This method returns a *DimStyleOverride* object - to create the necessary dimension geometry, you have to call *render()* manually, this two-step process allows additional processing steps on the *Dimension* entity between creation and rendering. Following render types are supported: - • Default text location outside: text aligned with dimension line; dimension style: “EZ\_RADIUS” - • Default text location outside horizontal: “EZ\_RADIUS” + dimtoh=1 - • Default text location inside: text aligned with dimension line; dimension style: “EZ\_RADIUS\_INSIDE” - • Default text location inside horizontal: “EZ\_RADIUS\_INSIDE” + dimtih=1 - • User defined text location: argument *location* != **None**, text aligned with dimension line; dimension style: “EZ\_RADIUS” - • User defined text location horizontal: argument *location* != **None**, “EZ\_RADIUS” + dimtoh=1 for text outside horizontal, “EZ\_RADIUS” + dimtih=1 for text inside horizontal Placing the dimension text at a user defined *location*, overrides the *mpoint* and the *angle* argument, but requires a given *radius* argument. The *location* argument does not define the exact text location, instead it defines the dimension line starting at *center* and the measurement text midpoint projected on this dimension line going through *location*, if text is aligned to the dimension line. If text is horizontal, *location* is the kink point of the dimension line from radial to horizontal direction. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. - **Parameters** - • **center** – center point of the circle (in UCS) - • **mpoint** – measurement point on the circle, overrides *angle* and *radius* (in UCS) - • **radius** – radius in drawing units, requires argument *angle* - • **angle** – specify angle of dimension line in degrees, requires argument *radius* - • **location** – user defined dimension text location, overrides *mpoint* and *angle*, but requires *radius* (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_RADIUS” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_radius\_dim\_2p(center: *UVec*, mpoint: *UVec*, \*, text: str = '\<\>', dimstyle: str = 'EZ\_RADIUS', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut method to create a radius dimension by center point, measurement point on the circle and the measurement text at the default location defined by the associated *dimstyle*, for further information see general method *add\_radius\_dim()*. - • dimstyle “EZ\_RADIUS”: places the dimension text outside - • dimstyle “EZ\_RADIUS\_INSIDE”: places the dimension text inside - **Parameters** - • **center** – center point of the circle (in UCS) - • **mpoint** – measurement point on the circle (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_RADIUS” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_radius\_dim\_cra(center: *UVec*, radius: float, angle: float, \*, text: str = '\<\>', dimstyle: str = 'EZ\_RADIUS', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut method to create a radius dimension by (c)enter point, (r)adius and (a)ngle, the measurement text is placed at the default location defined by the associated *dimstyle*, for further information see general method *add\_radius\_dim()*. - • dimstyle “EZ\_RADIUS”: places the dimension text outside - • dimstyle “EZ\_RADIUS\_INSIDE”: places the dimension text inside - **Parameters** - • **center** – center point of the circle (in UCS) - • **radius** – radius in drawing units - • **angle** – angle of dimension line in degrees - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_RADIUS” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_diameter\_dim(center: *UVec*, mpoint: *UVec* \| None = None, radius: float \| None = None, angle: float \| None = None, \*, location: *UVec* \| None = None, text: str = '\<\>', dimstyle: str = 'EZ\_RADIUS', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Add a diameter *Dimension* line. The diameter dimension line requires a *center* point and a point *mpoint* on the circle or as an alternative a *radius* and a dimension line *angle* in degrees. If an *UCS* is used for dimension line rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. This method returns a *DimStyleOverride* object - to create the necessary dimension geometry, you have to call *render()* manually, this two-step process allows additional processing steps on the *Dimension* entity between creation and rendering. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. - **Parameters** - • **center** – specifies the center of the circle (in UCS) - • **mpoint** – specifies the measurement point on the circle (in UCS) - • **radius** – specify radius, requires argument *angle*, overrides *p1* argument - • **angle** – specify angle of dimension line in degrees, requires argument *radius*, overrides *p1* argument - • **location** – user defined location for the text midpoint (in UCS) - • **text** – **None** or **"\<\>"** the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_RADIUS” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_diameter\_dim\_2p(p1: *UVec*, p2: *UVec*, text: str = '\<\>', dimstyle: str = 'EZ\_RADIUS', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut method to create a diameter dimension by two points on the circle and the measurement text at the default location defined by the associated *dimstyle*, for further information see general method *add\_diameter\_dim()*. Center point of the virtual circle is the midpoint between *p1* and *p2*. - • dimstyle “EZ\_RADIUS”: places the dimension text outside - • dimstyle “EZ\_RADIUS\_INSIDE”: places the dimension text inside - **Parameters** - • **p1** – first point of the circle (in UCS) - • **p2** – second point on the opposite side of the center point of the circle (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_RADIUS” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_angular\_dim\_2l(base: *UVec*, line1: tuple\[*UVec*, *UVec*\], line2: tuple\[*UVec*, *UVec*\], \*, location: *UVec* \| None = None, text: str = '\<\>', text\_rotation: float \| None = None, dimstyle: str = 'EZ\_CURVED', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Add angular *Dimension* from two lines. The measurement is always done from *line1* to *line2* in counter-clockwise orientation. This does not always match the result in CAD applications! If an *UCS* is used for angular dimension rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. This method returns a *DimStyleOverride* object - to create the necessary dimension geometry, you have to call *render()* manually, this two-step process allows additional processing steps on the *Dimension* entity between creation and rendering. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. - **Parameters** - • **base** – location of dimension line, any point on the dimension line or its extension is valid (in UCS) - • **line1** – specifies start leg of the angle (start point, end point) and determines extension line 1 (in UCS) - • **line2** – specifies end leg of the angle (start point, end point) and determines extension line 2 (in UCS) - • **location** – user defined location for the text midpoint (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **text\_rotation** – rotation angle of the dimension text as absolute angle (x-axis=0, y-axis=90) in degrees - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_CURVED” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_angular\_dim\_3p(base: *UVec*, center: *UVec*, p1: *UVec*, p2: *UVec*, \*, location: *UVec* \| None = None, text: str = '\<\>', text\_rotation: float \| None = None, dimstyle: str = 'EZ\_CURVED', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Add angular *Dimension* from three points (center, p1, p2). The measurement is always done from *p1* to *p2* in counter-clockwise orientation. This does not always match the result in CAD applications! If an *UCS* is used for angular dimension rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. This method returns a *DimStyleOverride* object - to create the necessary dimension geometry, you have to call *render()* manually, this two-step process allows additional processing steps on the *Dimension* entity between creation and rendering. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. - **Parameters** - • **base** – location of dimension line, any point on the dimension line or its extension is valid (in UCS) - • **center** – specifies the vertex of the angle - • **p1** – specifies start leg of the angle (center -\> p1) and end-point of extension line 1 (in UCS) - • **p2** – specifies end leg of the angle (center -\> p2) and end-point of extension line 2 (in UCS) - • **location** – user defined location for the text midpoint (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **text\_rotation** – rotation angle of the dimension text as absolute angle (x-axis=0, y-axis=90) in degrees - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_CURVED” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_angular\_dim\_cra(center: *UVec*, radius: float, start\_angle: float, end\_angle: float, distance: float, \*, location: *UVec* \| None = None, text: str = '\<\>', text\_rotation: float \| None = None, dimstyle: str = 'EZ\_CURVED', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut method to create an angular dimension by (c)enter point, (r)adius and start- and end (a)ngles, the measurement text is placed at the default location defined by the associated *dimstyle*. The measurement is always done from *start\_angle* to *end\_angle* in counter-clockwise orientation. This does not always match the result in CAD applications! For further information see the more generic factory method *add\_angular\_dim\_3p()*. - **Parameters** - • **center** – center point of the angle (in UCS) - • **radius** – the distance from *center* to the start of the extension lines in drawing units - • **start\_angle** – start angle in degrees (in UCS) - • **end\_angle** – end angle in degrees (in UCS) - • **distance** – distance from start of the extension lines to the dimension line in drawing units - • **location** – user defined location for the text midpoint (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **text\_rotation** – rotation angle of the dimension text as absolute angle (x-axis=0, y-axis=90) in degrees - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_CURVED” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_angular\_dim\_arc(arc: *ConstructionArc*, distance: float, \*, location: *UVec* \| None = None, text: str = '\<\>', text\_rotation: float \| None = None, dimstyle: str = 'EZ\_CURVED', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut method to create an angular dimension from a *ConstructionArc*. This construction tool can be created from ARC entities and the tool itself provides various construction class methods. The measurement text is placed at the default location defined by the associated *dimstyle*. The measurement is always done from *start\_angle* to *end\_angle* of the arc in counter-clockwise orientation. This does not always match the result in CAD applications! For further information see the more generic factory method *add\_angular\_dim\_3p()*. - **Parameters** - • **arc** – *ConstructionArc* - • **distance** – distance from start of the extension lines to the dimension line in drawing units - • **location** – user defined location for the text midpoint (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **text\_rotation** – rotation angle of the dimension text as absolute angle (x-axis=0, y-axis=90) in degrees - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_CURVED” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_arc\_dim\_3p(base: *UVec*, center: *UVec*, p1: *UVec*, p2: *UVec*, \*, location: *UVec* \| None = None, text: str = '\<\>', text\_rotation: float \| None = None, dimstyle: str = 'EZ\_CURVED', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Add *ArcDimension* from three points (center, p1, p2). Point *p1* defines the radius and the start-angle of the arc, point *p2* only defines the end-angle of the arc. If an *UCS* is used for arc dimension rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. This method returns a *DimStyleOverride* object - to create the necessary dimension geometry, you have to call *render()* manually, this two-step process allows additional processing steps on the *ArcDimension* entity between creation and rendering. **NOTE:** *Ezdxf* does not render the arc dimension like CAD applications and does not consider all DIMSTYLE variables, so the rendering results are **very** different from CAD applications. - **Parameters** - • **base** – location of dimension line, any point on the dimension line or its extension is valid (in UCS) - • **center** – specifies the vertex of the angle - • **p1** – specifies the radius (center -\> p1) and the star angle of the arc, this is also the start point for the 1st extension line (in UCS) - • **p2** – specifies the end angle of the arc. The start 2nd extension line is defined by this angle and the radius defined by p1 (in UCS) - • **location** – user defined location for the text midpoint (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **text\_rotation** – rotation angle of the dimension text as absolute angle (x-axis=0, y-axis=90) in degrees - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_CURVED” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_arc\_dim\_cra(center: *UVec*, radius: float, start\_angle: float, end\_angle: float, distance: float, \*, location: *UVec* \| None = None, text: str = '\<\>', text\_rotation: float \| None = None, dimstyle: str = 'EZ\_CURVED', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut method to create an arc dimension by (c)enter point, (r)adius and start- and end (a)ngles, the measurement text is placed at the default location defined by the associated *dimstyle*. **NOTE:** *Ezdxf* does not render the arc dimension like CAD applications and does not consider all DIMSTYLE variables, so the rendering results are **very** different from CAD applications. - **Parameters** - • **center** – center point of the angle (in UCS) - • **radius** – the distance from *center* to the start of the extension lines in drawing units - • **start\_angle** – start-angle in degrees (in UCS) - • **end\_angle** – end-angle in degrees (in UCS) - • **distance** – distance from start of the extension lines to the dimension line in drawing units - • **location** – user defined location for text midpoint (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **text\_rotation** – rotation angle of the dimension text as absolute angle (x-axis=0, y-axis=90) in degrees - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_CURVED” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_arc\_dim\_arc(arc: *ConstructionArc*, distance: float, \*, location: *UVec* \| None = None, text: str = '\<\>', text\_rotation: float \| None = None, dimstyle: str = 'EZ\_CURVED', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut method to create an arc dimension from a *ConstructionArc*. This construction tool can be created from ARC entities and the tool itself provides various construction class methods. The measurement text is placed at the default location defined by the associated *dimstyle*. **NOTE:** *Ezdxf* does not render the arc dimension like CAD applications and does not consider all DIMSTYLE variables, so the rendering results are **very** different from CAD applications. - **Parameters** - • **arc** – *ConstructionArc* - • **distance** – distance from start of the extension lines to the dimension line in drawing units - • **location** – user defined location for the text midpoint (in UCS) - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **text\_rotation** – rotation angle of the dimension text as absolute angle (x-axis=0, y-axis=90) in degrees - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZ\_CURVED” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_ordinate\_dim(feature\_location: *UVec*, offset: *UVec*, dtype: int, \*, origin: *UVec* = NULLVEC, rotation: float = 0.0, text: str = '\<\>', dimstyle: str = 'EZDXF', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Add an ordinate type *Dimension* line. The feature location is defined in the global coordinate system, which is set as render UCS, which is the *WCS* by default. If an *UCS* is used for dimension line rendering, all point definitions in UCS coordinates, translation into *WCS* and *OCS* is done by the rendering function. Extrusion vector is defined by UCS or (0, 0, 1) by default. This method returns a *DimStyleOverride* object - to create the necessary dimension geometry, you have to call *render()* manually, this two-step process allows additional processing steps on the *Dimension* entity between creation and rendering. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. - **Parameters** - • **feature\_location** – feature location in the global coordinate system (UCS) - • **offset** – offset vector of leader end point from the feature location in the local coordinate system - • **dtype** – 1 = x-type, 0 = y-type - • **origin** – specifies the origin (0, 0) of the local coordinate system in UCS - • **rotation** – rotation angle of the local coordinate system in degrees - • **text** – **None** or “\<\>” the measurement is drawn as text, “ “ (a single space) suppresses the dimension text, everything else *text* is drawn as dimension text - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZDXF” - • **override** – *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes for the DIMENSION entity Returns: *DimStyleOverride* - **add\_ordinate\_x\_dim(feature\_location: *UVec*, offset: *UVec*, \*, origin: *UVec* = NULLVEC, rotation: float = 0.0, text: str = '\<\>', dimstyle: str = 'EZDXF', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut to add an x-type feature ordinate DIMENSION, for more information see *add\_ordinate\_dim()*. - **add\_ordinate\_y\_dim(feature\_location: *UVec*, offset: *UVec*, \*, origin: *UVec* = NULLVEC, rotation: float = 0.0, text: str = '\<\>', dimstyle: str = 'EZDXF', override: dict \| None = None, dxfattribs=None) -\> DimStyleOverride** Shortcut to add a y-type feature ordinate DIMENSION, for more information see *add\_ordinate\_dim()*. - **add\_leader(vertices: Iterable\[*UVec*\], dimstyle: str = 'EZDXF', override: dict \| None = None, dxfattribs=None) -\> *Leader*** The *Leader* entity represents an arrow, made up of one or more vertices (or spline fit points) and an arrowhead. The label or other content to which the *Leader* is attached is stored as a separate entity, and is not part of the *Leader* itself. (requires DXF R2000) *Leader* shares its styling infrastructure with *Dimension*. By default a *Leader* without any annotation is created. For creating more fancy leaders and annotations see documentation provided by Autodesk or *Demystifying DXF: LEADER and MULTILEADER* *implementation notes* . - **Parameters** - • **vertices** – leader vertices (in *WCS*) - • **dimstyle** – dimension style name (*DimStyle* table entry), default is “EZDXF” - • **override** – override *DimStyleOverride* attributes - • **dxfattribs** – additional DXF attributes - **add\_multileader\_mtext(style: str = 'Standard', dxfattribs=None) -\> *MultiLeaderMTextBuilder*** Add a *MultiLeader* entity but returns a *MultiLeaderMTextBuilder*. - **add\_multileader\_block(style: str = 'Standard', dxfattribs=None) -\> *MultiLeaderBlockBuilder*** Add a *MultiLeader* entity but returns a *MultiLeaderBlockBuilder*. - **add\_body(dxfattribs=None) -\> Body** Add a *Body* entity. (requires DXF R2000 or later) The ACIS data has to be set as *SAT* or *SAB*. - **add\_region(dxfattribs=None) -\> *Region*** Add a *Region* entity. (requires DXF R2000 or later) The ACIS data has to be set as *SAT* or *SAB*. - **add\_3dsolid(dxfattribs=None) -\> *Solid3d*** Add a 3DSOLID entity (*Solid3d*). (requires DXF R2000 or later) The ACIS data has to be set as *SAT* or *SAB*. - **add\_surface(dxfattribs=None) -\> Surface** Add a *Surface* entity. (requires DXF R2007 or later) The ACIS data has to be set as *SAT* or *SAB*. - **add\_extruded\_surface(dxfattribs=None) -\> *ExtrudedSurface*** Add a *ExtrudedSurface* entity. (requires DXF R2007 or later) The ACIS data has to be set as *SAT* or *SAB*. - **add\_lofted\_surface(dxfattribs=None) -\> *LoftedSurface*** Add a *LoftedSurface* entity. (requires DXF R2007 or later) The ACIS data has to be set as *SAT* or *SAB*. - **add\_revolved\_surface(dxfattribs=None) -\> *RevolvedSurface*** Add a *RevolvedSurface* entity. (requires DXF R2007 or later) The ACIS data has to be set as *SAT* or *SAB*. - **add\_swept\_surface(dxfattribs=None) -\> *SweptSurface*** Add a *SweptSurface* entity. (requires DXF R2007 or later) The ACIS data has to be set as *SAT* or *SAB*. ### Layout - **class ezdxf.layouts.Layout** *Layout* is a subclass of *BaseLayout* and common base class of *Modelspace* and *Paperspace*. - **name** Layout name as shown in tabs of *CAD* applications. - **dxf** Returns the DXF name space attribute of the associated *DXFLayout* object. This enables direct access to the underlying LAYOUT entity, e.g. **Layout.dxf.layout\_flags** - **\_\_contains\_\_(entity: *DXFGraphic* \| str) -\> bool** Returns **True** if *entity* is stored in this layout. - **Parameters** **entity** – **DXFGraphic** object or handle as hex string - **reset\_extents(extmin=(+1e20, +1e20, +1e20), extmax=(-1e20, -1e20, -1e20)) -\> None** Reset *extents* to given values or the AutoCAD default values. “Drawing extents are the bounds of the area occupied by objects.” (Quote Autodesk Knowledge Network) - **Parameters** - • **extmin** – minimum extents or (+1e20, +1e20, +1e20) as default value - • **extmax** – maximum extents or (-1e20, -1e20, -1e20) as default value - **reset\_limits(limmin=None, limmax=None) -\> None** Reset *limits* to given values or the AutoCAD default values. “Sets an invisible rectangular boundary in the drawing area that can limit the grid display and limit clicking or entering point locations.” (Quote Autodesk Knowledge Network) The *Paperspace* class has an additional method *reset\_paper\_limits()* to deduce the default limits from the paper size settings. - **Parameters** - • **limmin** – minimum limits or (0, 0) as default - • **limmax** – maximum limits or (paper width, paper height) as default value - **set\_plot\_type(value: int = 5) -\> None** | | | | --- | --- | | 0 | last screen display | | 1 | drawing extents | | 2 | drawing limits | | 3 | view specific (defined by **Layout.dxf.plot\_view\_name**) | | 4 | window specific (defined by **Layout.set\_plot\_window\_limits()**) | | 5 | layout information (default) | - **Parameters** **value** – plot type - **Raises** *DXFValueError* – for *value* out of range - **set\_plot\_style(name: str = 'ezdxf.ctb', show: bool = False) -\> None** Set plot style file of type *.ctb*. - **Parameters** - • **name** – plot style filename - • **show** – show plot style effect in preview? (AutoCAD specific attribute) - **set\_plot\_window(lower\_left: tuple\[float, float\] = (0, 0), upper\_right: tuple\[float, float\] = (0, 0)) -\> None** Set plot window size in (scaled) paper space units. - **Parameters** - • **lower\_left** – lower left corner as 2D point - • **upper\_right** – upper right corner as 2D point - **plot\_viewport\_borders(state: bool = True) -\> None** - **show\_plot\_styles(state: bool = True) -\> None** - **plot\_centered(state: bool = True) -\> None** - **plot\_hidden(state: bool = True) -\> None** - **use\_standard\_scale(state: bool = True) -\> None** - **use\_plot\_styles(state: bool = True) -\> None** - **scale\_lineweights(state: bool = True) -\> None** - **print\_lineweights(state: bool = True) -\> None** - **draw\_viewports\_first(state: bool = True) -\> None** - **model\_type(state: bool = True) -\> None** - **update\_paper(state: bool = True) -\> None** - **zoom\_to\_paper\_on\_update(state: bool = True) -\> None** - **plot\_flags\_initializing(state: bool = True) -\> None** - **prev\_plot\_init(state: bool = True) -\> None** - **set\_plot\_flags(flag, state: bool = True) -\> None** ### Modelspace - **class ezdxf.layouts.Modelspace** *Modelspace* is a subclass of *Layout*. The modelspace contains the “real” world representation of the drawing subjects in real world units. - **name** Name of modelspace is fixed as “Model”. - **new\_geodata(dxfattribs=None) -\> *GeoData*** Creates a new **GeoData** entity and replaces existing ones. The GEODATA entity resides in the OBJECTS section and not in the modelspace, it is linked to the modelspace by an **ExtensionDict** located in BLOCK\_RECORD of the modelspace. The GEODATA entity requires DXF R2010. The DXF reference does not document if other layouts than the modelspace supports geo referencing, so I assume getting/setting geo data may only make sense for the modelspace. - **Parameters** **dxfattribs** – DXF attributes for *GeoData* entity - **get\_geodata() -\> *GeoData* \| None** Returns the *GeoData* entity associated to the modelspace or **None**. ### Paperspace - **class ezdxf.layouts.Paperspace** *Paperspace* is a subclass of *Layout*. Paperspace layouts are used to create different drawing sheets of the modelspace subjects for printing or PDF export. - **name** Layout name as shown in tabs of *CAD* applications. - **page\_setup(size=(297, 210), margins=(10, 15, 10, 15), units='mm', offset=(0, 0), rotation=0, scale=16, name='ezdxf', device='DWG to PDF.pc3')** Setup plot settings and paper size and reset viewports. All parameters in given *units* (mm or inch). Reset paper limits, extents and viewports. - **Parameters** - • **size** – paper size as (width, height) tuple - • **margins** – (top, right, bottom, left) hint: clockwise - • **units** – “mm” or “inch” - • **offset** – plot origin offset is 2D point - • **rotation** – see table Rotation - • **scale** – integer in range \[0, 32\] defines a standard scale type or as tuple(numerator, denominator) e.g. (1, 50) for scale 1:50 - • **name** – paper name prefix “{name}\_({width}\_x\_{height}\_{unit})” - • **device** – device .pc3 configuration file or system printer name | | | | --- | --- | | int | Rotation | | 0 | no rotation | | 1 | 90 degrees counter-clockwise | | 2 | upside-down | | 3 | 90 degrees clockwise | - **viewports() -\> list\[*Viewport*\]** Get all VIEWPORT entities defined in this paperspace layout. - **main\_viewport() -\> *Viewport* \| None** Returns the main viewport of this paper space layout, or **None** if no main viewport exist. - **add\_viewport(center: *UVec*, size: tuple\[float, float\], view\_center\_point: *UVec*, view\_height: float, status: int = 2, dxfattribs=None) -\> *Viewport*** Add a new *Viewport* entity. Viewport **status**: - • \-1 is on, but is fully off-screen, or is one of the viewports that is not active because the $MAXACTVP count is currently being exceeded. - • 0 is off - • any value\>0 is on and active. The value indicates the order of stacking for the viewports, where 1 is the “active viewport”, 2 is the next, … - **reset\_viewports() -\> None** Delete all existing viewports, and create a new main viewport. - **reset\_main\_viewport(center: *UVec* = None, size: *UVec* = None) -\> *Viewport*** Reset the main viewport of this paper space layout to the given values, or reset them to the default values, deduced from the paper settings. Creates a new main viewport if none exist. Ezdxf does not create a main viewport by default, because CAD applications don’t require one. - **Parameters** - • **center** – center of the viewport in paper space units - • **size** – viewport size as (width, height) tuple in paper space units - **reset\_paper\_limits() -\> None** Set paper limits to default values, all values in paperspace units but without plot scale (?). - **get\_paper\_limits() -\> tuple\[*Vec2*, *Vec2*\]** Returns paper limits in plot paper units, relative to the plot origin. plot origin = lower left corner of printable area + plot origin offset - **Returns** tuple (Vec2(x1, y1), Vec2(x2, y2)), lower left corner is (x1, y1), upper right corner is (x2, y2). ### BlockLayout - **class ezdxf.layouts.BlockLayout** *BlockLayout* is a subclass of *BaseLayout*. Block layouts are reusable sets of graphical entities, which can be referenced by multiple *Insert* entities. Each reference can be placed, scaled and rotated individually and can have it’s own set of DXF *Attrib* entities attached. - **property name: str** Get/set the BLOCK name - **property block: Block \| None** the associated *Block* entity. - **property endblk: EndBlk \| None** the associated *EndBlk* entity. - **property dxf** DXF name space of associated *BlockRecord* table entry. - **property can\_explode: bool** Set property to **True** to allow exploding block references of this block. - **property scale\_uniformly: bool** Set property to **True** to allow block references of this block only scale uniformly. - **property base\_point: *Vec3*** Get/Set the base point of the block. - **\_\_contains\_\_(entity) -\> bool** Returns **True** if block contains *entity*. - **Parameters** **entity** – **DXFGraphic** object or handle as hex string - **attdefs() -\> Iterable\[AttDef\]** Returns iterable of all **Attdef** entities. - **has\_attdef(tag: str) -\> bool** Returns **True** if an **Attdef** for *tag* exist. - **get\_attdef(tag: str) -\> AttDef \| None** Returns attached **Attdef** entity by *tag* name. - **get\_attdef\_text(tag: str, default: str = '') -\> str** Returns text content for **Attdef** *tag* as string or returns *default* if no **Attdef** for *tag* exist. - **Parameters** - • **tag** – name of tag - • **default** – default value if *tag* not exist ### Groups A group is just a bunch of DXF entities tied together. All entities of a group has to be in the same layout (modelspace or any paperspace layout but not block). Groups can be named or unnamed, but in reality an unnamed groups has just a special name like “\*Annnn”. The name of a group has to be unique in the drawing. Groups are organized in the group table, which is stored as attribute *groups* in the *Drawing* object. **IMPORTANT:** Group entities have to reside in the modelspace or an paperspace layout but not in a block definition! ### DXFGroup - **class ezdxf.entities.dxfgroups.DXFGroup** The group name is not stored in the GROUP entity, it is stored in the *GroupCollection* object. - **dxf.description** group description (string) - **dxf.unnamed** 1 for unnamed, 0 for named group (int) - **dxf.selectable** 1 for selectable, 0 for not selectable group (int) - **\_\_iter\_\_() -\> Iterator\[DXFEntity\]** Iterate over all DXF entities in *DXFGroup* as instances of **DXFGraphic** or inherited (LINE, CIRCLE, …). - **\_\_len\_\_() -\> int** Returns the count of DXF entities in *DXFGroup*. - **\_\_getitem\_\_(item)** Returns entities by standard Python indexing and slicing. - **\_\_contains\_\_(item: str \| DXFEntity) -\> bool** Returns **True** if item is in *DXFGroup*. *item* has to be a handle string or an object of type **DXFEntity** or inherited. - **handles() -\> Iterable\[str\]** Iterable of handles of all DXF entities in *DXFGroup*. - **edit\_data() -\> list\[DXFEntity\]** Context manager which yields all the group entities as standard Python list: ``` with group.edit_data() as data: # add new entities to a group data.append(modelspace.add_line((0, 0), (3, 0))) # remove last entity from a group data.pop() ``` - **set\_data(entities: Iterable\[DXFEntity\]) -\> None** Set *entities* as new group content, entities should be an iterable of **DXFGraphic** (LINE, CIRCLE, …). - **Raises** *DXFValueError* – not all entities are located on the same layout (modelspace\ or any paperspace layout but not block) - **extend(entities: Iterable\[DXFEntity\]) -\> None** Add *entities* to *DXFGroup*, entities should be an iterable of **DXFGraphic** (LINE, CIRCLE, …). - **Raises** *DXFValueError* – not all entities are located on the same layout (modelspace\ or any paperspace layout but not block) - **clear() -\> None** Remove all entities from *DXFGroup*, does not delete any drawing entities referenced by this group. - **audit(auditor: Auditor) -\> None** Remove invalid entities from *DXFGroup*. Invalid entities are: - • deleted entities - • all entities which do not reside in model- or paper space - • all entities if they do not reside in the same layout ### GroupCollection Each *Drawing* has one group table, which is accessible by the attribute *groups*. - **class ezdxf.entities.dxfgroups.GroupCollection** Manages all *DXFGroup* objects of a *Drawing*. - **\_\_len\_\_()** Returns the count of DXF groups. - **\_\_iter\_\_()** Iterate over all existing groups as (*name*, *group*) tuples. *name* is the name of the group as string and *group* is an *DXFGroup* object. - **\_\_contains\_\_()** Returns **True** if a group *name* exist. - **get(name: str) -\> *DXFGroup*** Returns the group *name*. Raises **DXFKeyError** if group *name* does not exist. - **groups() -\> Iterator\[*DXFGroup*\]** Iterable of all existing groups. - **new(name: str \| None = None, description: str = '', selectable: bool = True) -\> *DXFGroup*** Creates a new group. If *name* is **None** an unnamed group is created, which has an automatically generated name like “\*Annnn”. Group names are case-insensitive. - **Parameters** - • **name** – group name as string - • **description** – group description as string - • **selectable** – group is selectable if **True** - **delete(group: *DXFGroup* \| str) -\> None** Delete *group*, *group* can be an object of type *DXFGroup* or a group name as string. - **clear()** Delete all groups. - **audit(auditor: Auditor) -\> None** Removes empty groups and invalid handles from all groups. ### DXF Entities All DXF entities can only reside in the *BaseLayout* and inherited classes like *Modelspace*, *Paperspace* and *BlockLayout*. **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! ### DXF Entity Base Class Common base class for all DXF entities and objects. **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.DXFEntity** - **dxf** The DXF attributes namespace: ``` # set attribute value entity.dxf.layer = 'MyLayer' # get attribute value linetype = entity.dxf.linetype # delete attribute del entity.dxf.linetype ``` - **dxf.handle** DXF *handle* is a unique identifier as plain hex string like **F000**. (feature for experts) - **dxf.owner** Handle to *owner* as plain hex string like **F000**. (feature for experts) - **doc** Get the associated *Drawing* instance. - **property is\_alive: bool** Is **False** if entity has been deleted. - **property is\_virtual: bool** Is **True** if entity is a virtual entity. - **property is\_bound: bool** Is **True** if entity is bound to DXF document. - **property is\_copy: bool** Is **True** if the entity is a copy. - **property uuid: UUID** Returns a UUID, which allows to distinguish even virtual entities without a handle. Dynamic attribute: this UUID will be created at the first request. - **property source\_of\_copy: DXFEntity \| None** The immediate source entity if this entity is a copy else **None**. Never references a destroyed entity. - **property origin\_of\_copy: DXFEntity \| None** The origin source entity if this entity is a copy else **None**. References the first non-virtual source entity and never references a destroyed entity. - **property has\_source\_block\_reference: bool** Is **True** if this virtual entity was created by a block reference. - **property source\_block\_reference: *Insert* \| None** The source block reference (INSERT) which created this virtual entity. The property is **None** if this entity was not created by a block reference. - **dxftype() -\> str** Get DXF type as string, like **LINE** for the line entity. - **\_\_str\_\_() -\> str** Returns a simple string representation. - **\_\_repr\_\_() -\> str** Returns a simple string representation including the class. - **has\_dxf\_attrib(key: str) -\> bool** Returns **True** if DXF attribute *key* really exist. Raises **DXFAttributeError** if *key* is not an supported DXF attribute. - **is\_supported\_dxf\_attrib(key: str) -\> bool** Returns **True** if DXF attrib *key* is supported by this entity. Does not grant that attribute *key* really exist. - **get\_dxf\_attrib(key: str, default: Any = None) -\> Any** Get DXF attribute *key*, returns *default* if key doesn’t exist, or raise **DXFValueError** if *default* is **DXFValueError** and no DXF default value is defined: ``` layer = entity.get_dxf_attrib("layer") # same as layer = entity.dxf.layer ``` Raises **DXFAttributeError** if *key* is not an supported DXF attribute. - **set\_dxf\_attrib(key: str, value: Any) -\> None** Set new *value* for DXF attribute *key*: ``` entity.set_dxf_attrib("layer", "MyLayer") # same as entity.dxf.layer = "MyLayer" ``` Raises **DXFAttributeError** if *key* is not an supported DXF attribute. - **del\_dxf\_attrib(key: str) -\> None** Delete DXF attribute *key*, does not raise an error if attribute is supported but not present. Raises **DXFAttributeError** if *key* is not an supported DXF attribute. - **dxfattribs(drop: set\[str\] \| None = None) -\> dict** Returns a **dict** with all existing DXF attributes and their values and exclude all DXF attributes listed in set *drop*. - **update\_dxf\_attribs(dxfattribs: dict) -\> None** Set DXF attributes by a **dict** like **{'layer': 'test',** **'color': 4}**. - **set\_flag\_state(flag: int, state: bool = True, name: str = 'flags') -\> None** Set binary coded *flag* of DXF attribute *name* to 1 (on) if *state* is **True**, set *flag* to 0 (off) if *state* is **False**. - **get\_flag\_state(flag: int, name: str = 'flags') -\> bool** Returns **True** if any *flag* of DXF attribute is 1 (on), else **False**. Always check only one flag state at the time. - **has\_extension\_dict** Returns **True** if entity has an attached *ExtensionDict* instance. - **get\_extension\_dict() -\> *ExtensionDict*** Returns the existing *ExtensionDict* instance. - **Raises** **AttributeError** – extension dict does not exist - **new\_extension\_dict() -\> *ExtensionDict*** Create a new *ExtensionDict* instance. - **discard\_extension\_dict() -\> None** Delete *ExtensionDict* instance. - **discard\_empty\_extension\_dict() -\> None** Delete *ExtensionDict* instance when empty. - **has\_app\_data(appid: str) -\> bool** Returns **True** if application defined data for *appid* exist. - **get\_app\_data(appid: str) -\> *Tags*** Returns application defined data for *appid*. - **Parameters** **appid** – application name as defined in the APPID table. - **Raises** *DXFValueError* – no data for *appid* found - **set\_app\_data(appid: str, tags: Iterable) -\> None** Set application defined data for *appid* as iterable of tags. - **Parameters** - • **appid** – application name as defined in the APPID table. - • **tags** – iterable of (code, value) tuples or *DXFTag* - **discard\_app\_data(appid: str)** Discard application defined data for *appid*. Does not raise an exception if no data for *appid* exist. - **has\_xdata(appid: str) -\> bool** Returns **True** if extended data for *appid* exist. - **get\_xdata(appid: str) -\> *Tags*** Returns extended data for *appid*. - **Parameters** **appid** – application name as defined in the APPID table. - **Raises** *DXFValueError* – no extended data for *appid* found - **set\_xdata(appid: str, tags: Iterable) -\> None** Set extended data for *appid* as iterable of tags. - **Parameters** - • **appid** – application name as defined in the APPID table. - • **tags** – iterable of (code, value) tuples or *DXFTag* - **discard\_xdata(appid: str) -\> None** Discard extended data for *appid*. Does not raise an exception if no extended data for *appid* exist. - **has\_xdata\_list(appid: str, name: str) -\> bool** Returns **True** if a tag list *name* for extended data *appid* exist. - **get\_xdata\_list(appid: str, name: str) -\> *Tags*** Returns tag list *name* for extended data *appid*. - **Parameters** - • **appid** – application name as defined in the APPID table. - • **name** – extended data list name - **Raises** *DXFValueError* – no extended data for *appid* found or no data list *name* not found - **set\_xdata\_list(appid: str, name: str, tags: Iterable) -\> None** Set tag list *name* for extended data *appid* as iterable of tags. - **Parameters** - • **appid** – application name as defined in the APPID table. - • **name** – extended data list name - • **tags** – iterable of (code, value) tuples or *DXFTag* - **discard\_xdata\_list(appid: str, name: str) -\> None** Discard tag list *name* for extended data *appid*. Does not raise an exception if no extended data for *appid* or no tag list *name* exist. - **replace\_xdata\_list(appid: str, name: str, tags: Iterable) -\> None** Replaces tag list *name* for existing extended data *appid* by *tags*. Appends new list if tag list *name* do not exist, but raises **DXFValueError** if extended data *appid* do not exist. - **Parameters** - • **appid** – application name as defined in the APPID table. - • **name** – extended data list name - • **tags** – iterable of (code, value) tuples or *DXFTag* - **Raises** *DXFValueError* – no extended data for *appid* found - **has\_reactors() -\> bool** Returns **True** if entity has reactors. - **get\_reactors() -\> list\[str\]** Returns associated reactors as list of handles. - **set\_reactors(handles: Iterable\[str\]) -\> None** Set reactors as list of handles. - **append\_reactor\_handle(handle: str) -\> None** Append *handle* to reactors. - **discard\_reactor\_handle(handle: str) -\> None** Discard *handle* from reactors. Does not raise an exception if *handle* does not exist. ### DXF Graphic Entity Base Class Common base class for all graphical DXF entities. All graphical entities reside in an entity space like *Modelspace*, any *Paperspace* or *BlockLayout*. **SEE ALSO:** - • *ezdxf.gfxattribs* module, helper tools to set graphical attributes of DXF entities - • *ezdxf.colors* module - • *Tutorial for Common Graphical Attributes* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFEntity* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.DXFGraphic** - **rgb** Get/set/delete DXF attribute *dxf.true\_color* as (r, g, b) tuple, returns **None** if attribute *dxf.true\_color* is not set. ``` entity.rgb = (30, 40, 50) # set as tuple[int, int, int] or color.RGB r, g, b = entity.rgb # returns tuple[int, int, int] or None del entity.rgb # discard true color value, no exception if not exist ``` This is the recommend method to get/set/delete RGB values, when ever possible do not use the DXF low level attribute *dxf.true\_color*. - **transparency** Get/set the transparency value as float. The transparency value is in the range from 0 to 1, where 0 means the entity is opaque and 1 means the entity is 100% transparent (invisible). This is the recommend method to get/set the transparency value, when ever possible do not use the DXF low level attribute *DXFGraphic.dxf.transparency*. This attribute requires DXF R2004 or later, returns 0 for older DXF versions and raises **DXFAttributeError** for setting transparency in older DXF versions. - **property is\_transparency\_by\_layer: bool** Returns **True** if entity inherits transparency from layer. - **property is\_transparency\_by\_block: bool** Returns **True** if entity inherits transparency from block. - **ocs() -\> *OCS*** Returns object coordinate system (*OCS*) for 2D entities like *Text* or *Circle*, returns a pass-through OCS for entities without OCS support. - **get\_layout() -\> *BaseLayout* \| None** Returns the owner layout or returns **None** if entity is not assigned to any layout. - **unlink\_from\_layout() -\> None** Unlink entity from associated layout. Does nothing if entity is already unlinked. It is more efficient to call the *unlink\_entity()* method of the associated layout, especially if you have to unlink more than one entity. - **copy\_to\_layout(layout: *BaseLayout*) -\> Self** Copy entity to another *layout*, returns new created entity as *DXFEntity* object. Copying between different DXF drawings is not supported. - **Parameters** **layout** – any layout (model space, paper space, block) - **Raises** *DXFStructureError* – for copying between different DXF drawings - **move\_to\_layout(layout: *BaseLayout*, source: *BaseLayout* \| None = None) -\> None** Move entity from model space or a paper space layout to another layout. For block layout as source, the block layout has to be specified. Moving between different DXF drawings is not supported. - **Parameters** - • **layout** – any layout (model space, paper space, block) - • **source** – provide source layout, faster for DXF R12, if entity is in a block layout - **Raises** *DXFStructureError* – for moving between different DXF drawings - **graphic\_properties() -\> dict** Returns the important common properties layer, color, linetype, lineweight, ltscale, true\_color and color\_name as *dxfattribs* dict. - **has\_hyperlink() -\> bool** Returns **True** if entity has an attached hyperlink. - **get\_hyperlink() -\> tuple\[str, str, str\]** Returns hyperlink, description and location. - **set\_hyperlink(link: str, description: str \| None = None, location: str \| None = None)** Set hyperlink of an entity. - **transform(m: *Matrix44*) -\> Self** Inplace transformation interface, returns *self* (floating interface). - **Parameters** **m** – 4x4 transformation matrix (*ezdxf.math.Matrix44*) - **translate(dx: float, dy: float, dz: float) -\> Self** Translate entity inplace about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis, returns *self* (floating interface). Basic implementation uses the *transform()* interface, subclasses may have faster implementations. - **scale(sx: float, sy: float, sz: float) -\> Self** Scale entity inplace about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis, returns *self* (floating interface). - **scale\_uniform(s: float) -\> Self** Scale entity inplace uniform about *s* in x-axis, y-axis and z-axis, returns *self* (floating interface). - **rotate\_x(angle: float) -\> Self** Rotate entity inplace about x-axis, returns *self* (floating interface). - **Parameters** **angle** – rotation angle in radians - **rotate\_y(angle: float) -\> Self** Rotate entity inplace about y-axis, returns *self* (floating interface). - **Parameters** **angle** – rotation angle in radians - **rotate\_z(angle: float) -\> Self** Rotate entity inplace about z-axis, returns *self* (floating interface). - **Parameters** **angle** – rotation angle in radians - **rotate\_axis(axis: *UVec*, angle: float) -\> Self** Rotate entity inplace about vector *axis*, returns *self* (floating interface). - **Parameters** - • **axis** – rotation axis as tuple or **Vec3** - • **angle** – rotation angle in radians ### Common graphical DXF attributes - **DXFGraphic.dxf.layer** Layer name as string; default = “0” - **DXFGraphic.dxf.linetype** Linetype as string, special names “BYLAYER”, “BYBLOCK”; default value is “BYLAYER” - **DXFGraphic.dxf.color** *AutoCAD Color Index (ACI)*, default value is 256 Constants defined in *ezdxf.lldxf.const* or use the *ezdxf.colors* module | | | | --- | --- | | 0 | BYBLOCK | | 256 | BYLAYER | | 257 | BYOBJECT | - **DXFGraphic.dxf.lineweight** Line weight in mm times 100 (e.g. 0.13mm = 13). There are fixed valid lineweights which are accepted by AutoCAD, other values prevents AutoCAD from loading the DXF document, BricsCAD isn’t that picky. (requires DXF R2000) Constants defined in *ezdxf.lldxf.const* | | | | --- | --- | | -1 | LINEWEIGHT\_BYLAYER | | -2 | LINEWEIGHT\_BYBLOCK | | -3 | LINEWEIGHT\_DEFAULT | Valid DXF lineweights stored in **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 - **DXFGraphic.dxf.ltscale** Line type scale as float; default value is 1.0; (requires DXF R2000) - **DXFGraphic.dxf.invisible** 1 for invisible, 0 for visible; default value is 0; (requires DXF R2000) - **DXFGraphic.dxf.paperspace** 0 for entity resides in modelspace or a block, 1 for paperspace, this attribute is set automatically by adding an entity to a layout (feature for experts); default value is 0 - **DXFGraphic.dxf.extrusion** Extrusion direction as 3D vector; default value is (0, 0, 1) - **DXFGraphic.dxf.thickness** Entity thickness as float; default value is 0.0; (requires DXF R2000) - **DXFGraphic.dxf.true\_color** True color value as int 0x00RRGGBB, use *DXFGraphic.rgb* to get/set true color values as (r, g, b) tuples. (requires DXF R2004) - **DXFGraphic.dxf.color\_name** Color name as string. (requires DXF R2004) - **DXFGraphic.dxf.transparency** Transparency value as int, 0x020000TT, 0x00 = 100% transparent / 0xFF = opaque, special value 0x01000000 means transparency by block. An unset transparency value means transparency by layer. Use *DXFGraphic.transparency* to get/set transparency as float value, and the properties *DXFGraphic.is\_transparency\_by\_block* and *DXFGraphic.is\_transparency\_by\_layer* to check special cases. (requires DXF R2004) - **DXFGraphic.dxf.shadow\_mode** | | | | --- | --- | | 0 | casts and receives shadows | | 1 | casts shadows | | 2 | receives shadows | | 3 | ignores shadows | (requires DXF R2007) **SEE ALSO:** - • *ezdxf.gfxattribs* module, helper tools to set graphical attributes of DXF entities - • *ezdxf.colors* module - • *Tutorial for Common Graphical Attributes* ### Face3d The 3DFACE entity (*DXF Reference*) is real 3D solid filled triangle or quadrilateral. Access vertices by name (**entity.dxf.vtx0 = (1.7, 2.3)**) or by index (**entity\[0\] = (1.7, 2.3)**). Unlike the entities *Solid* and *Trace*, the vertices of *Face3d* have the expected vertex order: ``` msp.add_3dface([(0, 0), (10, 0), (10, 10), (0, 10)]) ``` \[image\] | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'3DFACE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_3dface()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Face3d** The class name is *Face3d* because **3dface** is not a valid Python class name. - **dxf.vtx0** Location of 1. vertex (3D Point in *WCS*) - **dxf.vtx1** Location of 2. vertex (3D Point in *WCS*) - **dxf.vtx2** Location of 3. vertex (3D Point in *WCS*) - **dxf.vtx3** Location of 4. vertex (3D Point in *WCS*) - **dxf.invisible\_edges** invisible edge flag (int, default=0) | | | | --- | --- | | 1 | first edge is invisible | | 2 | second edge is invisible | | 4 | third edge is invisible | | 8 | fourth edge is invisible | Combine values by adding them, e.g. 1+4 = first and third edge is invisible. - **transform(m: *Matrix44*) -\> Face3d** Transform the 3DFACE entity by transformation matrix *m* inplace. - **wcs\_vertices(close: bool = False) -\> list\[*Vec3*\]** Returns WCS vertices, if argument *close* is **True**, the first vertex is also returned as closing last vertex. Returns 4 vertices when *close* is **False** and 5 vertices when *close* is **True**. Some edges may have zero-length. This is a compatibility interface to SOLID and TRACE. The 3DFACE entity is already defined by WCS vertices. ### Solid3d 3DSOLID entity (*DXF Reference*) created by an ACIS geometry kernel provided by the *Spatial Corp.* **SEE ALSO:** *Ezdxf* has only very limited support for ACIS based entities, for more information see the FAQ: *How to add/edit ACIS based entities like 3DSOLID, REGION or SURFACE?* | | | | --- | --- | | Subclass of | *ezdxf.entities.Body* | | DXF type | **'3DSOLID'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_3dsolid()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Solid3d** Same attributes and methods as parent class *Body*. - **dxf.history\_handle** Handle to history object. ### ACADProxyEntity An ACAD\_PROXY\_ENTITY (*DXF Reference*) is a proxy entity that represents an entity created by an Autodesk or 3rd party application. It stores the graphics and data of the original entity. The internals of this entity are unknown, so the entity cannot be copied or transformed. However, *ezdxf* can extract the proxy graphic from these entities as virtual entities or replace (explode) the entire entity with its proxy graphic. The meaning and data of this entity is lost when the entity is exploded. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'ACAD\_PROXY\_ENTITY'** | | Factory function | not supported | | Inherited DXF attributes | *Common graphical DXF attributes* | - **class ezdxf.entities.ACADProxyEntity** - **virtual\_entities() -\> Iterator\[DXFGraphic\]** Yields proxy graphic as “virtual” entities. - **explode(target\_layout: *BaseLayout* \| None = None) -\> *EntityQuery*** Explodes the proxy graphic for the ACAD\_PROXY\_ENTITY into the target layout, if target layout is **None**, the layout of the ACAD\_PROXY\_ENTITY will be used. This method destroys the source ACAD\_PROXY\_ENTITY entity. - **Parameters** **target\_layout** – target layout for exploded entities, **None** for same layout as the source ACAD\_PROXY\_ENTITY. - **Returns** *EntityQuery* container referencing all exploded DXF entities. ### Arc The ARC entity (*DXF Reference*) represents a circular arc, which is defined by the DXF attributes **dxf.center**, **dxf.radius**, **dxf.start\_angle** and **dxf.end\_angle**. The arc-curve goes always from **dxf.start\_angle** to **dxf.end\_angle** in counter-clockwise orientation around the **dxf.extrusion** vector, which is (0, 0, 1) by default and the usual case for 2D arcs. The ARC entity has *OCS* coordinates. The helper tool *ezdxf.math.ConstructionArc* supports creating arcs from various scenarios, like from 3 points or 2 points and an angle or 2 points and a radius and the *upright* module can convert inverted extrusion vectors from (0, 0, -1) to (0, 0, 1) without changing the curve. **SEE ALSO:** - • *Tutorial for Simple DXF Entities*, section *Arc* - • *ezdxf.math.ConstructionArc* - • *Object Coordinate System (OCS)* - • *ezdxf.upright* module | | | | --- | --- | | Subclass of | *ezdxf.entities.Circle* | | DXF type | **'ARC'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_arc()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Arc** - **dxf.center** Center point of arc (2D/3D Point in *OCS*) - **dxf.radius** Radius of arc (float) - **dxf.start\_angle** Start angle in degrees (float) - **dxf.end\_angle** End angle in degrees (float) - **start\_point** Returns the start point of the arc in *WCS*, takes the *OCS* into account. - **end\_point** Returns the end point of the arc in *WCS*, takes the *OCS* into account. - **angles(num: int) -\> Iterator\[float\]** Yields *num* angles from start- to end angle in degrees in counter-clockwise orientation. All angles are normalized in the range from \[0, 360). - **flattening(sagitta: float) -\> Iterator\[*Vec3*\]** Approximate the arc by vertices in *WCS*, the argument *sagitta* defines the maximum distance from the center of an arc segment to the center of its chord. - **transform(m: *Matrix44*) -\> Arc** Transform ARC entity by transformation matrix *m* inplace. Raises **NonUniformScalingError()** for non-uniform scaling. - **to\_ellipse(replace=True) -\> *Ellipse*** Convert the CIRCLE/ARC entity to an *Ellipse* entity. Adds the new ELLIPSE entity to the entity database and to the same layout as the source entity. - **Parameters** **replace** – replace (delete) source entity by ELLIPSE entity if **True** - **to\_spline(replace=True) -\> *Spline*** Convert the CIRCLE/ARC entity to a *Spline* entity. Adds the new SPLINE entity to the entity database and to the same layout as the source entity. - **Parameters** **replace** – replace (delete) source entity by SPLINE entity if **True** - **construction\_tool() -\> *ConstructionArc*** Returns the 2D construction tool *ezdxf.math.ConstructionArc* but the extrusion vector is ignored. - **apply\_construction\_tool(arc: *ConstructionArc*) -\> Arc** Set ARC data from the construction tool *ezdxf.math.ConstructionArc* but the extrusion vector is ignored. ### Body BODY entity (*DXF Reference*) created by an ACIS geometry kernel provided by the *Spatial Corp.* **SEE ALSO:** *Ezdxf* has only very limited support for ACIS based entities, for more information see the FAQ: *How to add/edit ACIS based entities like 3DSOLID, REGION or SURFACE?* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'BODY'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_body()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Body** - **dxf.version** Modeler format version number, default value is 1 - **dxf.flags** Require DXF R2013. - **dxf.uid** Require DXF R2013. - **property acis\_data: bytes \| Sequence\[str\]** Returns *SAT* data for DXF R2000 up to R2010 and *SAB* data for DXF R2013 and later - **property sat: Sequence\[str\]** Get/Set *SAT* data as sequence of strings. - **property sab: bytes** Get/Set *SAB* data as bytes. - **property has\_binary\_data** Returns **True** if the entity contains *SAB* data and **False** if the entity contains *SAT* data. - **tostring() -\> str** Returns ACIS *SAT* data as a single string if the entity has SAT data. ### Circle The CIRCLE entity (*DXF Reference*) defined by the DXF attributes **dxf.center** and **dxf.radius**. The CIRCLE entity has *OCS* coordinates. **SEE ALSO:** - • *Tutorial for Simple DXF Entities*, section *Circle* - • *ezdxf.math.ConstructionCircle* - • *Object Coordinate System (OCS)* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'CIRCLE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_circle()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Circle** - **dxf.center** Center point of circle (2D/3D Point in *OCS*) - **dxf.radius** Radius of circle (float) - **vertices(angles: Iterable\[float\]) -\> Iterator\[*Vec3*\]** Yields the vertices of the circle of all given *angles* as *Vec3* instances in *WCS*. - **Parameters** **angles** – iterable of angles in *OCS* as degrees, angle goes counter-clockwise around the extrusion vector, and the OCS x-axis defines 0-degree. - **flattening(sagitta: float) -\> Iterator\[*Vec3*\]** Approximate the circle by vertices in *WCS* as *Vec3* instances. The argument *sagitta* is the maximum distance from the center of an arc segment to the center of its chord. Yields a closed polygon where the start vertex is equal to the end vertex! - **transform(m: *Matrix44*) -\> Circle** Transform the CIRCLE entity by transformation matrix *m* inplace. Raises **NonUniformScalingError()** for non-uniform scaling. - **translate(dx: float, dy: float, dz: float) -\> Circle** Optimized CIRCLE/ARC translation about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis, returns *self* (floating interface). - **to\_ellipse(replace=True) -\> *Ellipse*** Convert the CIRCLE/ARC entity to an *Ellipse* entity. Adds the new ELLIPSE entity to the entity database and to the same layout as the source entity. - **Parameters** **replace** – replace (delete) source entity by ELLIPSE entity if **True** - **to\_spline(replace=True) -\> *Spline*** Convert the CIRCLE/ARC entity to a *Spline* entity. Adds the new SPLINE entity to the entity database and to the same layout as the source entity. - **Parameters** **replace** – replace (delete) source entity by SPLINE entity if **True** ### Dimension The DIMENSION entity (*DXF Reference*) represents several types of dimensions in many orientations and alignments. The basic types of dimensioning are linear, radial, angular, ordinate, and arc length. For more information about dimensions see the online help from AutoDesk: *About the Types of Dimensions* **IMPORTANT:** The DIMENSION entity is reused to create dimensional constraints, such entities do not have an associated geometrical block nor a dimension type group code (2) and reside on layer **\*ADSK\_CONSTRAINTS**. Use property *Dimension.is\_dimensional\_constraint* to check for this objects. Dimensional constraints are not documented in the DXF reference and not supported by *ezdxf*. **SEE ALSO:** - • *Tutorial for Linear Dimensions* - • *Tutorial for Radius Dimensions* - • *Tutorial for Diameter Dimensions* - • *Tutorial for Angular Dimensions* - • *Tutorial for Ordinate Dimensions* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'DIMENSION'** | | factory function | see table below | | Inherited DXF attributes | *Common graphical DXF attributes* | ### Factory Functions | | | | --- | --- | | *Linear and Rotated Dimension (DXF)* | *add\_linear\_dim()* | | *Aligned Dimension (DXF)* | *add\_aligned\_dim()* | | *Angular Dimension (DXF)* | *add\_angular\_dim\_2l()* | | *Angular 3P Dimension (DXF)* | *add\_angular\_dim\_3p()* | | Angular Dimension by center, radius, angles | *add\_angular\_dim\_cra()* | | Angular Dimension by ConstructionArc | *add\_angular\_dim\_arc()* | | *Diameter Dimension (DXF)* | *add\_diameter\_dim()* | | *Radius Dimension (DXF)* | *add\_radius\_dim()* | | *Ordinate Dimension (DXF)* | *add\_ordinate\_dim()* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Dimension** There is only one *Dimension* class to represent all different dimension types. - **dxf.version** Version number: **0** = R2010. (int, DXF R2010) - **dxf.geometry** Name of the BLOCK that contains the entities that make up the dimension picture. For AutoCAD this graphical representation is mandatory, otherwise AutoCAD will not open the DXF document. BricsCAD will render the DIMENSION entity by itself, if the graphical representation is not present, but displays the BLOCK content if present. - **dxf.dimstyle** Dimension style (*DimStyle*) name as string. - **dxf.dimtype** Values 0-6 are integer values that represent the dimension type. Values 32, 64, and 128 are bit values, which are added to the integer values. | | | | --- | --- | | 0 | *Linear and Rotated Dimension (DXF)* | | 1 | *Aligned Dimension (DXF)* | | 2 | *Angular Dimension (DXF)* | | 3 | *Diameter Dimension (DXF)* | | 4 | *Radius Dimension (DXF)* | | 5 | *Angular 3P Dimension (DXF)* | | 6 | *Ordinate Dimension (DXF)* | | 8 | subclass *ezdxf.entities.ArcDimension* introduced in DXF R2004 | | 32 | Indicates that graphical representation **geometry** is referenced by this dimension only. (always set in DXF R13 and later) | | 64 | Ordinate type. This is a bit value (bit 7) used only with integer value 6. If set, ordinate is *X-type*; if not set, ordinate is *Y-type* | | 128 | This is a bit value (bit 8) added to the other **dimtype** values if the dimension text has been positioned at a user-defined location rather than at the default location | - **dxf.defpoint** Definition point for all dimension types. (3D Point in *WCS*) - • Linear- and rotated dimension: **dxf.defpoint** specifies the dimension line location. - • Arc- and angular dimension: **dxf.defpoint** and **dxfdefpoint4** specify the endpoints of the line used to determine the second extension line. - **dxf.defpoint2** Definition point for linear- and angular dimensions. (3D Point in *WCS*) - • Linear- and rotated dimension: The **dxf.defpoint2** specifies the start point of the first extension line. - • Arc- and angular dimension: The **dxf.defpoint2** and **dxf.defpoint3** specify the endpoints of the line used to determine the first extension line. - **dxf.defpoint3** Definition point for linear- and angular dimensions. (3D Point in *WCS*) - • Linear- and rotated dimension: The **dxf.defpoint3** specifies the start point of the second extension line. - • Arc- and angular dimension: The **dxf.defpoint2** and **dxf.defpoint3** specify the endpoints of the line used to determine the first extension line. - **dxf.defpoint4** Definition point for diameter-, radius-, and angular dimensions. (3D Point in *WCS*) The **dxf.defpoint** and **dxf.defpoint4** specify the endpoints of the line used to determine the second extension line for arc- and angular dimension: - **dxf.defpoint5** This point defines the location of the arc for angular dimensions. (3D Point in *OCS*) - **dxf.angle** Rotation angle of linear and rotated dimensions in degrees. (float) - **dxf.leader\_length** Leader length for radius and diameter dimensions. (float) - **dxf.text\_midpoint** Middle point of dimension text. (3D Point in *OCS*) - **dxf.insert** Insertion point for clones of a linear dimensions. (3D Point in *OCS*) This value translates the content of the associated anonymous block for cloned linear dimensions, similar to the **insert** attribute of the *Insert* entity. - **dxf.attachment\_point** Text attachment point (int, DXF R2000), default value is 5. | | | | --- | --- | | 1 | Top left | | 2 | Top center | | 3 | Top right | | 4 | Middle left | | 5 | Middle center | | 6 | Middle right | | 7 | Bottom left | | 8 | Bottom center | | 9 | Bottom right | - **dxf.line\_spacing\_style** Dimension text line-spacing style (int, DXF R2000), default value is 1. | | | | --- | --- | | 1 | At least (taller characters will override) | | 2 | Exact (taller characters will not override) | - **dxf.line\_spacing\_factor** Dimension text-line spacing factor. (float, DXF R2000) Percentage of default (3-on-5) line spacing to be applied. Valid values range from 0.25 to 4.00. - **dxf.actual\_measurement** Actual measurement (float, DXF R2000), this is an optional attribute and often not present. (read-only value) - **dxf.text** Dimension text explicitly entered by the user (str), default value is an empty string. If empty string or “\<\>”, the dimension measurement is drawn as the text, if “ ” (one blank space), the text is suppressed. Anything else will be displayed as the dimension text. - **dxf.oblique\_angle** The optional **dxf.oblique\_angle** defines the angle of the extension lines for linear dimension. - **dxf.text\_rotation** Defines is the rotation angle of the dimension text away from its default orientation (the direction of the dimension line). (float) - **dxf.horizontal\_direction** Indicates the horizontal direction for the dimension entity (float). This attribute determines the orientation of dimension text and lines for horizontal, vertical, and rotated linear dimensions. This value is the negative of the angle in the OCS xy-plane between the dimension line and the OCS x-axis. - **property dimtype: int** *dxf.dimtype* without binary flags (32, 62, 128). - **property is\_dimensional\_constraint: bool** Returns **True** if the DIMENSION entity is a dimensional constraint object. - **get\_dim\_style() -\> *DimStyle*** Returns the associated *DimStyle* entity. - **get\_geometry\_block() -\> *BlockLayout* \| None** Returns *BlockLayout* of associated anonymous dimension block, which contains the entities that make up the dimension picture. Returns **None** if block name is not set or the BLOCK itself does not exist - **get\_measurement() -\> float \| *Vec3*** Returns the actual dimension measurement in *WCS* units, no scaling applied for linear dimensions. Returns angle in degrees for angular dimension from 2 lines and angular dimension from 3 points. Returns vector from origin to feature location for ordinate dimensions. - **override() -\> DimStyleOverride** Returns the *DimStyleOverride* object. - **render() -\> None** Renders the graphical representation of the DIMENSION entity as DXF primitives (TEXT, LINE, ARC, …) into an anonymous content BLOCK. - **transform(m: *Matrix44*) -\> Dimension** Transform the DIMENSION entity by transformation matrix *m* inplace. Raises **NonUniformScalingError()** for non uniform scaling. - **virtual\_entities() -\> Iterator\[DXFGraphic\]** Yields the graphical representation of the anonymous content BLOCK as virtual DXF primitives (LINE, ARC, TEXT, …). These virtual entities are located at the original location of the DIMENSION entity, but they are not stored in the entity database, have no handle and are not assigned to any layout. - **explode(target\_layout: *BaseLayout* \| None = None) -\> *EntityQuery*** Explodes the graphical representation of the DIMENSION entity as DXF primitives (LINE, ARC, TEXT, …) into the target layout, **None** for the same layout as the source DIMENSION entity. Returns an *EntityQuery* container containing all DXF primitives. - **Parameters** **target\_layout** – target layout for the DXF primitives, **None** for same layout as source DIMENSION entity. ### DimStyleOverride All of the *DimStyle* attributes can be overridden for each *Dimension* entity individually. The *DimStyleOverride* class manages all the complex dependencies between *DimStyle* and *Dimension*, the different features of all DXF versions and the rendering process to create the *Dimension* picture as BLOCK, which is required for AutoCAD. - **class ezdxf.entities.DimStyleOverride** - **dimension** Base *Dimension* entity. - **dimstyle** By *dimension* referenced *DimStyle* entity. - **dimstyle\_attribs** Contains all overridden attributes of *dimension*, as a **dict** with *DimStyle* attribute names as keys. - **\_\_getitem\_\_(key: str) -\> Any** Returns DIMSTYLE attribute *key*, see also *get()*. - **\_\_setitem\_\_(key: str, value: Any) -\> None** Set DIMSTYLE attribute *key* in *dimstyle\_attribs*. - **\_\_delitem\_\_(key: str) -\> None** Deletes DIMSTYLE attribute *key* from *dimstyle\_attribs*, ignores **KeyErrors** silently. - **get(attribute: str, default: Any = None) -\> Any** Returns DIMSTYLE *attribute* from override dict *dimstyle\_attribs* or base *DimStyle*. Returns *default* value for attributes not supported by DXF R12. This is a hack to use the same algorithm to render DXF R2000 and DXF R12 DIMENSION entities. But the DXF R2000 attributes are not stored in the DXF R12 file! This method does not catch invalid attribute names! Check debug log for ignored DIMSTYLE attributes. - **pop(attribute: str, default: Any = None) -\> Any** Returns DIMSTYLE *attribute* from override dict *dimstyle\_attribs* and removes this *attribute* from override dict. - **update(attribs: dict) -\> None** Update override dict *dimstyle\_attribs*. - **Parameters** **attribs** – **dict** of DIMSTYLE attributes - **commit() -\> None** Writes overridden DIMSTYLE attributes into ACAD:DSTYLE section of XDATA of the DIMENSION entity. - **get\_arrow\_names() -\> tuple\[str, str\]** Get arrow names as strings like ‘ARCHTICK’ as tuple (dimblk1, dimblk2). - **set\_arrows(blk: str \| None = None, blk1: str \| None = None, blk2: str \| None = None, ldrblk: str \| None = None, size: float \| None = None) -\> None** Set arrows or user defined blocks and disable oblique stroke as tick. - **Parameters** - • **blk** – defines both arrows at once as name str or user defined block - • **blk1** – defines left arrow as name str or as user defined block - • **blk2** – defines right arrow as name str or as user defined block - • **ldrblk** – defines leader arrow as name str or as user defined block - • **size** – arrow size in drawing units - **set\_tick(size: float = 1) -\> None** Use oblique stroke as tick, disables arrows. - **Parameters** **size** – arrow size in daring units - **set\_text\_align(halign: str \| None = None, valign: str \| None = None, vshift: float \| None = None) -\> None** Set measurement text alignment, *halign* defines the horizontal alignment, *valign* defines the vertical alignment, *above1* and *above2* means above extension line 1 or 2 and aligned with extension line. - **Parameters** - • **halign** – *left*, *right*, *center*, *above1*, *above2*, requires DXF R2000+ - • **valign** – *above*, *center*, *below* - • **vshift** – vertical text shift, if *valign* is *center*; \>0 shift upward, \<0 shift downwards - **set\_tolerance(upper: float, lower: float \| None = None, hfactor: float \| None = None, align: *MTextLineAlignment* \| None = None, dec: int \| None = None, leading\_zeros: bool \| None = None, trailing\_zeros: bool \| None = None) -\> None** Set tolerance text format, upper and lower value, text height factor, number of decimal places or leading and trailing zero suppression. - **Parameters** - • **upper** – upper tolerance value - • **lower** – lower tolerance value, if None same as upper - • **hfactor** – tolerance text height factor in relation to the dimension text height - • **align** – tolerance text alignment enum *ezdxf.enums.MTextLineAlignment* - • **dec** – Sets the number of decimal places displayed - • **leading\_zeros** – suppress leading zeros for decimal dimensions if **False** - • **trailing\_zeros** – suppress trailing zeros for decimal dimensions if **False** - **set\_limits(upper: float, lower: float, hfactor: float \| None = None, dec: int \| None = None, leading\_zeros: bool \| None = None, trailing\_zeros: bool \| None = None) -\> None** Set limits text format, upper and lower limit values, text height factor, number of decimal places or leading and trailing zero suppression. - **Parameters** - • **upper** – upper limit value added to measurement value - • **lower** – lower limit value subtracted from measurement value - • **hfactor** – limit text height factor in relation to the dimension text height - • **dec** – Sets the number of decimal places displayed, requires DXF R2000+ - • **leading\_zeros** – suppress leading zeros for decimal dimensions if **False**, requires DXF R2000+ - • **trailing\_zeros** – suppress trailing zeros for decimal dimensions if **False**, requires DXF R2000+ - **set\_text\_format(prefix: str = '', postfix: str = '', rnd: float \| None = None, dec: int \| None = None, sep: str \| None = None, leading\_zeros: bool \| None = None, trailing\_zeros: bool \| None = None) -\> None** Set dimension text format, like prefix and postfix string, rounding rule and number of decimal places. - **Parameters** - • **prefix** – dimension text prefix text as string - • **postfix** – dimension text postfix text as string - • **rnd** – Rounds all dimensioning distances to the specified value, for instance, if DIMRND is set to 0.25, all distances round to the nearest 0.25 unit. If you set DIMRND to 1.0, all distances round to the nearest integer. - • **dec** – Sets the number of decimal places displayed for the primary units of a dimension. requires DXF R2000+ - • **sep** – “.” or “,” as decimal separator - • **leading\_zeros** – suppress leading zeros for decimal dimensions if **False** - • **trailing\_zeros** – suppress trailing zeros for decimal dimensions if **False** - **set\_dimline\_format(color: int \| None = None, linetype: str \| None = None, lineweight: int \| None = None, extension: float \| None = None, disable1: bool \| None = None, disable2: bool \| None = None)** Set dimension line properties. - **Parameters** - • **color** – color index - • **linetype** – linetype as string - • **lineweight** – line weight as int, 13 = 0.13mm, 200 = 2.00mm - • **extension** – extension length - • **disable1** – True to suppress first part of dimension line - • **disable2** – True to suppress second part of dimension line - **set\_extline\_format(color: int \| None = None, lineweight: int \| None = None, extension: float \| None = None, offset: float \| None = None, fixed\_length: float \| None = None)** Set common extension line attributes. - **Parameters** - • **color** – color index - • **lineweight** – line weight as int, 13 = 0.13mm, 200 = 2.00mm - • **extension** – extension length above dimension line - • **offset** – offset from measurement point - • **fixed\_length** – set fixed length extension line, length below the dimension line - **set\_extline1(linetype: str \| None = None, disable=False)** Set attributes of the first extension line. - **Parameters** - • **linetype** – linetype for the first extension line - • **disable** – disable first extension line if **True** - **set\_extline2(linetype: str \| None = None, disable=False)** Set attributes of the second extension line. - **Parameters** - • **linetype** – linetype for the second extension line - • **disable** – disable the second extension line if **True** - **set\_text(text: str = '\<\>') -\> None** Set dimension text. - • *text* = “ “ to suppress dimension text - • *text* = “” or “\<\>” to use measured distance as dimension text - • otherwise display *text* literally - **shift\_text(dh: float, dv: float) -\> None** Set relative text movement, implemented as user location override without leader. - **Parameters** - • **dh** – shift text in text direction - • **dv** – shift text perpendicular to text direction - **set\_location(location: *UVec*, leader=False, relative=False) -\> None** Set text location by user, special version for linear dimensions, behaves for other dimension types like *user\_location\_override()*. - **Parameters** - • **location** – user defined text location - • **leader** – create leader from text to dimension line - • **relative** – *location* is relative to default location. - **user\_location\_override(location: *UVec*) -\> None** Set text location by user, *location* is relative to the origin of the UCS defined in the *render()* method or WCS if the *ucs* argument is **None**. - **render(ucs: *UCS* \| None = None, discard=False) -\> BaseDimensionRenderer** Starts the dimension line rendering process and also writes overridden dimension style attributes into the DSTYLE XDATA section. The rendering process “draws” the graphical representation of the DIMENSION entity as DXF primitives (TEXT, LINE, ARC, …) into an anonymous content BLOCK. You can discard the content BLOCK for a friendly CAD applications like BricsCAD, because the rendering of the dimension entity is done automatically by BricsCAD if the content BLOCK is missing, and the result is in most cases better than the rendering done by *ezdxf*. AutoCAD does not render DIMENSION entities automatically, therefore I see AutoCAD as an unfriendly CAD application. - **Parameters** - • **ucs** – user coordinate system - • **discard** – discard the content BLOCK created by *ezdxf*, this works for BricsCAD, AutoCAD refuses to open DXF files containing DIMENSION entities without a content BLOCK - **Returns** The rendering object of the DIMENSION entity for analytics ### ArcDimension The ARC\_DIMENSION entity was introduced in DXF R2004 and is **not** documented in the DXF reference. **SEE ALSO:** *Tutorial for Arc Dimensions* | | | | --- | --- | | Subclass of | *ezdxf.entities.Dimension* | | DXF type | **'ARC\_DIMENSION'** | | factory function | *add\_arc\_dim\_3p()* *add\_arc\_dim\_cra()* *add\_arc\_dim\_arc()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | R2004 / AC1018 | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.ArcDimension** - **dxf.defpoint2** start point of first extension line in *OCS* - **dxf.defpoint3** start point of second extension line in *OCS* - **dxf.defpoint4** center point of arc in *OCS* - **dxf.start\_angle** - **dxf.end\_angle** - **dxf.is\_partial** - **dxf.has\_leader** - **dxf.leader\_point1** - **dxf.leader\_point2** - **dimtype** Returns always **8**. ### Ellipse The ELLIPSE entity (*DXF Reference*) is an elliptic 3D curve defined by the DXF attributes **dxf.center**, the **dxf.major\_axis** vector and the **dxf.extrusion** vector. The **dxf.ratio** attribute is the ratio of minor axis to major axis and has to be smaller or equal 1. The **dxf.start\_param** and **dxf.end\_param** attributes defines the starting- and the end point of the ellipse, a full ellipse goes from 0 to 2π. The curve always goes from start- to end param in counter clockwise orientation. The **dxf.extrusion** vector defines the normal vector of the ellipse plane. The minor axis direction is calculated by **dxf.extrusion** cross **dxf.major\_axis**. The default extrusion vector (0, 0, 1) defines an ellipse plane parallel to xy-plane of the *WCS*. All coordinates and vectors in *WCS*. **SEE ALSO:** - • *Tutorial for Simple DXF Entities*, section *Ellipse* - • *ezdxf.math.ConstructionEllipse* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'ELLIPSE'** | | factory function | *add\_ellipse()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.Ellipse** - **dxf.center** Center point of circle (2D/3D Point in *WCS*) - **dxf.major\_axis** Endpoint of major axis, relative to the **dxf.center** (Vec3), default value is (1, 0, 0). - **dxf.ratio** Ratio of minor axis to major axis (float), has to be in range from 0.000001 to 1.0, default value is 1. - **dxf.start\_param** Start parameter (float), default value is 0. - **dxf.end\_param** End parameter (float), default value is 2π. - **start\_point** Returns the start point of the ellipse in WCS. - **end\_point** Returns the end point of the ellipse in WCS. - **minor\_axis** Returns the minor axis of the ellipse as **Vec3** in WCS. - **construction\_tool() -\> *ConstructionEllipse*** Returns construction tool *ezdxf.math.ConstructionEllipse*. - **apply\_construction\_tool(e: *ConstructionEllipse*) -\> Ellipse** Set ELLIPSE data from construction tool *ezdxf.math.ConstructionEllipse*. - **vertices(params: Iterable\[float\]) -\> Iterable\[*Vec3*\]** Yields vertices on ellipse for iterable *params* in WCS. - **Parameters** **params** – param values in the range from 0 to 2π in radians, param goes counter-clockwise around the extrusion vector, major\_axis = local x-axis = 0 rad. - **flattening(distance: float, segments: int = 8) -\> Iterable\[*Vec3*\]** Adaptive recursive flattening. The argument *segments* is the minimum count of approximation segments, if the distance from the center of the approximation segment to the curve is bigger than *distance* the segment will be subdivided. Returns a closed polygon for a full ellipse where the start vertex has the same value as the end vertex. - **Parameters** - • **distance** – maximum distance from the projected curve point onto the segment chord. - • **segments** – minimum segment count - **params(num: int) -\> Iterable\[float\]** Returns *num* params from start- to end param in counter-clockwise order. All params are normalized in the range \[0, 2π). - **transform(m: *Matrix44*) -\> Ellipse** Transform the ELLIPSE entity by transformation matrix *m* inplace. - **translate(dx: float, dy: float, dz: float) -\> Ellipse** Optimized ELLIPSE translation about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis, returns *self* (floating interface). - **to\_spline(replace=True) -\> *Spline*** Convert ELLIPSE to a *Spline* entity. Adds the new SPLINE entity to the entity database and to the same layout as the source entity. - **Parameters** **replace** – replace (delete) source entity by SPLINE entity if **True** - **classmethod from\_arc(entity: DXFGraphic) -\> Ellipse** Create a new virtual ELLIPSE entity from an ARC or a CIRCLE entity. The new entity has no owner, no handle, is not stored in the entity database nor assigned to any layout! ### Hatch The HATCH entity (*DXF Reference*) fills a closed area defined by one or more boundary paths by a hatch pattern, a solid fill, or a gradient fill. All points in *OCS* as (x, y) tuples (*Hatch.dxf.elevation* is the z-axis value). There are two different hatch pattern default scaling, depending on the HEADER variable $MEASUREMENT, one for ISO measurement (m, cm, mm, …) and one for imperial measurement (in, ft, yd, …). The default scaling for predefined hatch pattern will be chosen according this measurement setting in the HEADER section, this replicates the behavior of BricsCAD and other CAD applications. *Ezdxf* uses the ISO pattern definitions as a base line and scales this pattern down by factor 1/25.6 for imperial measurement usage. The pattern scaling is independent from the drawing units of the document defined by the HEADER variable $INSUNITS. **SEE ALSO:** *Tutorial for Hatch* and *DXF Units* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'HATCH'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_hatch()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | Boundary paths classes Path manager: *BoundaryPaths* - • *PolylinePath* - • - ***EdgePath*** - • *LineEdge* - • *ArcEdge* - • *EllipseEdge* - • *SplineEdge* Pattern and gradient classes - • *Pattern* - • *PatternLine* - • *Gradient* - **class ezdxf.entities.Hatch** - **dxf.pattern\_name** Pattern name as string - **dxf.solid\_fill** | | | | --- | --- | | 1 | solid fill, use method *Hatch.set\_solid\_fill()* | | 0 | pattern fill, use method *Hatch.set\_pattern\_fill()* | - **dxf.associative** | | | | --- | --- | | 1 | associative hatch | | 0 | not associative hatch | Associations are not managed by *ezdxf*. - **dxf.hatch\_style** | | | | --- | --- | | 0 | normal | | 1 | outer | | 2 | ignore | (search AutoCAD help for more information) - **dxf.pattern\_type** | | | | --- | --- | | 0 | user | | 1 | predefined | | 2 | custom | - **dxf.pattern\_angle** The actual pattern rotation angle in degrees (float). Changing this value does not rotate the pattern, use *set\_pattern\_angle()* for this task. - **dxf.pattern\_scale** The actual pattern scale factor (float). Changing this value does not scale the pattern use *set\_pattern\_scale()* for this task. - **dxf.pattern\_double** 1 = double pattern size else 0. (int) - **dxf.n\_seed\_points** Count of seed points (use **get\_seed\_points()**) - **dxf.elevation** Z value represents the elevation height of the *OCS*. (float) - **paths** *BoundaryPaths* object. - **pattern** *Pattern* object. - **gradient** *Gradient* object. - **seeds** A list of seed points as (x, y) tuples. - **property has\_solid\_fill: bool** **True** if entity has a solid fill. (read only) - **property has\_pattern\_fill: bool** **True** if entity has a pattern fill. (read only) - **property has\_gradient\_data: bool** **True** if entity has a gradient fill. A hatch with gradient fill has also a solid fill. (read only) - **property bgcolor: *RGB* \| None** Set pattern fill background color as (r, g, b)-tuple, rgb values in the range \[0, 255\] (read/write/del) usage: ``` r, g, b = entity.bgcolor # get pattern fill background color entity.bgcolor = (10, 20, 30) # set pattern fill background color del entity.bgcolor # delete pattern fill background color ``` - **set\_pattern\_definition(lines: Sequence, factor: float = 1, angle: float = 0) -\> None** Setup pattern definition by a list of definition lines and the definition line is a 4-tuple (angle, base\_point, offset, dash\_length\_items). The pattern definition should be designed for a pattern scale factor of 1 and a pattern rotation angle of 0. - • angle: line angle in degrees - • base-point: (x, y) tuple - • offset: (dx, dy) tuple - • dash\_length\_items: list of dash items (item \> 0 is a line, item \< 0 is a gap and item == 0.0 is a point) - **Parameters** - • **lines** – list of definition lines - • **factor** – pattern scale factor - • **angle** – rotation angle in degrees - **set\_pattern\_scale(scale: float) -\> None** Sets the pattern scale factor and scales the pattern definition. The method always starts from the original base scale, the **set\_pattern\_scale(1)** call resets the pattern scale to the original appearance as defined by the pattern designer, but only if the pattern attribute *dxf.pattern\_scale* represents the actual scale, it cannot restore the original pattern scale from the pattern definition itself. - **Parameters** **scale** – pattern scale factor - **set\_pattern\_angle(angle: float) -\> None** Sets the pattern rotation angle and rotates the pattern definition. The method always starts from the original base rotation of 0, the **set\_pattern\_angle(0)** call resets the pattern rotation angle to the original appearance as defined by the pattern designer, but only if the pattern attribute *dxf.pattern\_angle* represents the actual pattern rotation, it cannot restore the original rotation angle from the pattern definition itself. - **Parameters** **angle** – pattern rotation angle in degrees - **set\_solid\_fill(color: int = 7, style: int = 1, rgb: *RGB* \| None = None)** Set the solid fill mode and removes all gradient and pattern fill related data. - **Parameters** - • **color** – *AutoCAD Color Index (ACI)*, (0 = BYBLOCK; 256 = BYLAYER) - • **style** – hatch style (0 = normal; 1 = outer; 2 = ignore) - • **rgb** – true color value as (r, g, b)-tuple - has higher priority than *color*. True color support requires DXF R2000. - **set\_pattern\_fill(name: str, color: int = 7, angle: float = 0.0, scale: float = 1.0, double: int = 0, style: int = 1, pattern\_type: int = 1, definition=None) -\> None** Sets the pattern fill mode and removes all gradient related data. The pattern definition should be designed for a scale factor 1 and a rotation angle of 0 degrees. The predefined hatch pattern like “ANSI33” are scaled according to the HEADER variable $MEASUREMENT for ISO measurement (m, cm, … ), or imperial units (in, ft, …), this replicates the behavior of BricsCAD. - **Parameters** - • **name** – pattern name as string - • **color** – pattern color as *AutoCAD Color Index (ACI)* - • **angle** – pattern rotation angle in degrees - • **scale** – pattern scale factor - • **double** – double size flag - • **style** – hatch style (0 = normal; 1 = outer; 2 = ignore) - • **pattern\_type** – pattern type (0 = user-defined; 1 = predefined; 2 = custom) - • **definition** – list of definition lines and a definition line is a 4-tuple \[angle, base\_point, offset, dash\_length\_items\], see *set\_pattern\_definition()* - **set\_gradient(color1: *RGB* = RGB(0, 0, 0), color2: *RGB* = RGB(255, 255, 255), rotation: float = 0.0, centered: float = 0.0, one\_color: int = 0, tint: float = 0.0, name: str = 'LINEAR') -\> None** Sets the gradient fill mode and removes all pattern fill related data, requires DXF R2004 or newer. A gradient filled hatch is also a solid filled hatch. Valid gradient type names are: - • “LINEAR” - • “CYLINDER” - • “INVCYLINDER” - • “SPHERICAL” - • “INVSPHERICAL” - • “HEMISPHERICAL” - • “INVHEMISPHERICAL” - • “CURVED” - • “INVCURVED” - **Parameters** - • **color1** – (r, g, b)-tuple for first color, rgb values as int in the range \[0, 255\] - • **color2** – (r, g, b)-tuple for second color, rgb values as int in the range \[0, 255\] - • **rotation** – rotation angle in degrees - • **centered** – determines whether the gradient is centered or not - • **one\_color** – 1 for gradient from *color1* to tinted *color1* - • **tint** – determines the tinted target *color1* for a one color gradient. (valid range 0.0 to 1.0) - • **name** – name of gradient type, default “LINEAR” - **set\_seed\_points(points: Iterable\[tuple\[float, float\]\]) -\> None** Set seed points, *points* is an iterable of (x, y)-tuples. I don’t know why there can be more than one seed point. All points in *OCS* (*Hatch.dxf.elevation* is the Z value) - **transform(m: *Matrix44*) -\> *Hatch*** Transform entity by transformation matrix *m* inplace. - **associate(path: AbstractBoundaryPath, entities: Iterable\[*DXFEntity*\])** Set association from hatch boundary *path* to DXF geometry *entities*. A HATCH entity can be associative to a base geometry, this association is **not** maintained nor verified by *ezdxf*, so if you modify the base geometry 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! - **remove\_association()** Remove associated path elements. ### Boundary Paths The hatch entity is build by different path types, these are the filter flags for the *Hatch.dxf.hatch\_style*: - • EXTERNAL: defines the outer boundary of the hatch - • OUTERMOST: defines the first tier of inner hatch boundaries - • DEFAULT: default boundary path As you will learn in the next sections, these are more the recommended usage type for the flags, but the fill algorithm doesn’t care much about that, for instance an OUTERMOST path doesn’t have to be inside the EXTERNAL path. ### Island Detection In general the island detection algorithm works always from outside to inside and alternates filled and unfilled areas. The area between then 1st and the 2nd boundary is filled, the area between the 2nd and the 3rd boundary is unfilled and so on. The different hatch styles defined by the *Hatch.dxf.hatch\_style* attribute are created by filtering some boundary path types. ### Hatch Style - • HATCH\_STYLE\_IGNORE: Ignores all paths except the paths marked as EXTERNAL, if there are more than one path marked as EXTERNAL, they are filled in NESTED style. Creates no hatch if no path is marked as EXTERNAL. - • HATCH\_STYLE\_OUTERMOST: Ignores all paths marked as DEFAULT, remaining EXTERNAL and OUTERMOST paths are filled in NESTED style. Creates no hatch if no path is marked as EXTERNAL or OUTERMOST. - • HATCH\_STYLE\_NESTED: Use all existing paths. ### Hatch Boundary Classes - **class ezdxf.entities.BoundaryPaths** Defines the borders of the hatch, a hatch can consist of more than one path. - **paths** List of all boundary paths. Contains *PolylinePath* and *EdgePath* objects. (read/write) - **external\_paths() -\> Iterable\[AbstractBoundaryPath\]** Iterable of external paths, could be empty. - **outermost\_paths() -\> Iterable\[AbstractBoundaryPath\]** Iterable of outermost paths, could be empty. - **default\_paths() -\> Iterable\[AbstractBoundaryPath\]** Iterable of default paths, could be empty. - **rendering\_paths(hatch\_style: int = const.HATCH\_STYLE\_NESTED) -\> Iterable\[AbstractBoundaryPath\]** Iterable of paths to process for rendering, filters unused boundary paths according to the given hatch style: - • NESTED: use all boundary paths - • OUTERMOST: use EXTERNAL and OUTERMOST boundary paths - • IGNORE: ignore all paths except EXTERNAL boundary paths Yields paths in order of EXTERNAL, OUTERMOST and DEFAULT. - **append(path: AbstractBoundaryPath) -\> None** Append a new boundary path. Added in version 1.4. - **add\_polyline\_path(path\_vertices: Iterable\[tuple\[float, ...\]\], is\_closed: bool = True, flags: int = 1) -\> PolylinePath** Create and add a new *PolylinePath* object. - **Parameters** - • **path\_vertices** – iterable of polyline vertices as (x, y) or (x, y, bulge)-tuples. - • **is\_closed** – 1 for a closed polyline else 0 - • **flags** – default(0), external(1), derived(4), textbox(8) or outermost(16) - **add\_edge\_path(flags: int = 1) -\> EdgePath** Create and add a new *EdgePath* object. - **Parameters** **flags** – default(0), external(1), derived(4), textbox(8) or outermost(16) - **polyline\_to\_edge\_paths(just\_with\_bulge=True) -\> None** Convert polyline paths including bulge values to line- and arc edges. - **Parameters** **just\_with\_bulge** – convert only polyline paths including bulge values if **True** - **edge\_to\_polyline\_paths(distance: float, segments: int = 16)** Convert all edge paths to simple polyline paths without bulges. - **Parameters** - • **distance** – maximum distance from the center of the curve to the center of the line segment between two approximation points to determine if a segment should be subdivided. - • **segments** – minimum segment count per curve - **arc\_edges\_to\_ellipse\_edges() -\> None** Convert all arc edges to ellipse edges. - **ellipse\_edges\_to\_spline\_edges(num: int = 32) -\> None** Convert all ellipse edges to spline edges (approximation). - **Parameters** **num** – count of control points for a **full** ellipse, partial ellipses have proportional fewer control points but at least 3. - **spline\_edges\_to\_line\_edges(factor: int = 8) -\> None** Convert all spline edges to line edges (approximation). - **Parameters** **factor** – count of approximation segments = count of control points x factor - **all\_to\_spline\_edges(num: int = 64) -\> None** Convert all bulge, arc and ellipse edges to spline edges (approximation). - **Parameters** **num** – count of control points for a **full** circle/ellipse, partial circles/ellipses have proportional fewer control points but at least 3. - **all\_to\_line\_edges(num: int = 64, spline\_factor: int = 8) -\> None** Convert all bulge, arc and ellipse edges to spline edges and approximate this splines by line edges. - **Parameters** - • **num** – count of control points for a **full** circle/ellipse, partial circles/ellipses have proportional fewer control points but at least 3. - • **spline\_factor** – count of spline approximation segments = count of control points x spline\_factor - **clear() -\> None** Remove all boundary paths. - **class ezdxf.entities.BoundaryPathType** - **POLYLINE** polyline path type - **EDGE** edge path type - **class ezdxf.entities.PolylinePath** A polyline as hatch boundary path. - **type** Path type as *BoundaryPathType.POLYLINE* enum - **path\_type\_flags** (bit coded flags) | | | | --- | --- | | 0 | default | | 1 | external | | 2 | polyline, will be set by *ezdxf* | | 4 | derived (?) | | 8 | textbox | | 16 | outermost | My interpretation of the *path\_type\_flags*, see also *Tutorial for Hatch*: - • external: path is part of the hatch outer border - • outermost: path is completely inside of one or more external paths - • default: path is completely inside of one or more outermost paths If there are troubles with AutoCAD, maybe the hatch entity has the **Hatch.dxf.pixel\_size** attribute set - delete it **del hatch.dxf.pixel\_size** and maybe the problem is solved. *Ezdxf* does not use the **Hatch.dxf.pixel\_size** attribute, but it can occur in DXF files created by other applications. - **is\_closed** **True** if polyline path is closed. - **vertices** List of path vertices as (x, y, bulge)-tuples. (read/write) - **source\_boundary\_objects** List of handles of the associated DXF entities for associative hatches. There is no support for associative hatches by *ezdxf*, you have to do it all by yourself. (read/write) - **set\_vertices(vertices: Iterable\[Sequence\[float\]\], is\_closed: bool = True) -\> None** Set new *vertices* as new polyline path, a vertex has to be a (x, y) or a (x, y, bulge)-tuple. - **clear() -\> None** Removes all vertices and all handles to associated DXF objects (*source\_boundary\_objects*). - **class ezdxf.entities.EdgePath** Boundary path build by edges. There are four different edge types: *LineEdge*, *ArcEdge*, *EllipseEdge* of *SplineEdge*. Make sure there are no gaps between edges and the edge path must be closed to be recognized as path. AutoCAD is very picky in this regard. *Ezdxf* performs no checks on gaps between the edges and does not prevent creating open loops. **NOTE:** *ArcEdge* and *EllipseEdge* are ALWAYS represented in counter-clockwise orientation, even if an clockwise oriented edge is required to build a closed loop. To add a clockwise oriented curve swap start- and end angles and set the *ccw* flag to *False* and *ezdxf* will export a correct clockwise orientated curve. - **type** Path type as *BoundaryPathType.EDGE* enum - **path\_type\_flags** (bit coded flags) | | | | --- | --- | | 0 | default | | 1 | external | | 16 | outermost | see *PolylinePath.path\_type\_flags* - **edges** List of boundary edges of type *LineEdge*, *ArcEdge*, *EllipseEdge* of *SplineEdge* - **source\_boundary\_objects** Required for associative hatches, list of handles to the associated DXF entities. - **clear() -\> None** Delete all edges. - **add\_line(start: *UVec*, end: *UVec*) -\> LineEdge** Add a *LineEdge* from *start* to *end*. - **Parameters** - • **start** – start point of line, (x, y)-tuple - • **end** – end point of line, (x, y)-tuple - **add\_arc(center: *UVec*, radius: float = 1.0, start\_angle: float = 0.0, end\_angle: float = 360.0, ccw: bool = True) -\> ArcEdge** Add an *ArcEdge*. **Adding Clockwise Oriented Arcs:** Clockwise oriented *ArcEdge* objects are sometimes necessary to build closed loops, but the *ArcEdge* objects are always represented in counter-clockwise orientation. To add a clockwise oriented *ArcEdge* you have to swap the start- and end angle and set the *ccw* flag to **False**, e.g. to add a clockwise oriented *ArcEdge* from 180 to 90 degree, add the *ArcEdge* in counter-clockwise orientation with swapped angles: ``` edge_path.add_arc(center, radius, start_angle=90, end_angle=180, ccw=False) ``` - **Parameters** - • **center** – center point of arc, (x, y)-tuple - • **radius** – radius of circle - • **start\_angle** – start angle of arc in degrees (*end\_angle* for a clockwise oriented arc) - • **end\_angle** – end angle of arc in degrees (*start\_angle* for a clockwise oriented arc) - • **ccw** – **True** for counter-clockwise **False** for clockwise orientation - **add\_ellipse(center: *UVec*, major\_axis: *UVec* = (1.0, 0.0), ratio: float = 1.0, start\_angle: float = 0.0, end\_angle: float = 360.0, ccw: bool = True) -\> EllipseEdge** Add an *EllipseEdge*. **Adding Clockwise Oriented Ellipses:** Clockwise oriented *EllipseEdge* objects are sometimes necessary to build closed loops, but the *EllipseEdge* objects are always represented in counter-clockwise orientation. To add a clockwise oriented *EllipseEdge* you have to swap the start- and end angle and set the *ccw* flag to **False**, e.g. to add a clockwise oriented *EllipseEdge* from 180 to 90 degree, add the *EllipseEdge* in counter-clockwise orientation with swapped angles: ``` edge_path.add_ellipse(center, major_axis, ratio, start_angle=90, end_angle=180, ccw=False) ``` - **Parameters** - • **center** – center point of ellipse, (x, y)-tuple - • **major\_axis** – vector of major axis as (x, y)-tuple - • **ratio** – ratio of minor axis to major axis as float - • **start\_angle** – start angle of ellipse in degrees (*end\_angle* for a clockwise oriented ellipse) - • **end\_angle** – end angle of ellipse in degrees (*start\_angle* for a clockwise oriented ellipse) - • **ccw** – **True** for counter-clockwise **False** for clockwise orientation - **add\_spline(fit\_points: Iterable\[*UVec*\] \| None = None, control\_points: Iterable\[*UVec*\] \| None = None, knot\_values: Iterable\[float\] \| None = None, weights: Iterable\[float\] \| None = None, degree: int = 3, periodic: int = 0, start\_tangent: *UVec* \| None = None, end\_tangent: *UVec* \| None = None) -\> SplineEdge** Add a *SplineEdge*. - **Parameters** - • **fit\_points** – points through which the spline must go, at least 3 fit points are required. list of (x, y)-tuples - • **control\_points** – affects the shape of the spline, mandatory and AutoCAD crashes on invalid data. list of (x, y)-tuples - • **knot\_values** – (knot vector) mandatory and AutoCAD crashes on invalid data. list of floats; *ezdxf* provides two tool functions to calculate valid knot values: *ezdxf.math.uniform\_knot\_vector()*, *ezdxf.math.open\_uniform\_knot\_vector()* (default if **None**) - • **weights** – weight of control point, not mandatory, list of floats. - • **degree** – degree of spline (int) - • **periodic** – 1 for periodic spline, 0 for none periodic spline - • **start\_tangent** – start\_tangent as 2d vector, optional - • **end\_tangent** – end\_tangent as 2d vector, optional **WARNING:** Unlike for the spline entity AutoCAD does not calculate the necessary *knot\_values* for the spline edge itself. On the contrary, if the *knot\_values* in the spline edge are missing or invalid AutoCAD **crashes**. - **close\_gaps(len\_tol: float) -\> None** Insert line-edges between the existing edges if the gap between these edges are bigger than *len\_tol*. Added in version 1.4. - **class ezdxf.entities.EdgeType** - **LINE** - **ARC** - **ELLIPSE** - **SPLINE** - **class ezdxf.entities.LineEdge** Straight boundary edge. - **type** Edge type as *EdgeType.LINE* enum - **start** Start point as (x, y)-tuple. (read/write) - **end** End point as (x, y)-tuple. (read/write) - **class ezdxf.entities.ArcEdge** Arc as boundary edge in counter-clockwise orientation, see *EdgePath.add\_arc()*. - **type** Edge type as *EdgeType.ARC* enum - **center** Center point of arc as (x, y)-tuple. (read/write) - **radius** Arc radius as float. (read/write) - **start\_angle** Arc start angle in counter-clockwise orientation in degrees. (read/write) - **end\_angle** Arc end angle in counter-clockwise orientation in degrees. (read/write) - **ccw** **True** for counter clockwise arc else **False**. (read/write) - **class ezdxf.entities.EllipseEdge** Elliptic arc as boundary edge in counter-clockwise orientation, see *EdgePath.add\_ellipse()*. - **type** Edge type as *EdgeType.ELLIPSE* enum - **major\_axis\_vector** Ellipse major axis vector as (x, y)-tuple. (read/write) - **minor\_axis\_length** Ellipse minor axis length as float. (read/write) - **radius** Ellipse radius as float. (read/write) - **start\_angle** Ellipse start angle in counter-clockwise orientation in degrees. (read/write) - **end\_angle** Ellipse end angle in counter-clockwise orientation in degrees. (read/write) - **ccw** **True** for counter clockwise ellipse else **False**. (read/write) - **class ezdxf.entities.SplineEdge** Spline as boundary edge. - **type** Edge type as *EdgeType.SPLINE* enum - **degree** Spline degree as int. (read/write) - **rational** 1 for rational spline else 0. (read/write) - **periodic** 1 for periodic spline else 0. (read/write) - **knot\_values** List of knot values as floats. (read/write) - **control\_points** List of control points as (x, y)-tuples. (read/write) - **fit\_points** List of fit points as (x, y)-tuples. (read/write) - **weights** List of weights (of control points) as floats. (read/write) - **start\_tangent** Spline start tangent (vector) as (x, y)-tuple. (read/write) - **end\_tangent** Spline end tangent (vector) as (x, y)-tuple. (read/write) ### Hatch Pattern Definition Classes - **class ezdxf.entities.Pattern** - **lines** List of pattern definition lines (read/write). see *PatternLine* - **add\_line(angle: float = 0, base\_point: *UVec* = (0, 0), offset: *UVec* = (0, 0), dash\_length\_items: Iterable\[float\] \| None = None) -\> None** Create a new pattern definition line and add the line to the *Pattern.lines* attribute. - **clear() -\> None** Delete all pattern definition lines. - **scale(factor: float = 1, angle: float = 0) -\> None** Scale and rotate pattern. Be careful, this changes the base pattern definition, maybe better use *Hatch.set\_pattern\_scale()* or *Hatch.set\_pattern\_angle()*. - **Parameters** - • **factor** – scaling factor - • **angle** – rotation angle in degrees - **class ezdxf.entities.PatternLine** Represents a pattern definition line, use factory function *Pattern.add\_line()* to create new pattern definition lines. - **angle** Line angle in degrees. (read/write) - **base\_point** Base point as (x, y)-tuple. (read/write) - **offset** Offset as (x, y)-tuple. (read/write) - **dash\_length\_items** List of dash length items (item \> 0 is line, \< 0 is gap, 0.0 = dot). (read/write) ### Hatch Gradient Fill Class - **class ezdxf.entities.Gradient** - **color1** First rgb color as (r, g, b)-tuple, rgb values in range 0 to 255. (read/write) - **color2** Second rgb color as (r, g, b)-tuple, rgb values in range 0 to 255. (read/write) - **one\_color** If *one\_color* is 1 - the hatch is filled with a smooth transition between *color1* and a specified *tint* of *color1*. (read/write) - **rotation** Gradient rotation in degrees. (read/write) - **centered** Specifies a symmetrical gradient configuration. If this option is not selected, the gradient fill is shifted up and to the left, creating the illusion of a light source to the left of the object. (read/write) - **tint** Specifies the tint (*color1* mixed with white) of a color to be used for a gradient fill of one color. (read/write) **SEE ALSO:** *Tutorial for Hatch Pattern Definition* ### Helix The HELIX entity (*DXF Reference*). The helix curve is represented by a cubic B-spline curve, therefore the HELIX entity is also derived from the SPLINE entity. **SEE ALSO:** - • *Wikipedia* article about the helix shape | | | | --- | --- | | Subclass of | *ezdxf.entities.Spline* | | DXF type | **'HELIX'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_helix()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.Helix** All points in *WCS* as (x, y, z) tuples - **dxf.axis\_base\_point** The base point of the helix axis (Vec3). - **dxf.start\_point** The starting point of the helix curve (Vec3). This also defines the base radius as the distance from the start point to the axis base point. - **dxf.axis\_vector** Defines the direction of the helix axis (Vec3). - **dxf.radius** Defines the top radius of the helix (float). - **dxf.turn\_height** Defines the pitch (height if one helix turn) of the helix (float). - **dxf.turns** The count of helix turns (float). - **dxf.handedness** Helix orientation (int). | | | | --- | --- | | 0 | clock wise (left handed) | | 1 | counter clockwise (right handed) | - **dxf.constrain** | | | | --- | --- | | 0 | constrain turn height (pitch) | | 1 | constrain count of turns | | 2 | constrain total height | ### Image The IMAGE entity (*DXF Reference*) represents a raster image, the image file itself is not embedded into the DXF file, it is always a separated file. The IMAGE entity is like a block reference, it can be used to add the image multiple times at different locations with different scale and rotation angles. Every IMAGE entity requires an image definition, see entity *ImageDef*. *Ezdxf* creates only images in the xy-plan, it’s possible to place images in 3D space, therefore the *Image.dxf.u\_pixel* and the *Image.dxf.v\_pixel* vectors has to be set accordingly. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'IMAGE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_image()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Image** - **dxf.insert** Insertion point, lower left corner of the image (3D Point in *WCS*). - **dxf.u\_pixel** U-vector of a single pixel as (x, y, z) tuple. This vector points along the visual bottom of the image, starting at the insertion point. - **dxf.v\_pixel** V-vector of a single pixel as (x, y, z) tuple. This vector points along the visual left side of the image, starting at the insertion point. - **dxf.image\_size** Image size in pixels as (x, y) tuple - **dxf.image\_def\_handle** Handle to the image definition entity, see *ImageDef* - **dxf.flags** | | | | | --- | --- | --- | | **Image.SHOW\_IMAGE** | 1 | Show image | | **Image.SHOW\_WHEN\_NOT\_ALIGNED** | 2 | Show image when not aligned with screen | | **Image.USE\_CLIPPING\_BOUNDARY** | 4 | Use clipping boundary | | **Image.USE\_TRANSPARENCY** | 8 | Transparency is on | - **dxf.clipping** Clipping state: | | | | --- | --- | | 0 | clipping off | | 1 | clipping on | - **dxf.brightness** Brightness value in the range \[0, 100\], default is 50 - **dxf.contrast** Contrast value in the range \[0, 100\], default is 50 - **dxf.fade** Fade value in the range \[0, 100\], default is 0 - **dxf.clipping\_boundary\_type** | | | | --- | --- | | 1 | Rectangular | | 2 | Polygonal | - **dxf.count\_boundary\_points** Number of clip boundary vertices, this attribute is maintained by *ezdxf*. - **dxf.clip\_mode** | | | | --- | --- | | 0 | Outside | | 1 | Inside | requires DXF R2010 or newer - **boundary\_path** Returns the boundray path in raw form in pixel coordinates. A list of vertices as pixel coordinates, Two vertices describe a rectangle, lower left corner is (-0.5, -0.5) and upper right corner is (ImageSizeX-0.5, ImageSizeY-0.5), more than two vertices is a polygon as clipping path. All vertices as pixel coordinates. (read/write) - **image\_def** Returns the associated IMAGEDEF entity, see *ImageDef*. - **reset\_boundary\_path() -\> None** Reset boundary path to the default rectangle \[(-0.5, -0.5), (ImageSizeX-0.5, ImageSizeY-0.5)\]. - **set\_boundary\_path(vertices: Iterable\[*UVec*\]) -\> None** Set boundary path to *vertices*. Two vertices describe a rectangle (lower left and upper right corner), more than two vertices is a polygon as clipping path. - **pixel\_boundary\_path() -\> list\[*Vec2*\]** Returns the boundary path as closed loop in pixel coordinates. Resolves the simple form of two vertices as a rectangle. The image coordinate system has an inverted y-axis and the top-left corner is (0, 0). Changed in version 1.2.0: renamed from **boundray\_path\_ocs()** - **boundary\_path\_wcs() -\> list\[*Vec3*\]** Returns the boundary/clipping path in WCS coordinates. It’s recommended to acquire the clipping path as *Path* object by the *make\_path()* function: ``` from ezdxf.path import make_path image = ... # get image entity clipping_path = make_path(image) ``` - **transform(m: *Matrix44*) -\> Self** Transform IMAGE entity by transformation matrix *m* inplace. ### Leader The LEADER entity (*DXF Reference*) represents a pointer line, made up of one or more vertices (or spline fit points) and an arrowhead. The label or other content to which the *Leader* is attached is stored as a separate entity, and is not part of the *Leader* itself. The LEADER entity uses parts of the styling infrastructure of the DIMENSION entity. By default a *Leader* without any annotation is created. For creating more fancy leaders and annotations see the documentation provided by Autodesk or *Demystifying DXF: LEADER and MULTILEADER implementation notes* . | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'LEADER'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_leader()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.Leader** - **dxf.dimstyle** Name of **Dimstyle** as string. - **dxf.has\_arrowhead** | | | | --- | --- | | 0 | Disabled | | 1 | Enabled | - **dxf.path\_type** Leader path type: | | | | --- | --- | | 0 | Straight line segments | | 1 | Spline | - **dxf.annotation\_type** | | | | --- | --- | | 0 | Created with text annotation | | 1 | Created with tolerance annotation | | 2 | Created with block reference annotation | | 3 | Created without any annotation (default) | - **dxf.hookline\_direction** Hook line direction flag: | | | | --- | --- | | 0 | Hookline (or end of tangent for a splined leader) is the opposite direction from the horizontal vector | | 1 | Hookline (or end of tangent for a splined leader) is the same direction as horizontal vector (see **has\_hook\_line**) | - **dxf.has\_hookline** | | | | --- | --- | | 0 | No hookline | | 1 | Has a hookline | - **dxf.text\_height** Text annotation height in drawing units. - **dxf.text\_width** Text annotation width. - **dxf.block\_color** Color to use if leader’s DIMCLRD = BYBLOCK - **dxf.annotation\_handle** Hard reference (handle) to associated annotation (*MText*, **Tolerance**, or *Insert* entity) - **dxf.normal\_vector** Extrusion vector? default is (0, 0, 1). - **.dxf.horizontal\_direction** *Horizontal* direction for leader, default is (1, 0, 0). - **dxf.leader\_offset\_block\_ref** Offset of last leader vertex from block reference insertion point, default is (0, 0, 0). - **dxf.leader\_offset\_annotation\_placement** Offset of last leader vertex from annotation placement point, default (0, 0, 0). - **vertices** List of *Vec3* objects, representing the vertices of the leader (3D Point in *WCS*). - **set\_vertices(vertices: Iterable\[*UVec*\])** Set vertices of the leader, vertices is an iterable of (x, y \[,z\]) tuples or *Vec3*. - **transform(m: *Matrix44*) -\> *Leader*** Transform LEADER entity by transformation matrix *m* inplace. - **virtual\_entities() -\> Iterator\[DXFGraphic\]** Yields the DXF primitives the LEADER entity is build up as virtual entities. These entities are located at the original location, but are not stored in the entity database, have no handle and are not assigned to any layout. - **explode(target\_layout: *BaseLayout* \| None = None) -\> *EntityQuery*** Explode parts of the LEADER entity as DXF primitives into target layout, if target layout is **None**, the target layout is the layout of the LEADER entity. This method destroys the source entity. Returns an *EntityQuery* container referencing all DXF primitives. - **Parameters** **target\_layout** – target layout for the created DXF primitives, **None** for the same layout as the source entity. ### Line The LINE entity (*DXF Reference*) is a 3D line defined by the DXF attributes **dxf.start** and **dxf.end**. The LINE entity has *WCS* coordinates. **SEE ALSO:** - • *Tutorial for Simple DXF Entities*, section *Line* - • *ezdxf.math.ConstructionRay* - • *ezdxf.math.ConstructionLine* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'LINE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_line()* | | Inherited DXF Attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Line** - **dxf.start** start point of line (2D/3D Point in *WCS*) - **dxf.end** end point of line (2D/3D Point in *WCS*) - **dxf.thickness** Line thickness in 3D space in direction **extrusion**, default value is 0. This value should not be confused with the *lineweight* value. - **dxf.extrusion** extrusion vector, default value is (0, 0, 1) - **transform(m: *Matrix44*) -\> Line** Transform the LINE entity by transformation matrix *m* inplace. - **translate(dx: float, dy: float, dz: float) -\> Line** Optimized LINE translation about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis. ### LWPolyline The LWPOLYLINE entity (Lightweight POLYLINE, *DXF Reference*) is defined as a single graphic entity, which differs from the old-style *Polyline* entity, which is defined as a group of sub-entities. *LWPolyline* display faster (in AutoCAD) and consume less disk space, it is a planar element, therefore all points are located in the *OCS* as (x, y)-tuples (*LWPolyline.dxf.elevation* is the z-axis value). | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'LWPOLYLINE'** | | factory function | *add\_lwpolyline()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | Bulge value The bulge value is used to create arc shaped line segments for *Polyline* and *LWPolyline* entities. The arc starts at the vertex which includes the bulge value and ends at the following vertex. The bulge value defines the ratio of the arc sagitta (versine) to half line segment length, a bulge value of 1 defines a semicircle. The sign of the bulge value defines the side of the bulge: - • positive value (\> 0): bulge is right of line (counter clockwise) - • negative value (\< 0): bulge is left of line (clockwise) - • 0 = no bulge \[image\] Start- and end width The start width and end width values defines the width in drawing units for the following line segment. To use the default width value for a line segment set value to 0. Width and bulge values at last point The width and bulge values of the last point has only a meaning if the polyline is closed, and they apply to the last line segment from the last to the first point. **SEE ALSO:** *Tutorial for LWPolyline* and *Bulge Related Functions* ### User Defined Point Format Codes | | | | --- | --- | | Code | Point Component | | x | x-coordinate | | y | y-coordinate | | s | start width | | e | end width | | b | bulge value | | v | (x, y \[, z\]) as tuple | - **class ezdxf.entities.LWPolyline** - **dxf.elevation** *OCS* z-axis value for all polyline points, default=0 - **dxf.flags** Constants defined in *ezdxf.lldxf.const*: | | | | | --- | --- | --- | | dxf.flags | Value | Description | | LWPOLYLINE\_CLOSED | 1 | polyline is closed | | LWPOLYLINE\_PLINEGEN | 128 | linetype is generated across the points | - **dxf.const\_width** Constant line width (float), default value is 0. - **dxf.count** Count of polyline points (read only), same as **len(polyline)** - **property closed: bool** Get/set closed state of polyline. A closed polyline has a connection segment from the last vertex to the first vertex. - **property is\_closed: bool** Get closed state of LWPOLYLINE. Compatibility interface to *Polyline* - **close(state: bool = True) -\> None** Set closed state of LWPOLYLINE. Compatibility interface to *Polyline* - **property has\_arc: bool** Returns **True** if LWPOLYLINE has an arc segment. - **property has\_width: bool** Returns **True** if LWPOLYLINE has any segment with width attributes or the DXF attribute const\_width is not 0. - **\_\_len\_\_() -\> int** Returns count of polyline points. - **\_\_getitem\_\_(index: int) -\> Tuple\[float, float, float, float, float\]** Returns point at position *index* as (x, y, start\_width, end\_width, bulge) tuple. start\_width, end\_width and bulge is 0 if not present, supports extended slicing. Point format is fixed as “xyseb”. All coordinates in *OCS*. - **\_\_setitem\_\_(index: int, value: Sequence\[float\]) -\> None** Set point at position *index* as (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuple. If start\_width or end\_width is 0 or left off the default width value is used. If the bulge value is left off, bulge is 0 by default (straight line). Does NOT support extend slicing. Point format is fixed as “xyseb”. All coordinates in *OCS*. - **Parameters** - • **index** – point index - • **value** – point value as (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuple - **\_\_delitem\_\_(index: int) -\> None** Delete point at position *index*, supports extended slicing. - **\_\_iter\_\_() -\> Iterator\[Tuple\[float, float, float, float, float\]\]** Returns iterable of tuples (x, y, start\_width, end\_width, bulge). - **vertices() -\> Iterator\[tuple\[float, float\]\]** Returns iterable of all polyline points as (x, y) tuples in *OCS* (*dxf.elevation* is the z-axis value). - **vertices\_in\_wcs() -\> Iterator\[*Vec3*\]** Returns iterable of all polyline points as Vec3(x, y, z) in *WCS*. - **append(point: Sequence\[float\], format: str = DEFAULT\_FORMAT) -\> None** Append *point* to polyline, *format* specifies a user defined point format. All coordinates in *OCS*. - **Parameters** - • **point** – (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuple - • **format** – format string, default is “xyseb”, see: *format codes* - **append\_points(points: Iterable\[Sequence\[float\]\], format: str = DEFAULT\_FORMAT) -\> None** Append new *points* to polyline, *format* specifies a user defined point format. All coordinates in *OCS*. - **Parameters** - • **points** – iterable of point, point is (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuple - • **format** – format string, default is “xyseb”, see: *format codes* - **insert(pos: int, point: Sequence\[float\], format: str = DEFAULT\_FORMAT) -\> None** Insert new point in front of positions *pos*, *format* specifies a user defined point format. All coordinates in *OCS*. - **Parameters** - • **pos** – insert position - • **point** – point data - • **format** – format string, default is “xyseb”, see: *format codes* - **clear() -\> None** Remove all points. - **get\_points(format: str = DEFAULT\_FORMAT) -\> list\[Sequence\[float\]\]** Returns all points as list of tuples, format specifies a user defined point format. All points in *OCS* as (x, y) tuples (*dxf.elevation* is the z-axis value). - **Parameters** **format** – format string, default is “xyseb”, see *format codes* - **set\_points(points: Iterable\[Sequence\[float\]\], format: str = DEFAULT\_FORMAT) -\> None** Remove all points and append new *points*. All coordinates in *OCS*. - **Parameters** - • **points** – iterable of point, point is (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuple - • **format** – format string, default is “xyseb”, see *format codes* - **points(format: str = DEFAULT\_FORMAT) -\> Iterator\[list\[Sequence\[float\]\]\]** Context manager for polyline points. Returns a standard Python list of points, according to the format string. All coordinates in *OCS*. - **Parameters** **format** – format string, see *format codes* - **transform(m: *Matrix44*) -\> LWPolyline** Transform the LWPOLYLINE entity by transformation matrix *m* inplace. A non-uniform scaling is not supported if the entity contains circular arc segments (bulges). - **Parameters** **m** – transformation *Matrix44* - **Raises** **NonUniformScalingError** – for non-uniform scaling of entity containing\ circular arc segments (bulges) - **virtual\_entities() -\> Iterator\[*Line* \| *Arc*\]** Yields the graphical representation of LWPOLYLINE as virtual DXF primitives (LINE or ARC). These virtual entities are located at the original location, but are not stored in the entity database, have no handle and are not assigned to any layout. - **explode(target\_layout: *BaseLayout* \| None = None) -\> *EntityQuery*** Explode the LWPOLYLINE entity as DXF primitives (LINE or ARC) into the target layout, if the target layout is **None**, the target layout is the layout of the source entity. This method destroys the source entity. Returns an *EntityQuery* container referencing all DXF primitives. - **Parameters** **target\_layout** – target layout for the DXF primitives, **None** for same layout as the source entity. ### MLine The MLINE entity (*DXF Reference*). | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'MLINE'** | | factory function | *add\_mline()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.MLine** - **dxf.style\_name** *MLineStyle* name stored in **Drawing.mline\_styles** dictionary, use *set\_style()* to change the MLINESTYLE and update geometry accordingly. - **dxf.style\_handle** Handle of *MLineStyle*, use *set\_style()* to change the MLINESTYLE and update geometry accordingly. - **dxf.scale\_factor** MLINE scaling factor, use method *set\_scale\_factor()* to change the scaling factor and update geometry accordingly. - **dxf.justification** Justification defines the location of the MLINE in relation to the reference line, use method *set\_justification()* to change the justification and update geometry accordingly. Constants defined in *ezdxf.lldxf.const*: | | | | --- | --- | | dxf.justification | Value | | MLINE\_TOP | 0 | | MLINE\_ZERO | 1 | | MLINE\_BOTTOM | 2 | | MLINE\_RIGHT (alias) | 0 | | MLINE\_CENTER (alias) | 1 | | MLINE\_LEFT (alias) | 2 | - **dxf.flags** Use method *close()* and the properties *start\_caps* and *end\_caps* to change these flags. Constants defined in *ezdxf.lldxf.const*: | | | | --- | --- | | dxf.flags | Value | | MLINE\_HAS\_VERTEX | 1 | | MLINE\_CLOSED | 2 | | MLINE\_SUPPRESS\_START\_CAPS | 4 | | MLINE\_SUPPRESS\_END\_CAPS | 8 | - **dxf.start\_location** Start location of the reference line. (read only) - **dxf.count** Count of MLINE vertices. (read only) - **dxf.style\_element\_count** Count of elements in *MLineStyle* definition. (read only) - **dxf.extrusion** Normal vector of the entity plane, but MLINE is not an OCS entity, all vertices of the reference line are WCS! (read only) - **vertices** MLINE vertices as *MLineVertex* objects, stored in a regular Python list. - **property style: MLineStyle \| None** Get associated MLINESTYLE. - **set\_style(name: str) -\> None** Set MLINESTYLE by name and update geometry accordingly. The MLINESTYLE definition must exist. - **set\_scale\_factor(value: float) -\> None** Set the scale factor and update geometry accordingly. - **set\_justification(value: int) -\> None** Set MLINE justification and update geometry accordingly. See *dxf.justification* for valid settings. - **property is\_closed: bool** Returns **True** if MLINE is closed. Compatibility interface to *Polyline* - **close(state: bool = True) -\> None** Get/set closed state of MLINE and update geometry accordingly. Compatibility interface to *Polyline* - **property start\_caps: bool** Get/Set start caps state. **True** to enable start caps and **False** tu suppress start caps. - **property end\_caps: bool** Get/Set end caps state. **True** to enable end caps and **False** tu suppress start caps. - **\_\_len\_\_()** Count of MLINE vertices. - **start\_location() -\> *Vec3*** Returns the start location of the reference line. Callback function for *dxf.start\_location*. - **get\_locations() -\> list\[*Vec3*\]** Returns the vertices of the reference line. - **extend(vertices: Iterable\[*UVec*\]) -\> None** Append multiple vertices to the reference line. It is possible to work with 3D vertices, but all vertices have to be in the same plane and the normal vector of this plan is stored as extrusion vector in the MLINE entity. - **clear() -\> None** Remove all MLINE vertices. - **update\_geometry() -\> None** Regenerate the MLINE geometry based on current settings. - **generate\_geometry(vertices: list\[*Vec3*\]) -\> None** Regenerate the MLINE geometry for new reference line defined by *vertices*. - **transform(m: *Matrix44*) -\> Self** Transform MLINE entity by transformation matrix *m* inplace. - **virtual\_entities() -\> Iterator\[DXFGraphic\]** Yields virtual DXF primitives of the MLINE entity as LINE, ARC and HATCH entities. These entities are located at the original positions, but are not stored in the entity database, have no handle and are not assigned to any layout. - **explode(target\_layout: *BaseLayout* \| None = None) -\> *EntityQuery*** Explode the MLINE entity as LINE, ARC and HATCH entities into target layout, if target layout is **None**, the target layout is the layout of the MLINE. This method destroys the source entity. Returns an *EntityQuery* container referencing all DXF primitives. - **Parameters** **target\_layout** – target layout for DXF primitives, **None** for same layout as source entity. - **class ezdxf.entities.MLineVertex** - **location** Reference line vertex location. - **line\_direction** Reference line direction. - **miter\_direction** - **line\_params** The line parameterization is a list of float values. The list may contain zero or more items. The first value (miter-offset) is the distance from the vertex *location* along the *miter\_direction* vector to the point where the line element’s path intersects the miter vector. The next value (line-start-offset) is the distance along the *line\_direction* from the miter/line path intersection point to the actual start of the line element. The next value (dash-length) is the distance from the start of the line element (dash) to the first break (gap) in the line element. The successive values continue to list the start and stop points of the line element in this segment of the mline. - **fill\_params** The fill parameterization is also a list of float values. Similar to the line parameterization, it describes the parameterization of the fill area for this mline segment. The values are interpreted identically to the line parameters and when taken as a whole for all line elements in the mline segment, they define the boundary of the fill area for the mline segment. - **class ezdxf.entities.MLineStyle** The *MLineStyle* stores the style properties for the MLINE entity. - **dxf.name** - **dxf.description** - **dxf.flags** - **dxf.fill\_color** *AutoCAD Color Index (ACI)* value of the fill color - **dxf.start\_angle** - **dxf.end\_angle** - **elements** *MLineStyleElements* object - **update\_all()** Update all MLINE entities using this MLINESTYLE. The update is required if elements were added or removed or the offset of any element was changed. - **class ezdxf.entities.mline.MLineStyleElements** - **elements** List of *MLineStyleElement* objects, one for each line element. - **MLineStyleElements.\_\_len\_\_()** - **MLineStyleElements.\_\_getitem\_\_(item)** - **MLineStyleElements.append(offset: float, color: int = 0, linetype: str = 'BYLAYER') -\> None** Append a new line element. - **Parameters** - • **offset** – normal offset from the reference line: if justification is **MLINE\_ZERO**, positive values are above and negative values are below the reference line. - • **color** – *AutoCAD Color Index (ACI)* value - • **linetype** – linetype name - **class ezdxf.entities.mline.MLineStyleElement** Named tuple to store properties of a line element. - **offset** Normal offset from the reference line: if justification is **MLINE\_ZERO**, positive values are above and negative values are below the reference line. - **color** *AutoCAD Color Index (ACI)* value - **linetype** Linetype name ### Mesh The MESH entity (*DXF Reference*) is a 3D surface in *WCS* build up from vertices and faces similar to the *Polyface* entity. All vertices in *WCS* as (x, y, z) tuples | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'MESH'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_mesh()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | **SEE ALSO:** *Tutorial for Mesh* and helper classes: *MeshBuilder*, *MeshVertexMerger* - **class ezdxf.entities.Mesh** - **dxf.version** - **dxf.blend\_crease** 0 = off, 1 = on - **dxf.subdivision\_levels** 0 for no smoothing else integer greater than 0. - **vertices** Vertices as list like *VertexArray*. (read/write) - **edges** Edges as list like *TagArray*. (read/write) - **faces** Faces as list like *TagList*. (read/write) - **creases** Creases as **array.array**. (read/write) - **edit\_data() -\> Iterator\[MeshData\]** Context manager for various mesh data, returns a *MeshData* instance. Despite that vertices, edge and faces are accessible as packed data types, the usage of *MeshData* by context manager *edit\_data()* is still recommended. - **transform(m: *Matrix44*) -\> Mesh** Transform the MESH entity by transformation matrix *m* inplace. ### MeshData - **class ezdxf.entities.MeshData** - **vertices** A standard Python list with (x, y, z) tuples (read/write) - **faces** A standard Python list with (v1, v2, v3,…) tuples (read/write) Each face consist of a list of vertex indices (= index in *vertices*). - **edges** A Python list with (v1, v2) tuples (read/write). This list represents the edges to which the *edge\_crease\_values* values will be applied. Each edge consist of exact two vertex indices (= index in *vertices*). - **edge\_crease\_values** A Python list of float values, one value for each edge. (read/write) - **add\_face(vertices: Iterable\[*UVec*\]) -\> Sequence\[int\]** Add a face by a list of vertices. - **add\_edge\_crease(v1: int, v2: int, crease: float)** Add an edge crease value, the edge is defined by the vertex indices *v1* and *v2*. The crease value defines the amount of subdivision that will be applied to this edge. A crease value of the subdivision level prevents the edge from deformation and a value of 0.0 means no protection from subdividing. - **optimize()** Reduce vertex count by merging coincident vertices. ### MPolygon The MPOLYGON entity is not a core DXF entity and is not supported by all CAD applications and DXF libraries. The *MPolygon* class is very similar to the *Hatch* class with small differences in the supported features and DXF attributes. The boundary paths of the MPOLYGON are visible and use the graphical DXF attributes of the main entity like **dxf.color**, **dxf.linetype** and so on. The solid filling is only visible if the attribute **dxf.solid\_fill** is 1, the color of the solid fill is defined by **dxf.fill\_color** as *AutoCAD Color Index (ACI)*. The MPOLYGON supports *ezdxf.entities.Gradient* settings like HATCH for DXF R2004 and newer. This feature is used by method *MPolygon.set\_solid\_fill()* to set a solid RGB fill color as linear gradient, this disables pattern fill automatically. The MPOLYGON does not support associated source path entities, because the MPOLYGON also represents the boundary paths as visible graphical objects. Hatch patterns are supported, but the hatch style tag is not supported, the default hatch style is **ezdxf.const.HATCH\_STYLE\_NESTED** and the style flags of the boundary paths are ignored. Background color for pattern fillings is supported, set background color by property *MPolygon.bgcolor* as RGB tuple. **NOTE:** Background RGB fill color for solid fill and pattern fill is set differently! Autodesk products do support polyline paths including bulges. An example for edge paths as boundary paths is not available or edge paths are not supported. *Ezdxf* does **not** export MPOLYGON entities including edge paths! The *BoundaryPaths.edge\_to\_polyline\_paths()* method converts all edge paths to simple polyline paths with approximated curves, this conversion has to be done explicit. **SEE ALSO:** For more information see the *ezdxf.entities.Hatch* documentation. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'MPOLYGON'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_mpolygon()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.MPolygon** - **dxf.pattern\_name** Pattern name as string - **dxf.solid\_fill** | | | | --- | --- | | 1 | solid fill, better use: *MPolygon.set\_solid\_fill()* | | 0 | pattern fill, better use: *MPolygon.set\_pattern\_fill()* | (search AutoCAD help for more information) - **dxf.pattern\_type** | | | | --- | --- | | 0 | user | | 1 | predefined | | 2 | custom | - **dxf.pattern\_angle** Actual pattern angle in degrees (float). Changing this value does not rotate the pattern, use *set\_pattern\_angle()* for this task. - **dxf.pattern\_scale** Actual pattern scaling factor (float). Changing this value does not scale the pattern use *set\_pattern\_scale()* for this task. - **dxf.pattern\_double** 1 = double pattern size else 0. (int) - **dxf.elevation** Z value represents the elevation height of the *OCS*. (float) - **paths** *BoundaryPaths* object. - **pattern** *Pattern* object. - **gradient** *Gradient* object. - **property has\_solid\_fill: bool** **True** if entity has a solid fill. (read only) - **property has\_pattern\_fill: bool** **True** if entity has a pattern fill. (read only) - **property has\_gradient\_data: bool** **True** if entity has a gradient fill. A hatch with gradient fill has also a solid fill. (read only) - **property bgcolor: *RGB* \| None** Set pattern fill background color as (r, g, b)-tuple, rgb values in the range \[0, 255\] (read/write/del) usage: ``` r, g, b = entity.bgcolor # get pattern fill background color entity.bgcolor = (10, 20, 30) # set pattern fill background color del entity.bgcolor # delete pattern fill background color ``` - **set\_pattern\_definition(lines: Sequence, factor: float = 1, angle: float = 0) -\> None** Setup pattern definition by a list of definition lines and the definition line is a 4-tuple (angle, base\_point, offset, dash\_length\_items). The pattern definition should be designed for a pattern scale factor of 1 and a pattern rotation angle of 0. - • angle: line angle in degrees - • base-point: (x, y) tuple - • offset: (dx, dy) tuple - • dash\_length\_items: list of dash items (item \> 0 is a line, item \< 0 is a gap and item == 0.0 is a point) - **Parameters** - • **lines** – list of definition lines - • **factor** – pattern scale factor - • **angle** – rotation angle in degrees - **set\_pattern\_scale(scale: float) -\> None** Sets the pattern scale factor and scales the pattern definition. The method always starts from the original base scale, the **set\_pattern\_scale(1)** call resets the pattern scale to the original appearance as defined by the pattern designer, but only if the pattern attribute *dxf.pattern\_scale* represents the actual scale, it cannot restore the original pattern scale from the pattern definition itself. - **Parameters** **scale** – pattern scale factor - **set\_pattern\_angle(angle: float) -\> None** Sets the pattern rotation angle and rotates the pattern definition. The method always starts from the original base rotation of 0, the **set\_pattern\_angle(0)** call resets the pattern rotation angle to the original appearance as defined by the pattern designer, but only if the pattern attribute *dxf.pattern\_angle* represents the actual pattern rotation, it cannot restore the original rotation angle from the pattern definition itself. - **Parameters** **angle** – pattern rotation angle in degrees - **set\_solid\_fill(color: int = 7, style: int = 1, rgb: *RGB* \| None = None)** Set *MPolygon* to solid fill mode and removes all gradient and pattern fill related data. - **Parameters** - • **color** – *AutoCAD Color Index (ACI)*, (0 = BYBLOCK; 256 = BYLAYER) - • **style** – hatch style is not supported by MPOLYGON, just for symmetry to HATCH - • **rgb** – true color value as (r, g, b)-tuple - has higher priority than *color*. True color support requires DXF R2004+ - **set\_pattern\_fill(name: str, color: int = 7, angle: float = 0.0, scale: float = 1.0, double: int = 0, style: int = 1, pattern\_type: int = 1, definition=None) -\> None** Sets the pattern fill mode and removes all gradient related data. The pattern definition should be designed for a scale factor 1 and a rotation angle of 0 degrees. The predefined hatch pattern like “ANSI33” are scaled according to the HEADER variable $MEASUREMENT for ISO measurement (m, cm, … ), or imperial units (in, ft, …), this replicates the behavior of BricsCAD. - **Parameters** - • **name** – pattern name as string - • **color** – pattern color as *AutoCAD Color Index (ACI)* - • **angle** – pattern rotation angle in degrees - • **scale** – pattern scale factor - • **double** – double size flag - • **style** – hatch style (0 = normal; 1 = outer; 2 = ignore) - • **pattern\_type** – pattern type (0 = user-defined; 1 = predefined; 2 = custom) - • **definition** – list of definition lines and a definition line is a 4-tuple \[angle, base\_point, offset, dash\_length\_items\], see *set\_pattern\_definition()* - **set\_gradient(color1: *RGB* = RGB(0, 0, 0), color2: *RGB* = RGB(255, 255, 255), rotation: float = 0.0, centered: float = 0.0, one\_color: int = 0, tint: float = 0.0, name: str = 'LINEAR') -\> None** Sets the gradient fill mode and removes all pattern fill related data, requires DXF R2004 or newer. A gradient filled hatch is also a solid filled hatch. Valid gradient type names are: - • “LINEAR” - • “CYLINDER” - • “INVCYLINDER” - • “SPHERICAL” - • “INVSPHERICAL” - • “HEMISPHERICAL” - • “INVHEMISPHERICAL” - • “CURVED” - • “INVCURVED” - **Parameters** - • **color1** – (r, g, b)-tuple for first color, rgb values as int in the range \[0, 255\] - • **color2** – (r, g, b)-tuple for second color, rgb values as int in the range \[0, 255\] - • **rotation** – rotation angle in degrees - • **centered** – determines whether the gradient is centered or not - • **one\_color** – 1 for gradient from *color1* to tinted *color1* - • **tint** – determines the tinted target *color1* for a one color gradient. (valid range 0.0 to 1.0) - • **name** – name of gradient type, default “LINEAR” - **transform(m: *Matrix44*) -\> DXFPolygon** Transform entity by transformation matrix *m* inplace. ### MText The MTEXT entity (*DXF Reference*) fits a multiline text in a specified width but can extend vertically to an indefinite length. You can format individual words or characters within the *MText*. **SEE ALSO:** *Tutorial for MText and MTextEditor* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'MTEXT'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_mtext()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.MText** - **dxf.insert** Insertion point (3D Point in *OCS*) - **dxf.char\_height** Initial text height (float); default=1.0 - **dxf.width** Reference text width (float), forces text wrapping at given width. - **dxf.attachment\_point** Constants defined in *ezdxf.lldxf.const*: | | | | --- | --- | | MText.dxf.attachment\_point | Value | | MTEXT\_TOP\_LEFT | 1 | | MTEXT\_TOP\_CENTER | 2 | | MTEXT\_TOP\_RIGHT | 3 | | MTEXT\_MIDDLE\_LEFT | 4 | | MTEXT\_MIDDLE\_CENTER | 5 | | MTEXT\_MIDDLE\_RIGHT | 6 | | MTEXT\_BOTTOM\_LEFT | 7 | | MTEXT\_BOTTOM\_CENTER | 8 | | MTEXT\_BOTTOM\_RIGHT | 9 | - **dxf.flow\_direction** Constants defined in **ezdxf.const**: | | | | | --- | --- | --- | | MText.dxf.flow\_direction | Value | Description | | MTEXT\_LEFT\_TO\_RIGHT | 1 | left to right | | MTEXT\_TOP\_TO\_BOTTOM | 3 | top to bottom | | MTEXT\_BY\_STYLE | 5 | by style (the flow direction is inherited from the associated text style) | - **dxf.style** Text style (string); default is “STANDARD” - **dxf.text\_direction** X-axis direction vector in *WCS* (3D Point); default value is (1, 0, 0); if **dxf.rotation** and **dxf.text\_direction** are present, **dxf.text\_direction** wins. - **dxf.rotation** Text rotation in degrees (float); default is 0 - **dxf.line\_spacing\_style** Line spacing style (int), see table below - **dxf.line\_spacing\_factor** Percentage of default (3-on-5) line spacing to be applied. Valid values range from 0.25 to 4.00 (float). Constants defined in *ezdxf.lldxf.const*: | | | | | --- | --- | --- | | MText.dxf.line\_spacing\_style | Value | Description | | MTEXT\_AT\_LEAST | 1 | taller characters will override | | MTEXT\_EXACT | 2 | taller characters will not override | - **dxf.bg\_fill** Defines the background fill type. (DXF R2007) | | | | | --- | --- | --- | | MText.dxf.bg\_fill | Value | Description | | MTEXT\_BG\_OFF | 0 | no background color | | MTEXT\_BG\_COLOR | 1 | use specified color | | MTEXT\_BG\_WINDOW\_COLOR | 2 | use window color (?) | | MTEXT\_BG\_CANVAS\_COLOR | 3 | use canvas background color | - **dxf.box\_fill\_scale** Determines how much border there is around the text. (DXF R2007) Requires that the attributes *bg\_fill*, *bg\_fill\_color* are present otherwise AutoCAD complains. It’s recommended to use **set\_bg\_color()** - **dxf.bg\_fill\_color** Background fill color as *AutoCAD Color Index (ACI)* (DXF R2007) It’s recommended to use **set\_bg\_color()** - **dxf.bg\_fill\_true\_color** Background fill color as true color value (DXF R2007), also the **dxf.bg\_fill\_color** attribute must be present otherwise AutoCAD complains. It’s recommended to use **set\_bg\_color()** - **dxf.bg\_fill\_color\_name** Background fill color as name string (?) (DXF R2007), also the **dxf.bg\_fill\_color** attribute must be present otherwise AutoCAD complains. It’s recommended to use **set\_bg\_color()** - **dxf.transparency** Transparency of background fill color (DXF R2007), not supported by AutoCAD nor BricsCAD. - **text** MTEXT content as string (read/write). The line ending character **\\n** will be replaced by the MTEXT line ending **\\P** at DXF export, but **not** vice versa the **\\P** character by **\\n** at DXF file loading, therefore loaded MTEXT entities always use the **\\P** character for line endings. - **set\_location(insert: *UVec*, rotation: float \| None = None, attachment\_point: int \| None = None) -\> MText** Sets the attributes *dxf.insert*, *dxf.rotation* and *dxf.attachment\_point*, **None** for *dxf.rotation* or *dxf.attachment\_point* preserves the existing value. - **get\_rotation() -\> float** Returns the text rotation in degrees. - **set\_rotation(angle: float) -\> MText** Sets the attribute **rotation** to *angle* (in degrees) and deletes *dxf.text\_direction* if present. - **get\_text\_direction() -\> *Vec3*** Returns the horizontal text direction as *Vec3* object, even if only the text rotation is defined. - **set\_bg\_color(color: int \| str \| *RGB* \| None, scale: float = 1.5, text\_frame=False)** Sets the background color as *AutoCAD Color Index (ACI)* value, as name string or as (r, g, b) tuple. Use the special color name **canvas**, to set the background color to the canvas background color. Remove the background filling by setting argument *color* to **None**. - **Parameters** - • **color** – color as *AutoCAD Color Index (ACI)*, string, (r, g, b) tuple or **None** - • **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. - • **text\_frame** – draw a text frame in text color if **True** - **\_\_iadd\_\_(text: str) -\> MText** Append *text* to existing content (*text* attribute). - **append(text: str) -\> MText** Append *text* to existing content (*text* attribute). - **plain\_text(split=False, fast=True) -\> list\[str\] \| str** Returns the text content without inline formatting codes. The “fast” mode is accurate if the DXF content was created by reliable (and newer) CAD applications like AutoCAD or BricsCAD. The “accurate” mode is for some rare cases where the content was created by older CAD applications or unreliable DXF libraries and CAD applications. - **Parameters** - • **split** – split content text at line breaks if **True** and returns a list of strings without line endings - • **fast** – uses the “fast” mode to extract the plain MTEXT content if **True** or the “accurate” mode if set to **False** - **all\_columns\_plain\_text(split=False) -\> list\[str\] \| str** Returns the text content of all columns without inline formatting codes. - **Parameters** **split** – split content text at line breaks if **True** and returns a list of strings without line endings - **all\_columns\_raw\_content() -\> str** Returns the text content of all columns as a single string including the inline formatting codes. - **transform(m: *Matrix44*) -\> MText** Transform the MTEXT entity by transformation matrix *m* inplace. - **ucs() -\> *UCS*** Returns the *UCS* of the *MText* entity, defined by the insert location (origin), the text direction or rotation (x-axis) and the extrusion vector (z-axis). ### MText Inline Codes | | | | --- | --- | | Code | Description | | \\L | Start underline | | \\l | Stop underline | | \\O | Start overline | | \\o | Stop overline | | \\K | Start strike-through | | \\k | Stop strike-through | | \\P | New paragraph (new line) | | \\p | Paragraphs properties: indentation, alignment, tabulator stops | | \\X | Paragraph wrap on the dimension line (only in dimensions) | | \\Q | Slanting (oblique) text by angle - e.g. \\Q30; | | \\H | Text height - e.g. relative \\H3x; absolut \\H3; | | \\W | Text width - e.g. relative \\W0.8x; absolut \\W0.8; | | \\T | Tracking, character spacing - e.g. relative \\T0.5x; absolut \\T2; | | \\F | Font selection e.g. \\Fgdt;o - GDT-tolerance | | \\S | Stacking, fractions e.g. \\SA^ B; space after “^” is required to avoid caret decoding, \\SX/Y; \\S1#4; | | \\A | Alignment \\A0; = bottom \\A1; = center \\A2; = top | | \\C | Color change \\C1; = red \\C2; = yellow \\C3; = green \\C4; = cyan \\C5; = blue \\C6; = magenta \\C7; = white | | \\~ | Non breaking space | | {} | Braces - define the text area influenced by the code, codes and braces can be nested up to 8 levels deep | | \\ | Escape character - e.g. \\{ = “{” | ### Convenient constants defined in MTextEditor: | | | | --- | --- | | Constant | Description | | UNDERLINE\_START | start underline text | | UNDERLINE\_STOP | stop underline text | | OVERSTRIKE\_START | start overline | | OVERSTRIKE\_STOP | stop overline | | STRIKE\_START | start strike through | | STRIKE\_STOP | stop strike through | | GROUP\_START | start of group | | GROUP\_END | end of group | | NEW\_LINE | start in new line | | NBSP | none breaking space | ### MultiLeader The MULTILEADER entity (*DXF Reference*) represents one or more leaders, made up of one or more vertices (or spline fit points) and an arrowhead. In contrast to the *Leader* entity the text- or block content is part of the MULTILEADER entity. AutoCAD, BricsCAD and maybe other CAD applications do accept “MLEADER” as type string but they always create entities with “MULTILEADER” as type string. Because of the complexity of the MULTILEADER entity, the usage of factory methods to create new entities by special builder classes is recommended: - • *add\_multileader\_mtext()* returns a new *MultiLeaderMTextBuilder* instance - • *add\_multileader\_block()* returns a new *MultiLeaderBlockBuilder* instance The visual design is based on an associated *MLeaderStyle*, but almost all attributes are also stored in the MULTILEADER entity itself. The attribute *MultiLeader.dxf.property\_override\_flags* should indicate which MLEADERSTYLE attributes are overridden by MULTILEADER attributes, but these flags do not always reflect the state of overridden attributes. The *ezdxf* MULTILEADER renderer uses always the attributes from the MULTILEADER entity and ignores the override flags. All vertices are WCS coordinates, even those for BLOCK entities which are OCS coordinates for regular usage. **SEE ALSO:** - • *ezdxf.entities.MLeaderStyle* - • *ezdxf.render.MultiLeaderBuilder* - • *Tutorial for MultiLeader* - • *MULTILEADER Internals* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'MULTILEADER'** | | Factory functions | *ezdxf.layouts.BaseLayout.add\_multileader\_mtext()* *ezdxf.layouts.BaseLayout.add\_multileader\_block()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.MultiLeader** - **dxf.arrow\_head\_handle** handle of the arrow head, see also *ezdxf.render.arrows* module, “closed filled” arrow if not set - **dxf.arrow\_head\_size** arrow head size in drawing units - **dxf.block\_color** block color as *raw-color* value, default is BY\_BLOCK\_RAW\_VALUE - **dxf.block\_connection\_type** | | | | --- | --- | | 0 | center extents | | 1 | insertion point | - **dxf.block\_record\_handle** handle to block record of the BLOCK content - **dxf.block\_rotation** BLOCK rotation in radians - **dxf.block\_scale\_vector** **Vec3** object which stores the scaling factors for the x-, y- and z-axis - **dxf.content\_type** | | | | --- | --- | | 0 | none | | 1 | BLOCK | | 2 | MTEXT | | 3 | TOLERANCE | - **dxf.dogleg\_length** dogleg length in drawing units - **dxf.has\_dogleg** - **dxf.has\_landing** - **dxf.has\_text\_frame** - **dxf.is\_annotative** - **dxf.is\_text\_direction\_negative** - **dxf.leader\_extend\_to\_text** - **dxf.leader\_line\_color** leader line color as *raw-color* value - **dxf.leader\_linetype\_handle** handle of the leader linetype, “CONTINUOUS” if not set - **dxf.leader\_lineweight** - **dxf.leader\_type** | | | | --- | --- | | 0 | invisible | | 1 | straight line leader | | 2 | spline leader | - **dxf.property\_override\_flags** Each bit shows if the MLEADERSTYLE is overridden by the value in the MULTILEADER entity, but this is not always the case for all values, it seems to be save to always use the value from the MULTILEADER entity. - **dxf.scale** overall scaling factor - **dxf.style\_handle** handle to the associated MLEADERSTYLE object - **dxf.text\_IPE\_align** unknown meaning - **dxf.text\_alignment\_type** unknown meaning - its not the MTEXT attachment point! - **dxf.text\_angle\_type** | | | | --- | --- | | 0 | text angle is equal to last leader line segment angle | | 1 | text is horizontal | | 2 | text angle is equal to last leader line segment angle, but potentially rotated by 180 degrees so the right side is up for readability. | - **dxf.text\_attachment\_direction** defines whether the leaders attach to the left & right of the content BLOCK/MTEXT or attach to the top & bottom: | | | | --- | --- | | 0 | horizontal - left & right of content | | 1 | vertical - top & bottom of content | - **dxf.text\_attachment\_point** MTEXT attachment point | | | | --- | --- | | 1 | top left | | 2 | top center | | 3 | top right | - **dxf.text\_bottom\_attachment\_type** | | | | --- | --- | | 9 | center | | 10 | overline and center | - **dxf.text\_color** MTEXT color as *raw-color* value - **dxf.text\_left\_attachment\_type** | | | | --- | --- | | 0 | top of top MTEXT line | | 1 | middle of top MTEXT line | | 2 | middle of whole MTEXT | | 3 | middle of bottom MTEXT line | | 4 | bottom of bottom MTEXT line | | 5 | bottom of bottom MTEXT line & underline bottom MTEXT line | | 6 | bottom of top MTEXT line & underline top MTEXT line | | 7 | bottom of top MTEXT line | | 8 | bottom of top MTEXT line & underline all MTEXT lines | - **dxf.text\_right\_attachment\_type** | | | | --- | --- | | 0 | top of top MTEXT line | | 1 | middle of top MTEXT line | | 2 | middle of whole MTEXT | | 3 | middle of bottom MTEXT line | | 4 | bottom of bottom MTEXT line | | 5 | bottom of bottom MTEXT line & underline bottom MTEXT line | | 6 | bottom of top MTEXT line & underline top MTEXT line | | 7 | bottom of top MTEXT line | | 8 | bottom of top MTEXT line & underline all MTEXT lines | - **dxf.text\_style\_handle** handle of the MTEXT text style, “Standard” if not set - **dxf.text\_top\_attachment\_type** | | | | --- | --- | | 9 | center | | 10 | overline and center | - **dxf.version** always 2? - **context** *MLeaderContext* instance - **arrow\_heads** list of *ArrowHeadData* - **block\_attribs** list of *AttribData* - **property has\_mtext\_content: bool** **True** if MULTILEADER has MTEXT content. - **get\_mtext\_content() -\> str** Get MTEXT content as string, return “” if MULTILEADER has BLOCK content. - **set\_mtext\_content(text: str)** Set MTEXT content as string, does nothing if MULTILEADER has BLOCK content. - **property has\_block\_content: bool** **True** if MULTILEADER has BLOCK content. - **get\_block\_content() -\> dict\[str, str\]** Get BLOCK attributes as dictionary of (tag, value) pairs. Returns an empty dictionary if MULTILEADER has MTEXT content. - **set\_block\_content(content: dict\[str, str\])** Set BLOCK attributes by a dictionary of (tag, value) pairs. Does nothing if MULTILEADER has MTEXT content. - **virtual\_entities() -\> Iterator\[DXFGraphic\]** Yields the graphical representation of MULTILEADER as virtual DXF primitives. These entities are located at the original location, but are not stored in the entity database, have no handle and are not assigned to any layout. - **explode(target\_layout: *BaseLayout* \| None = None) -\> *EntityQuery*** Explode MULTILEADER as DXF primitives into target layout, if target layout is **None**, the target layout is the layout of the source entity. Returns an *EntityQuery* container with all DXF primitives. - **Parameters** **target\_layout** – target layout for the DXF primitives, **None** for same layout as the source entity. - **transform(m: *Matrix44*) -\> MultiLeader** Transform the MULTILEADER entity by transformation matrix *m* inplace. Non-uniform scaling is not supported. - **Parameters** **m** – transformation *Matrix44* - **Raises** **NonUniformScalingError** – for non-uniform scaling - **class ezdxf.entities.MLeaderContext** - **leaders** list of *LeaderData* objects - **scale** redundant data: *MultiLeader.dxf.scale* - **base\_point** insert location as **Vec3** of the MTEXT or the BLOCK entity? - **char\_height** MTEXT char height, already scaled - **arrow\_head\_size** redundant data: *MultiLeader.dxf.arrow\_head\_size* - **landing\_gap\_size** - **left\_attachment** redundant data: *MultiLeader.dxf.text\_left\_attachment\_type* - **right\_attachment** redundant data: *MultiLeader.dxf.text\_right\_attachment\_type* - **text\_align\_type** redundant data: *MultiLeader.dxf.text\_attachment\_point* - **attachment\_type** BLOCK alignment? | | | | --- | --- | | 0 | content extents | | 1 | insertion point | - **mtext** instance of *MTextData* if content is MTEXT otherwise **None** - **block** instance of *BlockData* if content is BLOCK otherwise **None** - **plane\_origin** **Vec3** - **plane\_x\_axis** **Vec3** - **plane\_y\_axis** **Vec3** - **plane\_normal\_reversed** the plan normal is x-axis “cross” y-axis (right-hand-rule), this flag indicates to invert this plan normal - **top\_attachment** redundant data: *MultiLeader.dxf.text\_top\_attachment\_type* - **bottom\_attachment** redundant data: *MultiLeader.dxf.text\_bottom\_attachment\_type* - **class ezdxf.entities.LeaderData** - **lines** list of *LeaderLine* - **has\_last\_leader\_line** unknown meaning - **has\_dogleg\_vector** - **last\_leader\_point** WCS point as **Vec3** - **dogleg\_vector** WCS direction as **Vec3** - **dogleg\_length** redundant data: *MultiLeader.dxf.dogleg\_length* - **index** leader index? - **attachment\_direction** redundant data: *MultiLeader.dxf.text\_attachment\_direction* - **breaks** list of break vertices as **Vec3** objects - **class ezdxf.entities.LeaderLine** - **vertices** list of WCS coordinates as **Vec3** - **breaks** mixed list of mixed integer indices and break coordinates or **None** leader lines without breaks in it - **index** leader line index? - **color** leader line color override, ignore override value if BY\_BLOCK\_RAW\_VALUE - **class ezdxf.entities.ArrowHeadData** - **index** arrow head index? - **handle** handle to arrow head block - **class ezdxf.entities.AttribData** - **handle** handle to **Attdef** entity in the BLOCK definition - **index** unknown meaning - **width** text width factor? - **text** *Attrib* content - **class ezdxf.entities.MTextData** stores the content and attributes of the MTEXT entity - **default\_content** content as string - **extrusion** extrusion vector of the MTEXT entity but MTEXT is not an OCS entity! - **style\_handle** redundant data: *MultiLeader.dxf.text\_style\_handle* - **insert** insert location in WCS coordinates, same as *MLeaderContext.base\_point*? - **text\_direction** “horizontal” text direction vector in WCS - **rotation** rotation angle in radians (!) around the extrusion vector, calculated as it were an OCS entity - **width** unscaled column width - **defined\_height** unscaled defined column height - **line\_spacing\_factor** see *MText.dxf.line\_spacing\_factor* - **line\_spacing\_style** see *MText.dxf.line\_spacing\_style* - **color** redundant data: *MultiLeader.dxf.text\_color* - **alignment** redundant data: *MultiLeader.dxf.text\_attachment\_point* - **flow\_direction** | | | | --- | --- | | 1 | horizontal | | 3 | vertical | | 6 | by text style | - **bg\_color** background color as *raw-color* value - **bg\_scale\_factor** see *MText.dxf.box\_fill\_scale* - **bg\_transparency** background transparency value - **use\_window\_bg\_color** - **has\_bg\_fill** - **column\_type** unknown meaning - most likely: | | | | --- | --- | | 0 | none | | 1 | static | | 2 | dynamic | - **use\_auto\_height** - **column\_width** unscaled column width, redundant data *width* - **column\_gutter\_width** unscaled column gutter width - **column\_flow\_reversed** - **column\_sizes** list of unscaled columns heights for dynamic column with manual heights - **use\_word\_break** - **class ezdxf.entities.BlockData** stores the attributes for the *Insert* entity - **block\_record\_handle** redundant data: *MultiLeader.dxf.block\_record\_handle* - **extrusion** extrusion vector in WCS - **insert** insertion location in WCS as **Vec3**, same as *MLeaderContext.base\_point*? - **scale** redundant data: *MultiLeader.dxf.block\_scale\_vector* - **rotation** redundant data: *MultiLeader.dxf.block\_rotation* - **color** redundant data: *MultiLeader.dxf.block\_color* ### Point The POINT entity (*DXF Reference*) represents a dimensionless point in *WCS*. The POINT styling is a global setting, stored as header variable *$PDMODE*, this also means **all** POINT entities in a DXF document have the same styling: | | | | --- | --- | | 0 | center dot (.) | | 1 | none ( ) | | 2 | cross (+) | | 3 | x-cross (x) | | 4 | tick (‘) | Combined with these bit values | | | | --- | --- | | 32 | circle | | 64 | Square | e.g. circle + square + center dot = 32 + 64 + 0 = 96 \[image\] The size of the points is defined by the header variable *$PDSIZE*: | | | | --- | --- | | 0 | 5% of draw area height | | \<0 | Specifies a percentage of the viewport size | | \>0 | Specifies an absolute size | **SEE ALSO:** - • *Tutorial for Simple DXF Entities*, section *Point* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'POINT'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_point()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Point** - **dxf.location** Location of the point (2D/3D Point in *WCS*) - **dxf.angle** Angle in degrees of the x-axis for the UCS in effect when POINT was drawn (float); used when PDMODE is nonzero. - **transform(m: *Matrix44*) -\> Point** Transform the POINT entity by transformation matrix *m* inplace. - **translate(dx: float, dy: float, dz: float) -\> Point** Optimized POINT translation about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis. - **virtual\_entities(pdsize: float = 1, pdmode: int = 0) -\> Iterator\[DXFGraphic\]** Yields the graphical representation of POINT as virtual DXF primitives (LINE and CIRCLE). The dimensionless point is rendered as zero-length line! Check for this condition: ``` e.dxftype() == 'LINE' and e.dxf.start.isclose(e.dxf.end) ``` if the rendering engine can’t handle zero-length lines. - **Parameters** - • **pdsize** – point size in drawing units - • **pdmode** – point styling mode ### Polyline The POLYLINE entity (*POLYLINE DXF Reference*) is very complex, it’s used to build 2D/3D polylines, 3D meshes and 3D polyfaces. For every type exists a different wrapper class but they all have the same DXF type “POLYLINE”. Detect the actual POLYLINE type by the method *Polyline.get\_mode()*. POLYLINE types returned by *Polyline.get\_mode()*: - • **'AcDb2dPolyline'** for 2D *Polyline* - • **'AcDb3dPolyline'** for 3D *Polyline* - • **'AcDbPolygonMesh'** for *Polymesh* - • **'AcDbPolyFaceMesh'** for *Polyface* For 2D entities all vertices in *OCS*. For 3D entities all vertices in *WCS*. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'POLYLINE'** | | 2D factory function | *ezdxf.layouts.BaseLayout.add\_polyline2d()* | | 3D factory function | *ezdxf.layouts.BaseLayout.add\_polyline3d()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Polyline** The *Vertex* entities are stored in the Python list *Polyline.vertices*. The VERTEX entities can be retrieved and deleted by direct access to the *Polyline.vertices* attribute: ``` # delete first and second vertex del polyline.vertices[:2] ``` - **dxf.elevation** Elevation point, the X and Y values are always 0, and the Z value is the polyline elevation (3D Point). - **dxf.flags** Constants defined in *ezdxf.lldxf.const*: | | | | | --- | --- | --- | | *Polyline.dxf.flags* | Value | Description | | POLYLINE\_CLOSED | 1 | This is a closed Polyline (or a polygon mesh closed in the M direction) | | POLYLINE\_MESH\_CLOSED\_M\_DIRECTION | 1 | equals POLYLINE\_CLOSED | | POLYLINE\_CURVE\_FIT\_VERTICES\_ADDED | 2 | Curve-fit vertices have been added | | POLYLINE\_SPLINE\_FIT\_VERTICES\_ADDED | 4 | Spline-fit vertices have been added | | POLYLINE\_3D\_POLYLINE | 8 | This is a 3D Polyline | | POLYLINE\_3D\_POLYMESH | 16 | This is a 3D polygon mesh | | POLYLINE\_MESH\_CLOSED\_N\_DIRECTION | 32 | The polygon mesh is closed in the N direction | | POLYLINE\_POLYFACE\_MESH | 64 | This Polyline is a polyface mesh | | POLYLINE\_GENERATE\_LINETYPE\_PATTERN | 128 | The linetype pattern is generated continuously around the vertices of this Polyline | - **dxf.default\_start\_width** Default line start width (float); default is 0 - **dxf.default\_end\_width** Default line end width (float); default is 0 - **dxf.m\_count** Polymesh M vertex count (int); default is 1 - **dxf.n\_count** Polymesh N vertex count (int); default is 1 - **dxf.m\_smooth\_density** Smooth surface M density (int); default is 0 - **dxf.n\_smooth\_density** Smooth surface N density (int); default is 0 - **dxf.smooth\_type** Curves and smooth surface type (int); default is 0, see table below Constants for **smooth\_type** defined in *ezdxf.lldxf.const*: | | | | | --- | --- | --- | | *Polyline.dxf.smooth\_type* | Value | Description | | POLYMESH\_NO\_SMOOTH | 0 | no smooth surface fitted | | POLYMESH\_QUADRATIC\_BSPLINE | 5 | quadratic B-spline surface | | POLYMESH\_CUBIC\_BSPLINE | 6 | cubic B-spline surface | | POLYMESH\_BEZIER\_SURFACE | 8 | Bezier surface | - **vertices** List of *Vertex* entities. - **is\_2d\_polyline** **True** if POLYLINE is a 2D polyline. - **is\_3d\_polyline** **True** if POLYLINE is a 3D polyline. - **is\_polygon\_mesh** **True** if POLYLINE is a polygon mesh, see *Polymesh* - **is\_poly\_face\_mesh** **True** if POLYLINE is a poly face mesh, see *Polyface* - **is\_closed** **True** if POLYLINE is closed. - **is\_m\_closed** **True** if POLYLINE (as *Polymesh*) is closed in m direction. - **is\_n\_closed** **True** if POLYLINE (as *Polymesh*) is closed in n direction. - **has\_arc** Returns **True** if 2D POLYLINE has an arc segment. - **has\_width** Returns **True** if 2D POLYLINE has default width values or any segment with width attributes. - **get\_mode() -\> str** Returns POLYLINE type as string: - • “AcDb2dPolyline” - • “AcDb3dPolyline” - • “AcDbPolygonMesh” - • “AcDbPolyFaceMesh” - **m\_close(status=True) -\> None** Close POLYMESH in m direction if *status* is **True** (also closes POLYLINE), clears closed state if *status* is **False**. - **n\_close(status=True) -\> None** Close POLYMESH in n direction if *status* is **True**, clears closed state if *status* is **False**. - **close(m\_close=True, n\_close=False) -\> None** Set closed state of POLYMESH and POLYLINE in m direction and n direction. **True** set closed flag, **False** clears closed flag. - **\_\_len\_\_() -\> int** Returns count of *Vertex* entities. - **\_\_getitem\_\_(pos) -\> DXFVertex** Get *Vertex* entity at position *pos*, supports list-like slicing. - **points() -\> Iterator\[*Vec3*\]** Returns all polyline points in *OCS* or *WCS* coordinates as *Vec3*. These are the raw location coordinates stored in the *Vertex* entities. A separately stored elevation value will not be applied. The points of 2D polylines are *OCS* coordinates other polyline types return *WCS* coordinates. - **points\_in\_wcs() -\> Iterator\[*Vec3*\]** Returns all polyline points in *WCS* coordinates as *Vec3*. Added in version 1.4. - **append\_vertex(point: *UVec*, dxfattribs=None) -\> None** Append a single *Vertex* entity at location *point*. - **Parameters** - • **point** – as (x, y\[, z\]) tuple - • **dxfattribs** – dict of DXF attributes for *Vertex* class - **append\_vertices(points: Iterable\[*UVec*\], dxfattribs=None) -\> None** Append multiple *Vertex* entities at location *points*. - **Parameters** - • **points** – iterable of (x, y\[, z\]) tuples - • **dxfattribs** – dict of DXF attributes for the VERTEX objects - **append\_formatted\_vertices(points: Iterable\[Sequence\], format: str = 'xy', dxfattribs=None) -\> None** Append multiple *Vertex* entities at location *points*. - **Parameters** - • **points** – iterable of (x, y, \[start\_width, \[end\_width, \[bulge\]\]\]) tuple - • **format** – format string, default is “xy”, see: *User Defined Point Format Codes* - • **dxfattribs** – dict of DXF attributes for the VERTEX objects - **insert\_vertices(pos: int, points: Iterable\[*UVec*\], dxfattribs=None) -\> None** Insert vertices *points* into *Polyline.vertices* list at insertion location *pos* . - **Parameters** - • **pos** – insertion position of list *Polyline.vertices* - • **points** – list of (x, y\[, z\]) tuples - • **dxfattribs** – dict of DXF attributes for *Vertex* class - **transform(m: *Matrix44*) -\> Polyline** Transform the POLYLINE entity by transformation matrix *m* inplace. A non-uniform scaling is not supported if a 2D POLYLINE contains circular arc segments (bulges). - **Parameters** **m** – transformation *Matrix44* - **Raises** **NonUniformScalingError** – for non-uniform scaling of 2D POLYLINE\ containing circular arc segments (bulges) - **virtual\_entities() -\> Iterator\[*Line* \| *Arc* \| *Face3d*\]** Yields the graphical representation of POLYLINE as virtual DXF primitives (LINE, ARC or 3DFACE). These virtual entities are located at the original location, but are not stored in the entity database, have no handle and are not assigned to any layout. - **explode(target\_layout: *BaseLayout* \| None = None) -\> *EntityQuery*** Explode the POLYLINE entity as DXF primitives (LINE, ARC or 3DFACE) into the target layout, if the target layout is **None**, the target layout is the layout of the POLYLINE entity. Returns an *EntityQuery* container referencing all DXF primitives. - **Parameters** **target\_layout** – target layout for DXF primitives, **None** for same layout as source entity. ### Vertex A VERTEX (*VERTEX DXF Reference*) represents a polyline/mesh vertex. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'VERTEX'** | | Factory function | *Polyline.append\_vertex()* | | Factory function | **Polyline.extend()** | | Factory function | *Polyline.insert\_vertices()* | | Inherited DXF Attributes | *Common graphical DXF attributes* | - **class ezdxf.entities.Vertex** - **dxf.location** Vertex location (2D/3D Point *OCS* when 2D, *WCS* when 3D) - **dxf.start\_width** Line segment start width (float); default is 0 - **dxf.end\_width** Line segment end width (float); default is 0 - **dxf.bulge** *Bulge value* (float); default is 0. The bulge value is used to create arc shaped line segments. - **dxf.flags** Constants defined in *ezdxf.lldxf.const*: | | | | | --- | --- | --- | | Vertex.dxf.flags | Value | Description | | VTX\_EXTRA\_VERTEX\_CREATED | 1 | Extra vertex created by curve-fitting | | VTX\_CURVE\_FIT\_TANGENT | 2 | curve-fit tangent defined for this vertex. A curve-fit tangent direction of 0 may be omitted from the DXF output, but is significant if this bit is set. | | VTX\_SPLINE\_VERTEX\_CREATED | 8 | spline vertex created by spline-fitting | | VTX\_SPLINE\_FRAME\_CONTROL\_POINT | 16 | spline frame control point | | VTX\_3D\_POLYLINE\_VERTEX | 32 | 3D polyline vertex | | VTX\_3D\_POLYGON\_MESH\_VERTEX | 64 | 3D polygon mesh | | VTX\_3D\_POLYFACE\_MESH\_VERTEX | 128 | polyface mesh vertex | - **dxf.tangent** Curve fit tangent direction (float), used for 2D spline in DXF R12. - **dxf.vtx1** Index of 1st vertex, if used as face (feature for experts) - **dxf.vtx2** Index of 2nd vertex, if used as face (feature for experts) - **dxf.vtx3** Index of 3rd vertex, if used as face (feature for experts) - **dxf.vtx4** Index of 4th vertex, if used as face (feature for experts) - **is\_2d\_polyline\_vertex** - **is\_3d\_polyline\_vertex** - **is\_polygon\_mesh\_vertex** - **is\_poly\_face\_mesh\_vertex** - **is\_face\_record** - **format(format='xyz') -\> Sequence** Return formatted vertex components as tuple. Format codes: - • “x” = x-coordinate - • “y” = y-coordinate - • “z” = z-coordinate - • “s” = start width - • “e” = end width - • “b” = bulge value - • “v” = (x, y, z) as tuple - **Args:** format: format string, default is “xyz” ### Polymesh | | | | --- | --- | | Subclass of | *ezdxf.entities.Polyline* | | DXF type | **'POLYLINE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_polymesh()* | | Inherited DXF Attributes | *Common graphical DXF attributes* | - **class ezdxf.entities.Polymesh** A polymesh is a grid of **m\_count** by **n\_count** vertices, every vertex has its own (x, y, z) location. The *Polymesh* is a subclass of *Polyline*, the DXF type is also “POLYLINE”, the method **get\_mode()** returns “AcDbPolygonMesh”. - **get\_mesh\_vertex(pos: tuple\[int, int\]) -\> DXFVertex** Get location of a single mesh vertex. - **Parameters** **pos** – 0-based (row, col) tuple, position of mesh vertex - **set\_mesh\_vertex(pos: tuple\[int, int\], point: *UVec*, dxfattribs=None)** Set location and DXF attributes of a single mesh vertex. - **Parameters** - • **pos** – 0-based (row, col) tuple, position of mesh vertex - • **point** – (x, y, z) tuple, new 3D coordinates of the mesh vertex - • **dxfattribs** – dict of DXF attributes - **get\_mesh\_vertex\_cache() -\> MeshVertexCache** Get a *MeshVertexCache* object for this POLYMESH. The caching object provides fast access to the **location** attribute of mesh vertices. ### MeshVertexCache - **class ezdxf.entities.MeshVertexCache** Cache mesh vertices in a dict, keys are 0-based (row, col) tuples. Set vertex location: **cache\[row, col\] = (x, y, z)** Get vertex location: **x, y, z = cache\[row, col\]** - **vertices** Dict of mesh vertices, keys are 0-based (row, col) tuples. - **\_\_getitem\_\_(pos: tuple\[int, int\]) -\> *UVec*** Get mesh vertex location as (x, y, z)-tuple. - **Parameters** **pos** – 0-based (row, col)-tuple. - **\_\_setitem\_\_(pos: tuple\[int, int\], location: *UVec*) -\> None** Get mesh vertex location as (x, y, z)-tuple. - **Parameters** - • **pos** – 0-based (row, col)-tuple. - • **location** – (x, y, z)-tuple ### Polyface | | | | --- | --- | | Subclass of | *ezdxf.entities.Polyline* | | DXF type | **'POLYLINE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_polyface()* | | Inherited DXF Attributes | *Common graphical DXF attributes* | **SEE ALSO:** *Tutorial for Polyface* - **class ezdxf.entities.Polyface** A polyface consist of multiple 3D areas called faces, only faces with 3 or 4 vertices are supported. The *Polyface* is a subclass of *Polyline*, the DXF type is also “POLYLINE”, the *get\_mode()* returns “AcDbPolyFaceMesh”. - **append\_face(face: FaceType, dxfattribs=None) -\> None** Append a single face. A *face* is a sequence of (x, y, z) tuples. - **Parameters** - • **face** – sequence of (x, y, z) tuples - • **dxfattribs** – dict of DXF attributes for the VERTEX objects - **append\_faces(faces: Iterable\[FaceType\], dxfattribs=None) -\> None** Append multiple *faces*. *faces* is a list of single faces and a single face is a sequence of (x, y, z) tuples. - **Parameters** - • **faces** – iterable of sequences of (x, y, z) tuples - • **dxfattribs** – dict of DXF attributes for the VERTEX entity - **faces() -\> Iterator\[list\[DXFVertex\]\]** Iterable of all faces, a face is a tuple of vertices. - **Returns** list of \[vertex, vertex, vertex, \[vertex,\] face\_record\] - **optimize(precision: int = 6) -\> None** Rebuilds the *Polyface* by merging vertices with nearly same vertex locations. - **Parameters** **precision** – floating point precision for determining identical vertex locations ### Ray The RAY entity (*DXF Reference*) starts at **Ray.dxf.point** and continues to infinity (construction line). | | | | --- | --- | | Subclass of | *ezdxf.entities.XLine* | | DXF type | **'RAY'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_ray()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.Ray** - **dxf.start** Start point as (3D Point in *WCS*) - **dxf.unit\_vector** Unit direction vector as (3D Point in *WCS*) - **transform(m: *Matrix44*) -\> XLine** Transform the XLINE/RAY entity by transformation matrix *m* inplace. - **translate(dx: float, dy: float, dz: float) -\> XLine** Optimized XLINE/RAY translation about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis. ### Region REGION entity (*DXF Reference*) created by an ACIS geometry kernel provided by the *Spatial Corp.* **SEE ALSO:** *Ezdxf* has only very limited support for ACIS based entities, for more information see the FAQ: *How to add/edit ACIS based entities like 3DSOLID, REGION or SURFACE?* | | | | --- | --- | | Subclass of | *ezdxf.entities.Body* | | DXF type | **'REGION'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_region()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Region** Same attributes and methods as parent class *Body*. ### Shape The SHAPE entity (*DXF Reference*) is used like a block references, each SHAPE reference can be scaled and rotated individually. The SHAPE definitions are stored in external shape files (\*.SHX), and *ezdxf* can not load or create these shape files. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'SHAPE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_shape()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Shape** - **dxf.insert** Insertion location as (2D/3D Point in *WCS*) - **dxf.name** Shape name (str) - **dxf.size** Shape size (float) - **dxf.rotation** Rotation angle in degrees; default value is 0 - **dxf.xscale** Relative X scale factor (float); default value is 1 - **dxf.oblique** Oblique angle in degrees (float); default value is 0 - **transform(m: *Matrix44*) -\> *Shape*** Transform the SHAPE entity by transformation matrix *m* inplace. ### Solid The SOLID entity (*DXF Reference*) is a filled triangle or quadrilateral. Access vertices by name (**entity.dxf.vtx0 = (1.7, 2.3)**) or by index (**entity\[0\] = (1.7, 2.3)**). If only 3 vertices are provided the last (3rd) vertex will be repeated in the DXF file. The SOLID entity stores the vertices in an unusual way, the last two vertices are reversed: ``` msp.add_solid([(0, 0), (10, 0), (10, 10), (0, 10)]) ``` \[image\] Reverse the last two vertices to get the *expected* square: ``` msp.add_solid([(0, 0), (10, 0), (0, 10), (10, 10)]) ``` \[image\] **NOTE:** The quirky vertex order is preserved at the lowest access level because *ezdxf* is intended as a DXF file format interface and presents the content of the DXF document to the package user as natively as possible. The *Solid.vertices()* and *Solid.wcs\_vertices()* methods return the vertices in the *expected* (reversed) order. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'SOLID'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_solid()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Solid** - **dxf.vtx0** Location of 1. vertex (2D/3D Point in *OCS*) - **dxf.vtx1** Location of 2. vertex (2D/3D Point in *OCS*) - **dxf.vtx2** Location of 3. vertex (2D/3D Point in *OCS*) - **dxf.vtx3** Location of 4. vertex (2D/3D Point in *OCS*) - **transform(m: *Matrix44*) -\> Solid** Transform the SOLID/TRACE entity by transformation matrix *m* inplace. - **vertices(close: bool = False) -\> list\[*Vec3*\]** Returns OCS vertices in correct order, if argument *close* is **True**, last vertex == first vertex. Does **not** return the duplicated last vertex if the entity represents a triangle. - **wcs\_vertices(close: bool = False) -\> list\[*Vec3*\]** Returns WCS vertices in correct order, if argument *close* is **True**, last vertex == first vertex. Does **not** return the duplicated last vertex if the entity represents a triangle. ### Spline The SPLINE entity (*DXF Reference*) is a 3D curve, all coordinates have to be 3D coordinates even if the spline is just a 2D planar curve. The spline curve is defined by control points, knot values and weights. The control points establish the spline, the various types of knot vector determines the shape of the curve and the weights of rational splines define how strong a control point influences the shape. A SPLINE can be created just from fit points - knot values and weights are optional (tested with AutoCAD 2010). If you add additional data, be sure you know what you do, because invalid data may invalidate the whole DXF file. The function *ezdxf.math.fit\_points\_to\_cad\_cv()* calculates control vertices from given fit points. This control vertices define a cubic B-spline which matches visually the SPLINE entities created by BricsCAD and AutoCAD from fit points. **SEE ALSO:** - • *Wikipedia* article about B\_splines - • Department of Computer Science and Technology at the *Cambridge* University - • *Tutorial for Spline* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'SPLINE'** | | Factory function | see table below | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | ### Factory Functions | | | | --- | --- | | Basic spline entity | *add\_spline()* | | Spline control frame from fit points | *add\_spline\_control\_frame()* | | Open uniform spline | *add\_open\_spline()* | | Closed uniform spline | **add\_closed\_spline()** | | Open rational uniform spline | *add\_rational\_spline()* | | Closed rational uniform spline | **add\_closed\_rational\_spline()** | - **class ezdxf.entities.Spline** All points in *WCS* as (x, y, z) tuples - **dxf.degree** Degree of the spline curve (int). - **dxf.flags** Bit coded option flags, constants defined in *ezdxf.lldxf.const*: | | | | | --- | --- | --- | | dxf.flags | Value | Description | | CLOSED\_SPLINE | 1 | Spline is closed | | PERIODIC\_SPLINE | 2 | | | RATIONAL\_SPLINE | 4 | | | PLANAR\_SPLINE | 8 | | | LINEAR\_SPLINE | 16 | planar bit is also set | - **dxf.n\_knots** Count of knot values (int), automatically set by *ezdxf* (read only) - **dxf.n\_fit\_points** Count of fit points (int), automatically set by ezdxf (read only) - **dxf.n\_control\_points** Count of control points (int), automatically set by ezdxf (read only) - **dxf.knot\_tolerance** Knot tolerance (float); default is 1e-10 - **dxf.fit\_tolerance** Fit tolerance (float); default is 1e-10 - **dxf.control\_point\_tolerance** Control point tolerance (float); default is 1e-10 - **dxf.start\_tangent** Start tangent vector as 3D vector in *WCS* - **dxf.end\_tangent** End tangent vector as 3D vector in *WCS* - **closed** **True** if spline is closed. A closed spline has a connection from the last control point to the first control point. (read/write) - **control\_points** *VertexArray* of control points in *WCS*. - **fit\_points** *VertexArray* of fit points in *WCS*. - **knots** Knot values as **array.array('d')**. - **weights** Control point weights as **array.array('d')**. - **control\_point\_count() -\> int** Count of control points. - **fit\_point\_count() -\> int** Count of fit points. - **knot\_count() -\> int** Count of knot values. - **construction\_tool() -\> *BSpline*** Returns the construction tool *ezdxf.math.BSpline*. - **apply\_construction\_tool(s) -\> Spline** Apply SPLINE data from a *BSpline* construction tool or from a **geomdl.BSpline.Curve** object. - **flattening(distance: float, segments: int = 4) -\> Iterator\[*Vec3*\]** Adaptive recursive flattening. The argument *segments* is the minimum count of approximation segments between two knots, if the distance from the center of the approximation segment to the curve is bigger than *distance* the segment will be subdivided. - **Parameters** - • **distance** – maximum distance from the projected curve point onto the segment chord. - • **segments** – minimum segment count between two knots - **set\_open\_uniform(control\_points: Sequence\[*UVec*\], degree: int = 3) -\> None** Open B-spline with a uniform knot vector, start and end at your first and last control points. - **set\_uniform(control\_points: Sequence\[*UVec*\], degree: int = 3) -\> None** B-spline with a uniform knot vector, does NOT start and end at your first and last control points. - **set\_closed(control\_points: Sequence\[*UVec*\], degree=3) -\> None** Closed B-spline with a uniform knot vector, start and end at your first control point. - **set\_open\_rational(control\_points: Sequence\[*UVec*\], weights: Sequence\[float\], degree: int = 3) -\> None** Open rational B-spline with a uniform knot vector, start and end at your first and last control points, and has additional control possibilities by weighting each control point. - **set\_uniform\_rational(control\_points: Sequence\[*UVec*\], weights: Sequence\[float\], degree: int = 3) -\> None** Rational B-spline with a uniform knot vector, does NOT start and end at your first and last control points, and has additional control possibilities by weighting each control point. - **set\_closed\_rational(control\_points: Sequence\[*UVec*\], weights: Sequence\[float\], degree: int = 3) -\> None** Closed rational B-spline with a uniform knot vector, start and end at your first control point, and has additional control possibilities by weighting each control point. - **transform(m: *Matrix44*) -\> Spline** Transform the SPLINE entity by transformation matrix *m* inplace. - **classmethod from\_arc(entity: DXFGraphic) -\> Spline** Create a new SPLINE entity from a CIRCLE, ARC or ELLIPSE entity. The new SPLINE entity has no owner, no handle, is not stored in the entity database nor assigned to any layout! ### Surface SURFACE entity (*DXF Reference*) created by an ACIS geometry kernel provided by the *Spatial Corp.* **SEE ALSO:** *Ezdxf* has only very limited support for ACIS based entities, for more information see the FAQ: *How to add/edit ACIS based entities like 3DSOLID, REGION or SURFACE?* | | | | --- | --- | | Subclass of | *ezdxf.entities.Body* | | DXF type | **'SURFACE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_surface()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Surface** Same attributes and methods as parent class *Body*. - **dxf.u\_count** Number of U isolines. - **dxf.v\_count** Number of V2 isolines. ### ExtrudedSurface (*DXF Reference*) | | | | --- | --- | | Subclass of | *ezdxf.entities.Surface* | | DXF type | **'EXTRUDEDSURFACE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_extruded\_surface()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2007 (**'AC1021'**) | - **class ezdxf.entities.ExtrudedSurface** Same attributes and methods as parent class *Surface*. - **dxf.class\_id** - **dxf.sweep\_vector** - **dxf.draft\_angle** - **dxf.draft\_start\_distance** - **dxf.draft\_end\_distance** - **dxf.twist\_angle** - **dxf.scale\_factor** - **dxf.align\_angle** - **dxf.solid** - **dxf.sweep\_alignment\_flags** | | | | --- | --- | | 0 | No alignment | | 1 | Align sweep entity to path | | 2 | Translate sweep entity to path | | 3 | Translate path to sweep entity | - **dxf.align\_start** - **dxf.bank** - **dxf.base\_point\_set** - **dxf.sweep\_entity\_transform\_computed** - **dxf.path\_entity\_transform\_computed** - **dxf.reference\_vector\_for\_controlling\_twist** - **transformation\_matrix\_extruded\_entity** type: *Matrix44* - **sweep\_entity\_transformation\_matrix** type: *Matrix44* - **path\_entity\_transformation\_matrix** type: *Matrix44* ### LoftedSurface (*DXF Reference*) | | | | --- | --- | | Subclass of | *ezdxf.entities.Surface* | | DXF type | **'LOFTEDSURFACE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_lofted\_surface()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2007 (**'AC1021'**) | - **class ezdxf.entities.LoftedSurface** Same attributes and methods as parent class *Surface*. - **dxf.plane\_normal\_lofting\_type** - **dxf.start\_draft\_angle** - **dxf.end\_draft\_angle** - **dxf.start\_draft\_magnitude** - **dxf.end\_draft\_magnitude** - **dxf.arc\_length\_parameterization** - **dxf.no\_twist** - **dxf.align\_direction** - **dxf.simple\_surfaces** - **dxf.closed\_surfaces** - **dxf.solid** - **dxf.ruled\_surface** - **dxf.virtual\_guide** - **set\_transformation\_matrix\_lofted\_entity** type: *Matrix44* ### RevolvedSurface (*DXF Reference*) | | | | --- | --- | | Subclass of | *ezdxf.entities.Surface* | | DXF type | **'REVOLVEDSURFACE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_revolved\_surface()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2007 (**'AC1021'**) | - **class ezdxf.entities.RevolvedSurface** Same attributes and methods as parent class *Surface*. - **dxf.class\_id** - **dxf.axis\_point** - **dxf.axis\_vector** - **dxf.revolve\_angle** - **dxf.start\_angle** - **dxf.draft\_angle** - **dxf.start\_draft\_distance** - **dxf.end\_draft\_distance** - **dxf.twist\_angle** - **dxf.solid** - **dxf.close\_to\_axis** - **transformation\_matrix\_revolved\_entity** type: *Matrix44* ### SweptSurface (*DXF Reference*) | | | | --- | --- | | Subclass of | *ezdxf.entities.Surface* | | DXF type | **'SWEPTSURFACE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_swept\_surface()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2007 (**'AC1021'**) | - **class ezdxf.entities.SweptSurface** Same attributes and methods as parent class *Surface*. - **dxf.swept\_entity\_id** - **dxf.path\_entity\_id** - **dxf.draft\_angle** - **draft\_start\_distance** - **dxf.draft\_end\_distance** - **dxf.twist\_angle** - **dxf.scale\_factor** - **dxf.align\_angle** - **dxf.solid** - **dxf.sweep\_alignment** - **dxf.align\_start** - **dxf.bank** - **dxf.base\_point\_set** - **dxf.sweep\_entity\_transform\_computed** - **dxf.path\_entity\_transform\_computed** - **dxf.reference\_vector\_for\_controlling\_twist** - **transformation\_matrix\_sweep\_entity** type: *Matrix44* - **transformation\_matrix\_path\_entity()** type: *Matrix44* - **sweep\_entity\_transformation\_matrix()** type: *Matrix44* - **path\_entity\_transformation\_matrix()** type: *Matrix44* ### Text The TEXT entity (*DXF Reference*) represents a single line of text. The *style* attribute stores the associated *Textstyle* entity as string, which defines the basic font properties. The text size is stored as cap-height in the *height* attribute in drawing units. Text alignments are defined as enums of type *ezdxf.enums.TextEntityAlignment*. **SEE ALSO:** See the documentation for the *Textstyle* class to understand the limitations of text representation in the DXF format. *Tutorial for Text* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'TEXT'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_text()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Text** - **dxf.text** Text content as string. - **dxf.insert** First alignment point of text (2D/3D Point in *OCS*), relevant for the adjustments LEFT, ALIGNED and FIT. - **dxf.align\_point** The main alignment point of text (2D/3D Point in *OCS*), if the alignment is anything else than LEFT, or the second alignment point for the ALIGNED and FIT alignments. - **dxf.height** Text height in drawing units as float value, the default value is 1. - **dxf.rotation** Text rotation in degrees as float value, the default value is 0. - **dxf.oblique** Text oblique angle (slanting) in degrees as float value, the default value is 0 (straight vertical text). - **dxf.style** *Textstyle* name as case insensitive string, the default value is “Standard” - **dxf.width** Width scale factor as float value, the default value is 1. - **dxf.halign** Horizontal alignment flag as int value, use the *set\_placement()* and *get\_align\_enum()* methods to handle text alignment, the default value is 0. | | | | --- | --- | | 0 | Left | | 2 | Right | | 3 | Aligned (if vertical alignment = 0) | | 4 | Middle (if vertical alignment = 0) | | 5 | Fit (if vertical alignment = 0) | - **dxf.valign** Vertical alignment flag as int value, use the *set\_placement()* and *get\_align\_enum()* methods to handle text alignment, the default value is 0. | | | | --- | --- | | 0 | Baseline | | 1 | Bottom | | 2 | Middle | | 3 | Top | - **dxf.text\_generation\_flag** Text generation flags as int value, use the **is\_backward** and **is\_upside\_down** attributes to handle this flags. | | | | --- | --- | | 2 | text is backward (mirrored in X) | | 4 | text is upside down (mirrored in Y) | - **property is\_backward: bool** Get/set text generation flag BACKWARDS, for mirrored text along the x-axis. - **property is\_upside\_down: bool** Get/set text generation flag UPSIDE\_DOWN, for mirrored text along the y-axis. - **set\_placement(p1: *UVec*, p2: *UVec* \| None = None, align: *TextEntityAlignment* \| None = None) -\> Text** Set text alignment and location. The alignments **ALIGNED** and **FIT** are special, they require a second alignment point, the text is aligned on the virtual line between these two points and sits vertically at the baseline. - • **ALIGNED**: Text is stretched or compressed to fit exactly between *p1* and *p2* and the text height is also adjusted to preserve height/width ratio. - • **FIT**: Text is stretched or compressed to fit exactly between *p1* and *p2* but only the text width is adjusted, the text height is fixed by the *dxf.height* attribute. - • **MIDDLE**: also a special adjustment, centered text like **MIDDLE\_CENTER**, but vertically centred at the total height of the text. - **Parameters** - • **p1** – first alignment point as (x, y\[, z\]) - • **p2** – second alignment point as (x, y\[, z\]), required for **ALIGNED** and **FIT** else ignored - • **align** – new alignment as enum *TextEntityAlignment*, **None** to preserve the existing alignment. - **get\_placement() -\> tuple\[*TextEntityAlignment*, *Vec3*, *Vec3* \| None\]** Returns a tuple (*align*, *p1*, *p2*), *align* is the alignment enum **TextEntityAlignment**, *p1* is the alignment point, *p2* is only relevant if *align* is **ALIGNED** or **FIT**, otherwise it is **None**. - **get\_align\_enum() -\> *TextEntityAlignment*** Returns the current text alignment as *TextEntityAlignment*, see also *set\_placement()*. - **set\_align\_enum(align=TextEntityAlignment.LEFT) -\> Text** Just for experts: Sets the text alignment without setting the alignment points, set adjustment points attr:*dxf.insert* and *dxf.align\_point* manually. - **Parameters** **align** – *TextEntityAlignment* - **transform(m: *Matrix44*) -\> Text** Transform the TEXT entity by transformation matrix *m* inplace. - **translate(dx: float, dy: float, dz: float) -\> Text** Optimized TEXT/ATTRIB/ATTDEF translation about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis, returns *self*. - **plain\_text() -\> str** Returns text content without formatting codes. - **font\_name() -\> str** Returns the font name of the associated *Textstyle*. - **fit\_length() -\> float** Returns the text length for alignments **TextEntityAlignment.FIT** and **TextEntityAlignment.ALIGNED**, defined by the distance from the insertion point to the align point or 0 for all other alignments. ### Trace The TRACE entity (*DXF Reference*) is solid filled triangle or quadrilateral. Access vertices by name (**entity.dxf.vtx0 = (1.7, 2.3)**) or by index (**entity\[0\] = (1.7, 2.3)**). If only 3 vertices are provided the last (3rd) vertex will be repeated in the DXF file. The TRACE entity stores the vertices in an unusual way, the last two vertices are reversed: ``` msp.add_solid([(0, 0), (10, 0), (10, 10), (0, 10)]) ``` \[image\] Reverse the last two vertices to get the *expected* square: ``` msp.add_solid([(0, 0), (10, 0), (0, 10), (10, 10)]) ``` \[image\] **NOTE:** The quirky vertex order is preserved at the lowest access level because *ezdxf* is intended as a DXF file format interface and presents the content of the DXF document to the package user as natively as possible. The *Trace.vertices()* and *Trace.wcs\_vertices()* methods return the vertices in the *expected* (reversed) order. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'TRACE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_trace()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Trace** - **dxf.vtx0** Location of 1. vertex (2D/3D Point in *OCS*) - **dxf.vtx1** Location of 2. vertex (2D/3D Point in *OCS*) - **dxf.vtx2** Location of 3. vertex (2D/3D Point in *OCS*) - **dxf.vtx3** Location of 4. vertex (2D/3D Point in *OCS*) - **transform(m: *Matrix44*) -\> Solid** Transform the SOLID/TRACE entity by transformation matrix *m* inplace. - **vertices(close: bool = False) -\> list\[*Vec3*\]** Returns OCS vertices in correct order, if argument *close* is **True**, last vertex == first vertex. Does **not** return the duplicated last vertex if the entity represents a triangle. - **wcs\_vertices(close: bool = False) -\> list\[*Vec3*\]** Returns WCS vertices in correct order, if argument *close* is **True**, last vertex == first vertex. Does **not** return the duplicated last vertex if the entity represents a triangle. ### Underlay The UNDERLAY entity (*DXF Reference*) links an underlay file to the DXF file, the file itself is not embedded into the DXF file, it is always a separated file. The (PDF)UNDERLAY entity is like a block reference, you can use it multiple times to add the underlay on different locations with different scales and rotations. But therefore you need a also a (PDF)DEFINITION entity, see *UnderlayDefinition*. The DXF standard supports three different file formats: PDF, DWF (DWFx) and DGN. An Underlay can be clipped by a rectangle or a polygon path. The clipping coordinates are 2D *OCS* coordinates in drawing units but without scaling. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | internal base class | | Factory function | *ezdxf.layouts.BaseLayout.add\_underlay()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.Underlay** Base class of *PdfUnderlay*, *DwfUnderlay* and *DgnUnderlay* - **dxf.insert** Insertion point, lower left corner of the image in *OCS*. - **dxf.scale\_x** Scaling factor in x-direction (float) - **dxf.scale\_y** Scaling factor in y-direction (float) - **dxf.scale\_z** Scaling factor in z-direction (float) - **dxf.rotation** ccw rotation in degrees around the extrusion vector (float) - **dxf.extrusion** extrusion vector, default is (0, 0, 1) - **dxf.underlay\_def\_handle** Handle to the underlay definition entity, see *UnderlayDefinition* - **dxf.flags** | | | | | --- | --- | --- | | **dxf.flags** | Value | Description | | UNDERLAY\_CLIPPING | 1 | clipping is on/off | | UNDERLAY\_ON | 2 | underlay is on/off | | UNDERLAY\_MONOCHROME | 4 | Monochrome | | UNDERLAY\_ADJUST\_FOR\_BACKGROUND | 8 | Adjust for background | - **dxf.contrast** Contrast value (20 - 100; default is 100) - **dxf.fade** Fade value (0 - 80; default is 0) - **clipping** **True** or **False** (read/write) - **on** **True** or **False** (read/write) - **monochrome** **True** or **False** (read/write) - **adjust\_for\_background** **True** or **False** (read/write) - **scale** Scaling (x, y, z) tuple (read/write) - **boundary\_path** Boundary path as list of vertices (read/write). Two vertices describe a rectangle (lower left and upper right corner), more than two vertices is a polygon as clipping path. - **get\_underlay\_def()** Returns the associated DEFINITION entity. see *UnderlayDefinition*. - **set\_underlay\_def()** Set the associated DEFINITION entity. see *UnderlayDefinition*. - **reset\_boundary\_path() -\> None** Removes the clipping path. ### PdfUnderlay | | | | --- | --- | | Subclass of | *ezdxf.entities.Underlay* | | DXF type | **'PDFUNDERLAY'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_underlay()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.PdfUnderlay** PDF underlay. ### DwfUnderlay | | | | --- | --- | | Subclass of | *ezdxf.entities.Underlay* | | DXF type | **'DWFUNDERLAY'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_underlay()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.DwfUnderlay** DWF underlay. ### DgnUnderlay | | | | --- | --- | | Subclass of | *ezdxf.entities.Underlay* | | DXF type | **'DGNUNDERLAY'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_underlay()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.DgnUnderlay** DGN underlay. ### Viewport The VIEWPORT entity (*DXF Reference*) is a window from a paperspace layout to the modelspace. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'VIEWPORT'** | | Factory function | *ezdxf.layouts.Paperspace.add\_viewport()* | | Inherited DXF attributes | *Common graphical DXF attributes* | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Viewport** - **dxf.center** Center point of the viewport located in the paper space layout in paper space units stored as 3D point. (Error in the DXF reference) - **dxf.width** Viewport width in paperspace units (float) - **dxf.height** Viewport height in paperspace units (float) - **dxf.status** Viewport status field (int) | | | | --- | --- | | -1 | On, but is fully off screen, or is one of the viewports that is not active because the $MAXACTVP count is currently being exceeded. | | 0 | Off | | \>0 | On and active. The value indicates the order of stacking for the viewports, where 1 is the active viewport, 2 is the next, and so forth. | - **dxf.id** Viewport id (int) - **dxf.view\_center\_point** View center point in modelspace stored as 2D point, but represents a *WCS* point. (Error in the DXF reference) - **dxf.snap\_base\_point** - **dxf.snap\_spacing** - **dxf.snap\_angle** - **dxf.grid\_spacing** - **dxf.view\_direction\_vector** View direction (3D vector in *WCS*). - **dxf.view\_target\_point** View target point (3D point in *WCS*). - **dxf.perspective\_lens\_length** Lens focal length in mm as 35mm film equivalent. - **dxf.front\_clip\_plane\_z\_value** - **dxf.back\_clip\_plane\_z\_value** - **dxf.view\_height** View height in *WCS*. - **dxf.view\_twist\_angle** - **dxf.circle\_zoom** - **dxf.flags** Viewport status bit-coded flags: | | | | | --- | --- | --- | | Bit value | Constant in **ezdxf.const** | Description | | 1 (0x1) | VSF\_PERSPECTIVE\_MODE | Enables perspective mode | | 2 (0x2) | VSF\_FRONT\_CLIPPING | Enables front clipping | | 4 (0x4) | VSF\_BACK\_CLIPPING | Enables back clipping | | 8 (0x8) | VSF\_USC\_FOLLOW | Enables UCS follow | | 16 (0x10) | VSF\_FRONT\_CLIPPING\_NOT\_AT\_EYE | Enables front clip not at eye | | 32 (0x20) | VSF\_UCS\_ICON\_VISIBILITY | Enables UCS icon visibility | | 64 (0x40) | VSF\_UCS\_ICON\_AT\_ORIGIN | Enables UCS icon at origin | | 128 (0x80) | VSF\_FAST\_ZOOM | Enables fast zoom | | 256 (0x100) | VSF\_SNAP\_MODE | Enables snap mode | | 512 (0x200) | VSF\_GRID\_MODE | Enables grid mode | | 1024 (0x400) | VSF\_ISOMETRIC\_SNAP\_STYLE | Enables isometric snap style | | 2048 (0x800) | VSF\_HIDE\_PLOT\_MODE | Enables hide plot mode | | 4096 (0x1000) | VSF\_KISOPAIR\_TOP | kIsoPairTop. If set and kIsoPairRight is not set, then isopair top is enabled. If both kIsoPairTop and kIsoPairRight are set, then isopair left is enabled | | 8192 (0x2000) | VSF\_KISOPAIR\_RIGHT | kIsoPairRight. If set and kIsoPairTop is not set, then isopair right is enabled | | 16384 (0x4000) | VSF\_LOCK\_ZOOM | Enables viewport zoom locking | | 32768 (0x8000) | VSF\_CURRENTLY\_ALWAYS\_ENABLED | Currently always enabled | | 65536 (0x10000) | VSF\_NON\_RECTANGULAR\_CLIPPING | Enables non-rectangular clipping | | 131072 (0x20000) | VSF\_TURN\_VIEWPORT\_OFF | Turns the viewport off | | 262144 (0x40000) | VSF\_NO\_GRID\_LIMITS | Enables the display of the grid beyond the drawing limits | | 524288 (0x80000) | VSF\_ADAPTIVE\_GRID\_DISPLAY | Enable adaptive grid display | | 1048576 (0x100000) | VSF\_SUBDIVIDE\_GRID | Enables subdivision of the grid below the set grid spacing when the grid display is adaptive | | 2097152 (0x200000) | VSF\_GRID\_FOLLOW\_WORKPLANE | Enables grid follows workplane switching | Use helper method *set\_flag\_state()* to set and clear viewport flags, e.g. lock viewport: ``` vp.set_flag_state(ezdxf.const.VSF_LOCK_ZOOM, True) ``` - **dxf.clipping\_boundary\_handle** - **dxf.plot\_style\_name** - **dxf.render\_mode** | | | | --- | --- | | 0 | 2D Optimized (classic 2D) | | 1 | Wireframe | | 2 | Hidden line | | 3 | Flat shaded | | 4 | Gouraud shaded | | 5 | Flat shaded with wireframe | | 6 | Gouraud shaded with wireframe | - **dxf.ucs\_per\_viewport** - **dxf.ucs\_icon** - **dxf.ucs\_origin** UCS origin as 3D point. - **dxf.ucs\_x\_axis** UCS x-axis as 3D vector. - **dxf.ucs\_y\_axis** UCS y-axis as 3D vector. - **dxf.ucs\_handle** Handle of **UCSTable** if UCS is a named UCS. If not present, then UCS is unnamed. - **dxf.ucs\_ortho\_type** | | | | --- | --- | | 0 | not orthographic | | 1 | Top | | 2 | Bottom | | 3 | Front | | 4 | Back | | 5 | Left | | 6 | Right | - **dxf.ucs\_base\_handle** Handle of **UCSTable** of base UCS if UCS is orthographic (*Viewport.dxf.ucs\_ortho\_type* is non-zero). If not present and *Viewport.dxf.ucs\_ortho\_type* is non-zero, then base UCS is taken to be WORLD. - **dxf.elevation** - **dxf.shade\_plot\_mode** (DXF R2004) | | | | --- | --- | | 0 | As Displayed | | 1 | Wireframe | | 2 | Hidden | | 3 | Rendered | - **dxf.grid\_frequency** Frequency of major grid lines compared to minor grid lines. (DXF R2007) - **dxf.background\_handle** - **dxf.shade\_plot\_handle** - **dxf.visual\_style\_handle** - **dxf.default\_lighting\_flag** - **dxf.default\_lighting\_style** | | | | --- | --- | | 0 | One distant light | | 1 | Two distant lights | - **dxf.view\_brightness** - **dxf.view\_contrast** - **dxf.ambient\_light\_color\_1** as *AutoCAD Color Index (ACI)* - **dxf.ambient\_light\_color\_2** as true color value - **dxf.ambient\_light\_color\_3** as true color value - **dxf.sun\_handle** - **dxf.ref\_vp\_object\_1** - **dxf.ref\_vp\_object\_2** - **dxf.ref\_vp\_object\_3** - **dxf.ref\_vp\_object\_4** - **frozen\_layers** Set/get frozen layers as list of layer names. - **is\_frozen(layer\_name: str) -\> bool** Returns **True** if *layer\_name* id frozen in this viewport. - **freeze(layer\_name: str) -\> None** Freeze *layer\_name* in this viewport. - **thaw(layer\_name: str) -\> None** Thaw *layer\_name* in this viewport. - **has\_extended\_clipping\_path** Returns **True** if a non-rectangular clipping path is defined. - **clipping\_rect() -\> tuple\[*Vec2*, *Vec2*\]** Returns the lower left and the upper right corner of the clipping rectangle in paperspace coordinates. - **clipping\_rect\_corners() -\> list\[*Vec2*\]** Returns the default rectangular clipping path as list of vertices. Use function *ezdxf.path.make\_path()* to get also non-rectangular shaped clipping paths if defined. - **get\_aspect\_ratio() -\> float** Returns the aspect ratio of the viewport, return 0.0 if width or height is zero. - **get\_modelspace\_limits() -\> tuple\[float, float, float, float\]** Returns the limits of the modelspace to view in drawing units as tuple (min\_x, min\_y, max\_x, max\_y). - **get\_scale() -\> float** Returns the scaling factor from modelspace to viewport. - **get\_transformation\_matrix() -\> *Matrix44*** Returns the transformation matrix from modelspace to paperspace coordinates. ### Wipeout The WIPEOUT entity (*DXF Reference*) is a polygonal area that masks underlying objects with the current background color. The WIPEOUT entity is based on the IMAGE entity, but usage does not require any knowledge about the IMAGE entity. The handles to the support entities *ImageDef* and *ImageDefReactor* are always “0”, both are not needed by the WIPEOUT entity. | | | | --- | --- | | Subclass of | *ezdxf.entities.Image* | | DXF type | **'WIPEOUT'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_wipeout()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | **WARNING:** Do not instantiate entity classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Wipeout** - **set\_masking\_area(vertices: Iterable\[*UVec*\]) -\> None** Set a new masking area, the area is placed in the layout xy-plane. ### XLine The XLINE entity (*DXF Reference*) is a construction line that extents to infinity in both directions. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFGraphic* | | DXF type | **'XLINE'** | | Factory function | *ezdxf.layouts.BaseLayout.add\_xline()* | | Inherited DXF attributes | *Common graphical DXF attributes* | | Required DXF version | DXF R2000 (**'AC1015'**) | - **class ezdxf.entities.XLine** - **dxf.start** Location point of line as (3D Point in *WCS*) - **dxf.unit\_vector** Unit direction vector as (3D Point in *WCS*) - **transform(m: *Matrix44*) -\> XLine** Transform the XLINE/RAY entity by transformation matrix *m* inplace. - **translate(dx: float, dy: float, dz: float) -\> XLine** Optimized XLINE/RAY translation about *dx* in x-axis, *dy* in y-axis and *dz* in z-axis. ### DXF Objects All DXF objects can only reside in the OBJECTS section of a DXF document. The purpose of the OBJECTS section is to allow CAD software developers to define and store custom objects that are not included in the basic DXF file format. These custom objects can be used to represent complex data structures, such as database tables or project management information, that are not easily represented by basic DXF entities. By including custom objects in the OBJECTS section, CAD software developers can extend the functionality of their software to support new types of data and objects. For example, a custom application might define a new type of block or dimension style that is specific to a particular industry or workflow. By storing this custom object definition in the OBJECTS section, the CAD software can recognize and use the new object type in a drawing. In summary, the OBJECTS section is an important part of the DXF file format because it allows CAD software developers to extend the functionality of their software by defining and storing custom objects and entity types. This makes it possible to represent complex data structures and workflows in CAD drawings, and allows CAD software to be customized to meet the specific needs of different industries and applications. ### Dictionary The *DICTIONARY* entity is a general storage entity. AutoCAD maintains items such as MLINE\_STYLES and GROUP definitions as objects in dictionaries. Other applications are free to create and use their own dictionaries as they see fit. The prefix **'ACAD\_'** is reserved for use by AutoCAD applications. Dictionary entries are (key, *DXFEntity*) pairs for fully loaded or new created DXF documents. The referenced entities are owned by the dictionary and cannot be graphical entities that always belong to the layout in which they are located. Loading DXF files is done in two passes, because at the first loading stage not all referenced objects are already stored in the entity database. Therefore the entities are stored as handles strings at the first loading stage and have to be replaced by the real entity at the second loading stage. If the entity is still a handle string after the second loading stage, the entity does not exist. Dictionary keys are handled case insensitive by AutoCAD, but not by *ezdxf*, in doubt use an uppercase key. AutoCAD stores all keys in uppercase. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'DICTIONARY'** | | Factory function | *ezdxf.sections.objects.ObjectsSection.add\_dictionary()* | **WARNING:** Do not instantiate object classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Dictionary** - **dxf.hard\_owned** If set to 1, indicates that elements of the dictionary are to be treated as hard-owned. - **dxf.cloning** Duplicate record cloning flag (determines how to merge duplicate entries, ignored by *ezdxf*): | | | | --- | --- | | 0 | not applicable | | 1 | keep existing | | 2 | use clone | | 3 | \$0$\ | | 4 | $0$\ | | 5 | Unmangle name | - **is\_hard\_owner** Returns **True** if the dictionary is hard owner of entities. Hard owned entities will be destroyed by deleting the dictionary. - **\_\_len\_\_() -\> int** Returns count of dictionary entries. - **\_\_contains\_\_(key: str) -\> bool** Returns *key* **in** self. - **\_\_getitem\_\_(key: str) -\> DXFEntity** Return self\[*key*\]. The returned value can be a handle string if the entity does not exist. - **Raises** *DXFKeyError* – *key* does not exist - **\_\_setitem\_\_(key: str, entity: DXFObject) -\> None** Set self\[*key*\] = *entity*. Only DXF objects stored in the OBJECTS section are allowed as content of *Dictionary* objects. DXF entities stored in layouts are not allowed. - **Raises** *DXFTypeError* – invalid DXF type - **\_\_delitem\_\_(key: str) -\> None** Delete self\[*key*\]. - **Raises** *DXFKeyError* – *key* does not exist - **keys()** Returns a **KeysView** of all dictionary keys. - **items()** Returns an **ItemsView** for all dictionary entries as (key, entity) pairs. An entity can be a handle string if the entity does not exist. - **count() -\> int** Returns count of dictionary entries. - **get(key: str, default: DXFObject \| None = None) -\> DXFObject \| None** Returns the *DXFEntity* for *key*, if *key* exist else *default*. An entity can be a handle string if the entity does not exist. - **add(key: str, entity: DXFObject) -\> None** Add entry (key, value). If the DICTIONARY is hard owner of its entries, the *add()* does NOT take ownership of the entity automatically. - **Raises** - • *DXFValueError* – invalid entity handle - • *DXFTypeError* – invalid DXF type - **remove(key: str) -\> None** Delete entry *key*. Raises **DXFKeyError**, if *key* does not exist. Destroys hard owned DXF entities. - **discard(key: str) -\> None** Delete entry *key* if exists. Does not raise an exception if *key* doesn’t exist and does not destroy hard owned DXF entities. - **clear() -\> None** Delete all entries from the dictionary and destroys hard owned DXF entities. - **add\_new\_dict(key: str, hard\_owned: bool = False) -\> Dictionary** Create a new sub-dictionary of type *Dictionary*. - **Parameters** - • **key** – name of the sub-dictionary - • **hard\_owned** – entries of the new dictionary are hard owned - **get\_required\_dict(key: str, hard\_owned=False) -\> Dictionary** Get entry *key* or create a new *Dictionary*, if *Key* not exist. - **add\_dict\_var(key: str, value: str) -\> DictionaryVar** Add a new *DictionaryVar*. - **Parameters** - • **key** – entry name as string - • **value** – entry value as string - **add\_xrecord(key: str) -\> *XRecord*** Add a new *XRecord*. - **Parameters** **key** – entry name as string - **link\_dxf\_object(name: str, obj: DXFObject) -\> None** Add *obj* and set owner of *obj* to this dictionary. Graphical DXF entities have to reside in a layout and therefore can not be owned by a *Dictionary*. - **Raises** *DXFTypeError* – *obj* has invalid DXF type ### DictionaryWithDefault | | | | --- | --- | | Subclass of | *ezdxf.entities.Dictionary* | | DXF type | **'ACDBDICTIONARYWDFLT'** | | Factory function | *ezdxf.sections.objects.ObjectsSection.add\_dictionary\_with\_default()* | - **class ezdxf.entities.DictionaryWithDefault** - **dxf.default** Handle to default entry as hex string like **FF00**. - **get(key: str, default: DXFObject \| None = None) -\> DXFObject \| None** Returns *DXFEntity* for *key* or the predefined dictionary wide *dxf.default* entity if *key* does not exist or **None** if default value also not exist. - **set\_default(default: DXFObject) -\> None** Set dictionary wide default entry. - **Parameters** **default** – default entry as *DXFEntity* ### DictionaryVar | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'DICTIONARYVAR'** | | Factory function | *ezdxf.entities.Dictionary.add\_dict\_var()* | - **class ezdxf.entities.DictionaryVar** - **dxf.schema** Object schema number (currently set to 0) - **dxf.value** Value as string. - **property value: str** Get/set the value of the *DictionaryVar* as string. ### DXFLayout *LAYOUT* entity is part of a modelspace or paperspace layout definitions. | | | | --- | --- | | Subclass of | *ezdxf.entities.PlotSettings* | | DXF type | **'LAYOUT'** | | Factory function | internal data structure, use *Layouts* to manage layout objects. | - **class ezdxf.entities.DXFLayout** - **dxf.name** Layout name as shown in tabs by *CAD* applications - **dxf.layout\_flags** | | | | --- | --- | | 1 | Indicates the PSLTSCALE value for this layout when this layout is current | | 2 | Indicates the LIMCHECK value for this layout when this layout is current | - **dxf.tab\_order** default is 1 - **dxf.limmin** default is Vec2(0, 0) - **dxf.limmax** default is Vec2(420, 297) - **dxf.insert\_base** default is Vec3(0, 0, 0) - **dxf.extmin** default is Vec3(1e20, 1e20, 1e20) - **dxf.extmax** default is Vec3(-1e20, -1e20, -1e20) - **dxf.elevation** default is 0 - **dxf.ucs\_origin** default is Vec3(0, 0, 0) - **dxf.ucs\_xaxis** default is Vec3(1, 0, 0) - **dxf.ucs\_yaxis** default is Vec3(0, 1, 0) - **dxf.ucs\_type** | | | | --- | --- | | 0 | UCS is not orthographic | | 1 | Top | | 2 | Bottom | | 3 | Front | | 4 | Back | | 5 | Left | | 6 | Right | default is 1 - **dxf.block\_record\_handle** - **dxf.viewport\_handle** - **dxf.ucs\_handle** - **dxf.base\_ucs\_handle** ### DXFObject Common base class for all non-graphical DXF objects. - **class ezdxf.entities.DXFObject** A class hierarchy marker class and subclass of *ezdxf.entities.DXFEntity* ### GeoData The *GEODATA* entity is associated to the *Modelspace* object. The *GEODATA* entity is supported since the DXF version R2000, but was officially documented the first time in the DXF reference for version R2009. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'GEODATA'** | | Factory function | *ezdxf.layouts.Modelspace.new\_geodata()* | | Required DXF version | R2010 (**'AC1024'**) | **SEE ALSO:** *geodata\_setup\_local\_grid.py* **WARNING:** Do not instantiate object classes by yourself - always use the provided factory functions! - **class ezdxf.entities.GeoData** - **dxf.version** | | | | --- | --- | | 1 | R2009 | | 2 | R2010 | - **dxf.coordinate\_type** | | | | --- | --- | | 0 | unknown | | 1 | local grid | | 2 | projected grid | | 3 | geographic (latitude/longitude) | - **dxf.block\_record\_handle** Handle of host BLOCK\_RECORD table entry, in general the *Modelspace*. - **dxf.design\_point** Reference point in *WCS* coordinates. - **dxf.reference\_point** Reference point in geo coordinates, valid only when coordinate type is *local grid*. The difference between *dxf.design\_point* and *dxf.reference\_point* defines the translation from WCS coordinates to geo-coordinates. - **dxf.north\_direction** North direction as 2D vector. Defines the rotation (about the *dxf.design\_point*) to transform from WCS coordinates to geo-coordinates - **dxf.horizontal\_unit\_scale** Horizontal unit scale, factor which converts horizontal design coordinates to meters by multiplication. - **dxf.vertical\_unit\_scale** Vertical unit scale, factor which converts vertical design coordinates to meters by multiplication. - **dxf.horizontal\_units** Horizontal units (see *BlockRecord*). Will be 0 (Unitless) if units specified by horizontal unit scale is not supported by AutoCAD enumeration. - **dxf.vertical\_units** Vertical units (see *BlockRecord*). Will be 0 (Unitless) if units specified by vertical unit scale is not supported by AutoCAD enumeration. - **dxf.up\_direction** Up direction as 3D vector. - **dxf.scale\_estimation\_method** | | | | --- | --- | | 1 | none | | 2 | user specified scale factor | | 3 | grid scale at reference point | | 4 | prismoidal | - **dxf.sea\_level\_correction** Bool flag specifying whether to do sea level correction. - **dxf.user\_scale\_factor** - **dxf.sea\_level\_elevation** - **dxf.coordinate\_projection\_radius** - **dxf.geo\_rss\_tag** - **dxf.observation\_from\_tag** - **dxf.observation\_to\_tag** - **dxf.mesh\_faces\_count** - **source\_vertices** 2D source vertices in the CRS of the GeoData as *VertexArray*. Used together with *target\_vertices* to define the transformation from the CRS of the GeoData to WGS84. - **target\_vertices** 2D target vertices in WGS84 (EPSG:4326) as *VertexArray*. Used together with *source\_vertices* to define the transformation from the CRS of the geoData to WGS84. - **faces** List of face definition tuples, each face entry is a 3-tuple of vertex indices (0-based). - **coordinate\_system\_definition** The coordinate system definition string. Stored as XML. Defines the CRS used by the GeoData. The EPSG number and other details like the axis-ordering of the CRS is stored. - **get\_crs() -\> tuple\[int, bool\]** Returns the EPSG index and axis-ordering, axis-ordering is **True** if fist axis is labeled “E” or “W” and **False** if first axis is labeled “N” or “S”. If axis-ordering is **False** the CRS is not compatible with the **\_\_geo\_interface\_\_** or GeoJSON (see chapter 3.1.1). - **Raises** **InvalidGeoDataException** – for invalid or unknown XML data The EPSG number is stored in a tag like: ``` OSGB1936.NationalGrid EPSG Code ``` The axis-ordering is stored in a tag like: ``` 1 Easting E east 2 Northing N north ``` - **get\_crs\_transformation(\*, no\_checks: bool = False) -\> tuple\[*Matrix44*, int\]** Returns the transformation matrix and the EPSG index to transform WCS coordinates into CRS coordinates. Because of the lack of proper documentation this method works only for tested configurations, set argument *no\_checks* to **True** to use the method for untested geodata configurations, but the results may be incorrect. Supports only “Local Grid” transformation! - **Raises** **InvalidGeoDataException** – for untested geodata configurations - **setup\_local\_grid(\*, design\_point: *UVec*, reference\_point: *UVec*, north\_direction: *UVec* = (0, 1), crs: str = EPSG\_3395)** Setup local grid coordinate system. This method is designed to setup CRS similar to *EPSG:3395 World Mercator*, the basic features of the CRS should fulfill these assumptions: - • base unit of reference coordinates is 1 meter - • right-handed coordinate system: +Y=north/+X=east/+Z=up The CRS string is not validated nor interpreted! **HINT:** The reference point must be a 2D cartesian map coordinate and not a globe (lon/lat) coordinate like stored in GeoJSON or GPS data. - **Parameters** - • **design\_point** – WCS coordinates of the CRS reference point - • **reference\_point** – CRS reference point in 2D cartesian coordinates - • **north\_direction** – north direction a 2D vertex, default is (0, 1) - • **crs** – Coordinate Reference System definition XML string, default is the definition string for *EPSG:3395 World Mercator* ### ImageDef The *IMAGEDEF* entity defines an image file, which can be placed by the *Image* entity. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'IMAGEDEF'** | | Factory function (1) | *ezdxf.document.Drawing.add\_image\_def()* | | Factory function (2) | *ezdxf.sections.objects.ObjectsSection.add\_image\_def()* | **WARNING:** Do not instantiate object classes by yourself - always use the provided factory functions! - **class ezdxf.entities.ImageDef** - **dxf.class\_version** Current version is 0. - **dxf.filename** Relative (to the DXF file) or absolute path to the image file as string. - **dxf.image\_size** Image size in pixel as (x, y) tuple. - **dxf.pixel\_size** Default size of one pixel in drawing units as (x, y) tuple. - **dxf.loaded** 0 = unloaded; 1 = loaded, default is 1 - **dxf.resolution\_units** | | | | --- | --- | | 0 | No units | | 2 | Centimeters | | 5 | Inch | default is 0 ### ImageDefReactor - **class ezdxf.entities.ImageDefReactor** - **dxf.class\_version** - **dxf.image\_handle** ### MLeaderStyle The MLEADERSTYLE entity (*DXF Reference*) stores all attributes required to create new *MultiLeader* entities. The meaning of these attributes are not really documented in the *DXF Reference*. The default style “Standard” always exist. **SEE ALSO:** - • *ezdxf.entities.MultiLeader* - • *ezdxf.render.MultiLeaderBuilder* - • *Tutorial for MultiLeader* Create a new *MLeaderStyle*: ``` import ezdxf doc = ezdxf.new() new_style = doc.mleader_styles.new("NewStyle") ``` Duplicate an existing style: ``` duplicated_style = doc.mleader_styles.duplicate_entry("Standard", "DuplicatedStyle") ``` | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'MLEADERSTYLE'** | | Factory function | **ezdxf.document.Drawing.mleader\_styles.new()** | - **class ezdxf.entities.MLeaderStyle** - **dxf.align\_space** unknown meaning - **dxf.arrow\_head\_handle** handle of default arrow head, see also *ezdxf.render.arrows* module, by default no handle is set, which mean default arrow “closed filled” - **dxf.arrow\_head\_size** default arrow head size in drawing units, default is 4.0 - **dxf.block\_color** default block color as ;term:*raw color* value, default is BY\_BLOCK\_RAW\_VALUE - **dxf.block\_connection\_type** | | | | --- | --- | | 0 | center extents | | 1 | insertion point | - **dxf.block\_record\_handle** handle to block record of the BLOCK content, not set by default - **dxf.block\_rotation** default BLOCK rotation in radians, default is 0.0 - **dxf.block\_scale\_x** default block x-axis scale factor, default is 1.0 - **dxf.block\_scale\_y** default block y-axis scale factor, default is 1.0 - **dxf.block\_scale\_z** default block z-axis scale factor, default is 1.0 - **dxf.break\_gap\_size** default break gap size, default is 3.75 - **dxf.char\_height** default MTEXT char height, default is 4.0 - **dxf.content\_type** | | | | --- | --- | | 0 | none | | 1 | BLOCK | | 2 | MTEXT | | 3 | TOLERANCE | default is MTEXT (2) - **dxf.default\_text\_content** default MTEXT content as string, default is “” - **dxf.dogleg\_length** default dogleg length, default is 8.0 - **dxf.draw\_leader\_order\_type** unknown meaning - **dxf.draw\_mleader\_order\_type** unknown meaning - **dxf.first\_segment\_angle\_constraint** angle of fist leader segment in radians, default is 0.0 - **dxf.has\_block\_rotation** - **dxf.has\_block\_scaling** - **dxf.has\_dogleg** default is 1 - **dxf.has\_landing** default is 1 - **dxf.is\_annotative** default is 0 - **dxf.landing\_gap\_size** default landing gap size, default is 2.0 - **dxf.leader\_line\_color** default leader line color as *raw-color* value, default is BY\_BLOCK\_RAW\_VALUE - **dxf.leader\_linetype\_handle** handle of default leader linetype - **dxf.leader\_lineweight** default leader lineweight, default is LINEWEIGHT\_BYBLOCK - **dxf.leader\_type** | | | | --- | --- | | 0 | invisible | | 1 | straight line leader | | 2 | spline leader | default is 1 - **dxf.max\_leader\_segments\_points** max count of leader segments, default is 2 - **dxf.name** MLEADERSTYLE name - **dxf.overwrite\_property\_value** unknown meaning - **dxf.scale** overall scaling factor, default is 1.0 - **dxf.second\_segment\_angle\_constraint** angle of fist leader segment in radians, default is 0.0 - **dxf.text\_align\_always\_left** use always left side to attach leaders, default is 0 - **dxf.text\_alignment\_type** unknown meaning - its not the MTEXT attachment point! - **dxf.text\_angle\_type** | | | | --- | --- | | 0 | text angle is equal to last leader line segment angle | | 1 | text is horizontal | | 2 | text angle is equal to last leader line segment angle, but potentially rotated by 180 degrees so the right side is up for readability. | default is 1 - **dxf.text\_attachment\_direction** defines whether the leaders attach to the left & right of the content BLOCK/MTEXT or attach to the top & bottom: | | | | --- | --- | | 0 | horizontal - left & right of content | | 1 | vertical - top & bottom of content | default is 0 - **dxf.text\_bottom\_attachment\_type** | | | | --- | --- | | 9 | center | | 10 | overline and center | default is 9 - **dxf.text\_color** default MTEXT color as *raw-color* value, default is BY\_BLOCK\_RAW\_VALUE - **dxf.text\_left\_attachment\_type** | | | | --- | --- | | 0 | top of top MTEXT line | | 1 | middle of top MTEXT line | | 2 | middle of whole MTEXT | | 3 | middle of bottom MTEXT line | | 4 | bottom of bottom MTEXT line | | 5 | bottom of bottom MTEXT line & underline bottom MTEXT line | | 6 | bottom of top MTEXT line & underline top MTEXT line | | 7 | bottom of top MTEXT line | | 8 | bottom of top MTEXT line & underline all MTEXT lines | - **dxf.text\_right\_attachment\_type** | | | | --- | --- | | 0 | top of top MTEXT line | | 1 | middle of top MTEXT line | | 2 | middle of whole MTEXT | | 3 | middle of bottom MTEXT line | | 4 | bottom of bottom MTEXT line | | 5 | bottom of bottom MTEXT line & underline bottom MTEXT line | | 6 | bottom of top MTEXT line & underline top MTEXT line | | 7 | bottom of top MTEXT line | | 8 | bottom of top MTEXT line & underline all MTEXT lines | - **dxf.text\_style\_handle** handle of the default MTEXT text style, not set by default, which means “Standard” - **dxf.text\_top\_attachment\_type** | | | | --- | --- | | 9 | center | | 10 | overline and center | ### Placeholder The *ACDBPLACEHOLDER* object for internal usage. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'ACDBPLACEHOLDER'** | | Factory function | *ezdxf.sections.objects.ObjectsSection.add\_placeholder()* | **WARNING:** Do not instantiate object classes by yourself - always use the provided factory functions! - **class ezdxf.entities.Placeholder** ### PlotSettings All *PLOTSETTINGS* attributes are part of the *DXFLayout* entity, I don’t know if this entity also appears as standalone entity. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'PLOTSETTINGS'** | | Factory function | internal data structure | - **class ezdxf.entities.PlotSettings** - **dxf.page\_setup\_name** default is “” - **dxf.plot\_configuration\_file** default is “Adobe PDF” - **dxf.paper\_size** default is “A3” - **dxf.plot\_view\_name** default is “” - **dxf.left\_margin** default is 7.5 mm - **dxf.bottom\_margin** default is 20 mm - **dxf.right\_margin** default is 7.5 mm - **dxf.top\_margin** default is 20 mm - **dxf.paper\_width** default is 420 mm - **dxf.paper\_height** default is 297 mm - **dxf.plot\_origin\_x\_offset** default is 0 - **dxf.plot\_origin\_y\_offset** default is 0 - **dxf.plot\_window\_x1** default is 0 - **dxf.plot\_window\_y1** default is 0 - **dxf.plot\_window\_x2** default is 0 - **dxf.plot\_window\_y2** default is 0 - **dxf.scale\_numerator** default is 1 - **dxf.scale\_denominator** default is 1 - **dxf.plot\_layout\_flags** | | | | --- | --- | | 1 | plot viewport borders | | 2 | show plot-styles | | 4 | plot centered | | 8 | plot hidden == hide paperspace entities? | | 16 | use standard scale | | 32 | plot with plot-styles | | 64 | scale lineweights | | 128 | plot entity lineweights | | 512 | draw viewports first | | 1024 | model type | | 2048 | update paper | | 4096 | zoom to paper on update | | 8192 | initializing | | 16384 | prev plot-init | default is 688 - **dxf.plot\_paper\_units** | | | | --- | --- | | 0 | Plot in inches | | 1 | Plot in millimeters | | 2 | Plot in pixels | - **dxf.plot\_rotation** | | | | --- | --- | | 0 | No rotation | | 1 | 90 degrees counterclockwise | | 2 | Upside-down | | 3 | 90 degrees clockwise | - **dxf.plot\_type** | | | | --- | --- | | 0 | Last screen display | | 1 | Drawing extents | | 2 | Drawing limits | | 3 | View specified by code 6 | | 4 | Window specified by codes 48, 49, 140, and 141 | | 5 | Layout information | - **dxf.current\_style\_sheet** default is “” - **dxf.standard\_scale\_type** | | | | --- | --- | | 0 | Scaled to Fit | | 1 | 1/128”=1’ | | 2 | 1/64”=1’ | | 3 | 1/32”=1’ | | 4 | 1/16”=1’ | | 5 | 3/32”=1’ | | 6 | 1/8”=1’ | | 7 | 3/16”=1’ | | 8 | 1/4”=1’ | | 9 | 3/8”=1’ | | 10 | 1/2”=1’ | | 11 | 3/4”=1’ | | 12 | 1”=1’ | | 13 | 3”=1’ | | 14 | 6”=1’ | | 15 | 1’=1’ | | 16 | 1:1 | | 17 | 1:2 | | 18 | 1:4 | | 19 | 1:8 | | 20 | 1:10 | | 21 | 1:16 | | 22 | 1:20 | | 23 | 1:30 | | 24 | 1:40 | | 25 | 1:50 | | 26 | 1:100 | | 27 | 2:1 | | 28 | 4:1 | | 29 | 8:1 | | 30 | 10:1 | | 31 | 100:1 | | 32 | 1000:1 | - **dxf.shade\_plot\_mode** | | | | --- | --- | | 0 | As Displayed | | 1 | Wireframe | | 2 | Hidden | | 3 | Rendered | - **dxf.shade\_plot\_resolution\_level** | | | | --- | --- | | 0 | Draft | | 1 | Preview | | 2 | Normal | | 3 | Presentation | | 4 | Maximum | | 5 | Custom | - **dxf.shade\_plot\_custom\_dpi** default is 300 - **dxf.unit\_factor** default is 1 - **dxf.paper\_image\_origin\_x** default is 0 - **dxf.paper\_image\_origin\_y** default is 0 - **dxf.shade\_plot\_handle** ### SpatialFilter The *SPATIAL\_FILTER* object stores the clipping path for external references and block references. For more information about getting, setting and removing clippings paths read the docs for the *ezdxf.xclip.XClip* class. The HEADER variable $XCLIPFRAME determines if the clipping path is displayed and plotted: | | | | --- | --- | | 0 | not displayed, not plotted | | 1 | displayed, not plotted | | 2 | displayed and plotted | **SEE ALSO:** - • *ezdxf.xclip* - • Knowledge Graph: *https://ezdxf.mozman.at/notes/#/page/spatial\_filter* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'SPATIAL\_FILTER'** | | Factory function | internal data structure | - **class ezdxf.entities.SpatialFilter** - **dxf.back\_clipping\_plane\_distance** Defines the distance of the back clipping plane from the origin in direction of the extrusion vector. - **dxf.is\_clipping\_enabled** Block reference clipping is enabled when 1 and disabled when 0. - **dxf.extrusion** Defines the orientation of the OCS - **dxf.front\_clipping\_plane\_distance** Defines the distance of the front clipping plane from the origin in direction of the extrusion vector. - **dxf.has\_back\_clipping\_plane** - **dxf.has\_front\_clipping\_plane** - **dxf.origin** Defines the origin of the OCS - **property boundary\_vertices: tuple\[*Vec2*, ...\]** Returns the clipping path vertices in OCS coordinates. - **property inverse\_insert\_matrix: *Matrix44*** Returns the inverse insert matrix. This matrix is the inverse of the original block reference (insert entity) transformation. The original block reference transformation is the one that is applied to all entities in the block when the block reference is regenerated. - **property transform\_matrix: *Matrix44*** Returns the transform matrix. This matrix transforms points into the coordinate system of the clip boundary. - **set\_boundary\_vertices(vertices: Iterable\[*UVec*\]) -\> None** Set the clipping path vertices in OCS coordinates. - **set\_inverse\_insert\_matrix(m: *Matrix44*) -\> None** - **set\_transform\_matrix(m: *Matrix44*) -\> None** ### Sun The *SUN* entity defines properties of the sun. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'SUN'** | | Factory function | creating a new SUN entity is not supported | - **class ezdxf.entities.Sun** - **dxf.version** Current version is 1. - **dxf.status** on = 1 or off = 0 - **dxf.color** *AutoCAD Color Index (ACI)* value of the sun. - **dxf.true\_color** *true-color* value of the sun. - **dxf.intensity** Intensity value in the range of \[0, 1\]. (float) - **dxf.julian\_day** use *calendardate()* to convert **dxf.julian\_day** to **datetime.datetime** object. - **dxf.time** Day time in seconds past midnight. (int) - **dxf.daylight\_savings\_time** - **dxf.shadows** | | | | --- | --- | | 0 | Sun do not cast shadows | | 1 | Sun do cast shadows | - **dxf.shadow\_type** - **dxf.shadow\_map\_size** - **dxf.shadow\_softness** ### UnderlayDefinition *UnderlayDefinition* (*DXF Reference*) defines an underlay file, which can be placed by the *Underlay* entity. | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | internal base class | | Factory function (1) | *ezdxf.document.Drawing.add\_underlay\_def()* | | Factory function (2) | *ezdxf.sections.objects.ObjectsSection.add\_underlay\_def()* | - **class ezdxf.entities.UnderlayDefinition** Base class of *PdfDefinition*, *DwfDefinition* and *DgnDefinition* - **dxf.filename** Relative (to the DXF file) or absolute path to the underlay file as string. - **dxf.name** Defines which part of the underlay file to display. | | | | --- | --- | | “pdf” | PDF page number | | “dgn” | always “default” | | “dwf” | ? | **WARNING:** Do not instantiate object classes by yourself - always use the provided factory functions! ### PdfDefinition | | | | --- | --- | | Subclass of | *ezdxf.entities.UnderlayDefinition* | | DXF type | **'PDFDEFINITION'** | | Factory function (1) | *ezdxf.document.Drawing.add\_underlay\_def()* | | Factory function (2) | *ezdxf.sections.objects.ObjectsSection.add\_underlay\_def()* | - **class ezdxf.entities.PdfDefinition** PDF underlay file. ### DwfDefinition | | | | --- | --- | | Subclass of | *ezdxf.entities.UnderlayDefinition* | | DXF type | **'DWFDEFINITION'** | | Factory function (1) | *ezdxf.document.Drawing.add\_underlay\_def()* | | Factory function (2) | *ezdxf.sections.objects.ObjectsSection.add\_underlay\_def()* | - **class ezdxf.entities.DwfDefinition** DWF underlay file. ### DgnDefinition | | | | --- | --- | | Subclass of | *ezdxf.entities.UnderlayDefinition* | | DXF type | **'DGNDEFINITION'** | | Factory function (1) | *ezdxf.document.Drawing.add\_underlay\_def()* | | Factory function (2) | *ezdxf.sections.objects.ObjectsSection.add\_underlay\_def()* | - **class ezdxf.entities.DgnDefinition** DGN underlay file. ### XRecord Important class for storing application defined data in DXF files. The *XRECORD* entities are used to store and manage arbitrary data. They are composed of DXF group codes ranging from 1 through 369. This object is similar in concept to XDATA but is not limited by size or order. To reference a XRECORD by an DXF entity, store the handle of the XRECORD in the XDATA section, application defined data or the **ExtensionDict** of the DXF entity. **SEE ALSO:** - • *Extended Data (XDATA)* - • *Extension Dictionary* - • *Storing Custom Data in DXF Files* | | | | --- | --- | | Subclass of | *ezdxf.entities.DXFObject* | | DXF type | **'XRECORD'** | | Factory function | *ezdxf.sections.objects.ObjectsSection.add\_xrecord()* | **WARNING:** Do not instantiate object classes by yourself - always use the provided factory functions! - **class ezdxf.entities.XRecord** - **dxf.cloning** Duplicate record cloning flag (determines how to merge duplicate entries, ignored by *ezdxf*): | | | | --- | --- | | 0 | not applicable | | 1 | keep existing | | 2 | use clone | | 3 | \$0$\ | | 4 | $0$\ | | 5 | Unmangle name | - **tags** Raw DXF tag container *Tags*. Be careful *ezdxf* does not validate the content of XRECORDS. - **clear() -\> None** Remove all DXF tags. - **reset(tags: Iterable\[tuple\[int, Any\] \| *DXFTag*\]) -\> None** Reset DXF tags. - **extend(tags: Iterable\[tuple\[int, Any\] \| *DXFTag*\]) -\> None** Extend DXF tags. ### Extended Data (XDATA) Extended data (XDATA) is a DXF tags structure to store arbitrary data in DXF entities. The XDATA is associated to an *AppID* and only one tag list is supported for each AppID per entity. **WARNING:** Low level usage of XDATA is an advanced feature, it is the responsibility of the programmer to create valid XDATA structures. Any errors can invalidate the DXF file! This section shows how to store DXF tags directly in DXF entity but there is also a more user friendly and safer way to store custom XDATA in DXF entities: - • *XDataUserList* - • *XDataUserDict* Use the high level methods of *DXFEntity* to manage XDATA tags. - • *has\_xdata()* - • *get\_xdata()* - • *set\_xdata()* Get XDATA tags as a *ezdxf.lldxf.tags.Tags* data structure, **without** the mandatory first tag (1001, AppID): ``` if entity.has_xdata("EZDXF"): tags = entity.get_xdata("EZDXF") # or use alternatively: try: tags = entity.get_xdata("EZDXF") except DXFValueError: # XDATA for "EZDXF" does not exist ... ``` Set DXF tags as list of (group code, value) tuples or as *ezdxf.lldxf.tags.Tags* data structure, valid DXF tags for XDATA are documented in the section about the *Extended Data* internals. The mandatory first tag (1001, AppID) is inserted automatically if not present. Set only new XDATA tags: ``` if not entity.has_xdata("EZDXF"): entity.set_xdata("EZDXF", [(1000, "MyString")]) ``` Replace or set new XDATA tags: ``` entity.set_xdata("EZDXF", [(1000, "MyString")]) ``` **SEE ALSO:** - • Tutorial: *Storing Custom Data in DXF Files* - • Internals about *Extended Data* tags - • Internal XDATA management class: *XData* - • *DXF R2018 Reference* ### Application-Defined Data (AppData) The application-defined data feature is not very well documented in the DXF reference, so usage as custom data store is not recommended. AutoCAD uses these feature to store the handle to the extension dictionary (*ExtensionDict*) of a DXF entity and the handles to the persistent reactors (*Reactors*) of a DXF entity. Use the high level methods of *DXFEntity* to manage application-defined data tags. - • *has\_app\_data()* - • *get\_app\_data()* - • *set\_app\_data()* - • *discard\_app\_data()* **HINT:** Ezdxf uses special classes to manage the extension dictionary and the reactor handles. These features cannot be accessed by the methods above. Set application-defined data: ``` entity.set_app_data("YOURAPPID", [(1, "DataString")])) ``` Setting the content tags can contain the opening structure tag (102, “{YOURAPPID”) and the closing tag (102, “}”), but doesn’t have to. The returned *Tags* objects does not contain these structure tags. Which tags are valid for application-defined data is not documented. The AppID has to have an entry in the AppID table. Get application-defined data: ``` if entity.has_app_data("YOURAPPID"): tags = entity.get_app_data("YOURAPPID") # tags content is [DXFTag(1, 'DataString')] ``` **SEE ALSO:** - • Internals about *Application-Defined Codes* - • Internal AppData management class: *AppData* ### Extension Dictionary Every entity can have an extension dictionary, which can reference arbitrary DXF objects from the OBJECTS section but not graphical entities. Using this mechanism, several applications can attach data to the same entity. The usage of extension dictionaries is more complex than *Extended Data (XDATA)* but also more flexible with higher capacity for adding data. Use the high level methods of *DXFEntity* to manage extension dictionaries. - • *has\_extension\_dict()* - • *get\_extension\_dict()* - • *new\_extension\_dict()* - • *discard\_extension\_dict()* The main data storage objects referenced by extension dictionaries are: - • *Dictionary*, structural container - • *DictionaryVar*, stores a single string - • *XRecord*, stores arbitrary data **SEE ALSO:** - • Tutorial: *Storing Custom Data in DXF Files* - **class ezdxf.entities.xdict.ExtensionDict** Internal management class for extension dictionaries. **SEE ALSO:** - • Underlying DXF *Dictionary* class - • DXF Internals: *Extension Dictionary* - • *DXF R2018 Reference* - **property is\_alive** Returns **True** if the underlying *Dictionary* object is not deleted. - **\_\_contains\_\_(key: str)** Return *key* in self. - **\_\_getitem\_\_(key: str)** Get self\[key\]. - **\_\_setitem\_\_(key: str, value)** Set self\[key\] to value. Only DXF objects stored in the OBJECTS section are allowed as content of the extension dictionary. DXF entities stored in layouts are not allowed. - **Raises** *DXFTypeError* – invalid DXF type - **\_\_delitem\_\_(key: str)** Delete self\[key\], destroys referenced entity. - **\_\_len\_\_()** Returns count of extension dictionary entries. - **get(key: str, default=None) -\> *DXFEntity* \| None** Return extension dictionary entry *key*. - **keys()** Returns a **KeysView** of all extension dictionary keys. - **items()** Returns an **ItemsView** for all extension dictionary entries as (key, entity) pairs. An entity can be a handle string if the entity does not exist. - **discard(key: str) -\> None** Discard extension dictionary entry *key*. - **add\_dictionary(name: str, hard\_owned: bool = True) -\> *Dictionary*** Create a new *Dictionary* object as extension dictionary entry *name*. - **add\_dictionary\_var(name: str, value: str) -\> *DictionaryVar*** Create a new *DictionaryVar* object as extension dictionary entry *name*. - **add\_xrecord(name: str) -\> *XRecord*** Create a new *XRecord* object as extension dictionary entry *name*. - **link\_dxf\_object(name: str, obj: *DXFObject*) -\> None** Link *obj* to the extension dictionary as entry *name*. Linked objects are owned by the extensions dictionary and therefore cannot be a graphical entity, which have to be owned by a *BaseLayout*. - **Raises** *DXFTypeError* – *obj* has invalid DXF type - **destroy()** Destroy the underlying *Dictionary* object. ### Reactors Persistent reactors are optional object handles of objects registering themselves as reactors on an object. Any DXF object or DXF entity may have reactors. Use the high level methods of *DXFEntity* to manage persistent reactor handles. - • *has\_reactors()* - • *get\_reactors()* - • *set\_reactors()* - • *append\_reactor\_handle()* - • *discard\_reactor\_handle()* *Ezdxf* keeps these reactors only up to date, if this is absolute necessary according to the DXF reference. **SEE ALSO:** - • Internals about *Persistent Reactors* - • Internal Reactors management class: *Reactors* ### Block Reference Management The package *ezdxf* is not designed as a CAD library and does not automatically monitor all internal changes. This enables faster entity processing at the cost of an unknown state of the DXF document. In order to carry out precise BLOCK reference management, i.e. to handle dependencies or to delete unused BLOCK definition, the block reference status (counter) must be acquired explicitly by the package user. All block reference management structures must be explicitly recreated each time the document content is changed. This is not very efficient, but it is safe. **WARNING:** The DXF reference does not document all uses of blocks. The INSERT entity is just one explicit use case, but there are also many indirect block references and the customizability of DXF allows you to store block names and handles in many places. There are some rules for storing names and handles and this module checks all of these known rules, but there is no guarantee that everyone follows these rules. Therefore, it is still possible to destroy a DXF document by deleting an absolutely necessary block definition. Always remember that *ezdxf* is not intended or suitable as a basis for a CAD application! - **class ezdxf.blkrefs.BlockDefinitionIndex(doc: *Drawing*)** Index of all *BlockRecord* entities representing real BLOCK definitions, excluding all *BlockRecord* entities defining model space or paper space layouts. External references (XREF) and XREF overlays are included. - **property block\_records: Iterator\[*BlockRecord*\]** Returns an iterator of all *BlockRecord* entities representing BLOCK definitions. - **rebuild()** Rebuild index from scratch. - **has\_handle(handle: str) -\> bool** Returns **True** if a *BlockRecord* for the given block record handle exist. - **by\_handle(handle: str) -\> *BlockRecord* \| None** Returns the *BlockRecord* for the given block record handle or **None**. - **has\_name(name: str) -\> bool** Returns **True** if a *BlockRecord* for the given block name exist. - **by\_name(name: str) -\> *BlockRecord* \| None** Returns *BlockRecord* for the given block name or **None**. - **class ezdxf.blkrefs.BlockReferenceCounter(doc: *Drawing*, index: *BlockDefinitionIndex* \| None = None)** Counts all block references in a DXF document. Check if a block is referenced by any entity or any resource (DIMSYTLE, MLEADERSTYLE) in a DXF document: ``` import ezdxf from ezdxf.blkrefs import BlockReferenceCounter doc = ezdxf.readfile("your.dxf") counter = BlockReferenceCounter(doc) count = counter.by_name("XYZ") print(f"Block 'XYZ' if referenced {count} times.") ``` - **by\_handle(handle: str) -\> int** Returns the block reference count for a given *BlockRecord* handle. - **by\_name(block\_name: str) -\> int** Returns the block reference count for a given block name. - **ezdxf.blkrefs.find\_unreferenced\_blocks(doc: *Drawing*) -\> set\[str\]** Returns the names of all block definitions without references. **WARNING:** The DXF reference does not document all uses of blocks. The INSERT entity is just one explicit use case, but there are also many indirect block references and the customizability of DXF allows you to store block names and handles in many places. There are some rules for storing names and handles and this module checks all of these known rules, but there is no guarantee that everyone follows these rules. Therefore, it is still possible to destroy a DXF document by deleting an absolutely necessary block definition. Added in version 1.3.5. ### Const The module *ezdxf.lldxf.const*, is also accessible from the **ezdxf** namespace: ``` from ezdxf.lldxf.const import DXF12 import ezdxf print(DXF12) print(ezdxf.const.DXF12) ``` ### DXF Version Strings | | | | | --- | --- | --- | | Name | Version | Alias | | DXF9 | “AC1004” | “R9” | | DXF10 | “AC1006” | “R10” | | DXF12 | “AC1009” | “R12” | | DXF13 | “AC1012” | “R13” | | DXF14 | “AC1014” | “R14” | | DXF2000 | “AC1015” | “R2000” | | DXF2004 | “AC1018” | “R2004” | | DXF2007 | “AC1021” | “R2007” | | DXF2010 | “AC1024” | “R2010” | | DXF2013 | “AC1027” | “R2013” | | DXF2018 | “AC1032” | “R2018” | ### Exceptions - **class ezdxf.lldxf.const.DXFError** Base exception for all *ezdxf* exceptions. - **class ezdxf.lldxf.const.DXFStructureError(DXFError)** - **class ezdxf.lldxf.const.DXFVersionError(DXFError)** Errors related to features not supported by the chosen DXF Version - **class ezdxf.lldxf.const.DXFValueError(DXFError)** - **class ezdxf.lldxf.const.DXFInvalidLineType(DXFValueError)** - **class ezdxf.lldxf.const.DXFBlockInUseError(DXFValueError)** - **class ezdxf.lldxf.const.DXFKeyError(DXFError)** - **class ezdxf.lldxf.const.DXFUndefinedBlockError(DXFKeyError)** - **class ezdxf.lldxf.const.DXFAttributeError(DXFError)** - **class ezdxf.lldxf.const.DXFIndexError(DXFError)** - **class ezdxf.lldxf.const.DXFTypeError(DXFError)** - **class ezdxf.lldxf.const.DXFTableEntryError(DXFValueError)** ### Colors ### Colors Module This module provides functions and constants to manage all kinds of colors in DXF documents. ### Converter Functions - **ezdxf.colors.rgb2int(rgb: *RGB* \| tuple\[int, int, int\]) -\> int** Combined integer value from (r, g, b) tuple. - **ezdxf.colors.int2rgb(value: int) -\> *RGB*** Split RGB integer *value* into (r, g, b) tuple. - **ezdxf.colors.aci2rgb(index: int) -\> *RGB*** Convert *AutoCAD Color Index (ACI)* into (r, g, b) tuple, based on default AutoCAD colors. - **ezdxf.colors.luminance(color: Sequence\[float\]) -\> float** Returns perceived luminance for an RGB color in the range \[0.0, 1.0\] from dark to light. - **ezdxf.colors.decode\_raw\_color(value: int) -\> tuple\[int, int \| *RGB*\]** Decode *raw-color* value as tuple(type, Union\[aci, (r, g, b)\]), the true color value is a (r, g, b) tuple. - **ezdxf.colors.decode\_raw\_color\_int(value: int) -\> tuple\[int, int\]** Decode *raw-color* value as tuple(type, int), the true color value is a 24-bit int value. - **ezdxf.colors.encode\_raw\_color(value: int \| *RGB*) -\> int** Encode *true-color* value or *AutoCAD Color Index (ACI)* color value into a :term: *raw color* value. - **ezdxf.colors.transparency2float(value: int) -\> float** Returns transparency value as float from 0 to 1, 0 for no transparency (opaque) and 1 for 100% transparency. - **Parameters** **value** – DXF integer transparency value, 0 for 100% transparency and 255 for opaque - **ezdxf.colors.float2transparency(value: float) -\> int** Returns DXF transparency value as integer in the range from 0 to 255, where 0 is 100% transparent and 255 is opaque. - **Parameters** **value** – transparency value as float in the range from 0 to 1, where 0 is opaque and 1 is 100% transparent. ### RGB Class - **class ezdxf.colors.RGB(r: int, g: int, b: int)** Named tuple representing an RGB color value. - **r** red channel in range \[0, 255\] - **Type** int - **g** green channel in range \[0, 255\] - **Type** int - **b** blue channel in range \[0, 255\] - **Type** int - **property luminance: float** Returns perceived luminance for an RGB color in range \[0.0, 1.0\] from dark to light. - **to\_hex() -\> str** Returns the color value as hex string “#RRGGBB”. - **classmethod from\_hex(color: str) -\> Self** Returns an *RGB* instance from a hex color string, the *color* string is a hex string “RRGGBB” with an optional leading “#”, an appended alpha channel is ignore. - **to\_floats() -\> tuple\[float, float, float\]** Returns the color value as a tuple of floats in range \[0, 1\]. - **classmethod from\_floats(rgb: tuple\[float, float, float\]) -\> Self** Returns an *RGB* instance from floats in range \[0, 1\]. ### RGBA Class - **class ezdxf.colors.RGBA(r: int, g: int, b: int, a: int = 255)** Named tuple representing an RGBA color value. The default alpha channel is 255 (opaque). - **r** red channel in range \[0, 255\] - **Type** int - **g** green channel in range \[0, 255\] - **Type** int - **b** blue channel in range \[0, 255\] - **Type** int - **a** alpha channel in range \[0, 255\], where 0 is transparent and 255 is opaque - **Type** int - **property luminance: float** Returns perceived luminance for an RGB color in range \[0.0, 1.0\] from dark to light. - **to\_hex() -\> str** Returns the color value as hex string “#RRGGBBAA”. - **classmethod from\_hex(color: str) -\> Self** Returns an *RGBA* instance from a hex color string, the *color* string is a hex string “RRGGBBAA” with an optional leading “#”. The alpha channel is optional. The default alpha channel is 255 (opaque). - **to\_floats() -\> tuple\[float, float, float, float\]** Returns the color value as a tuple of floats in range \[0, 1\]. - **classmethod from\_floats(values: Sequence\[float\]) -\> Self** Returns an *RGBA* instance from floats in range \[0, 1\]. The alpha channel is optional. The default alpha channel is 255 (opaque). ### ACI Color Values Common *AutoCAD Color Index (ACI)* values, also accessible as IntEnum *ezdxf.enums.ACI* | | | | --- | --- | | BYBLOCK | 0 | | BYLAYER | 256 | | BYOBJECT | 257 | | RED | 1 | | YELLOW | 2 | | GREEN | 3 | | CYAN | 4 | | BLUE | 5 | | MAGENTA | 6 | | BLACK (on light background) | 7 | | WHITE (on dark background) | 7 | | GRAY | 8 | | LIGHT\_GRAY | 9 | ### Default Palettes Default color mappings from *AutoCAD Color Index (ACI)* to *true-color* values. | | | | --- | --- | | model space | DXF\_DEFAULT\_COLORS | | paper space | DXF\_DEFAULT\_PAPERSPACE\_COLORS | ### Raw Color Types | | | | --- | --- | | COLOR\_TYPE\_BY\_LAYER | 0xC0 | | COLOR\_TYPE\_BY\_BLOCK | 0xC1 | | COLOR\_TYPE\_RGB | 0xC2 | | COLOR\_TYPE\_ACI | 0xC3 | | COLOR\_TYPE\_WINDOW\_BG | 0xC8 | ### Raw Color Vales | | | | --- | --- | | BY\_LAYER\_RAW\_VALUE | -1073741824 | | BY\_BLOCK\_RAW\_VALUE | -1056964608 | | WINDOW\_BG\_RAW\_VALUE | -939524096 | ### Transparency Values | | | | --- | --- | | OPAQUE | 0x20000FF | | TRANSPARENCY\_10 | 0x20000E5 | | TRANSPARENCY\_20 | 0x20000CC | | TRANSPARENCY\_30 | 0x20000B2 | | TRANSPARENCY\_40 | 0x2000099 | | TRANSPARENCY\_50 | 0x200007F | | TRANSPARENCY\_60 | 0x2000066 | | TRANSPARENCY\_70 | 0x200004C | | TRANSPARENCY\_80 | 0x2000032 | | TRANSPARENCY\_90 | 0x2000019 | | TRANSPARENCY\_BYBLOCK | 0x1000000 | ### Enums ### TextEntityAlignment - **class ezdxf.enums.TextEntityAlignment(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Text alignment enum for the *Text*, *Attrib* and *AttDef* entities. - **LEFT** - **CENTER** - **RIGHT** - **ALIGNED** - **MIDDLE** - **FIT** - **BOTTOM\_LEFT** - **BOTTOM\_CENTER** - **BOTTOM\_RIGHT** - **MIDDLE\_LEFT** - **MIDDLE\_CENTER** - **MIDDLE\_RIGHT** - **TOP\_LEFT** - **TOP\_CENTER** - **TOP\_RIGHT** ### MTextEntityAlignment - **class ezdxf.enums.MTextEntityAlignment(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Text alignment enum for the *MText* entity. - **TOP\_LEFT** - **TOP\_CENTER** - **TOP\_RIGHT** - **MIDDLE\_LEFT** - **MIDDLE\_CENTER** - **MIDDLE\_RIGHT** - **BOTTOM\_LEFT** - **BOTTOM\_CENTER** - **BOTTOM\_RIGHT** ### MTextParagraphAlignment - **class ezdxf.enums.MTextParagraphAlignment(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **DEFAULT** - **LEFT** - **RIGHT** - **CENTER** - **JUSTIFIED** - **DISTRIBUTED** ### MTextFlowDirection - **class ezdxf.enums.MTextFlowDirection(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **LEFT\_TO\_RIGHT** - **TOP\_TO\_BOTTOM** - **BY\_STYLE** ### MTextLineAlignment - **class ezdxf.enums.MTextLineAlignment(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **BOTTOM** - **MIDDLE** - **TOP** ### MTextStroke - **class ezdxf.enums.MTextStroke(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Combination of flags is supported: UNDERLINE + STRIKE\_THROUGH - **UNDERLINE** - **STRIKE\_THROUGH** - **OVERLINE** ### MTextLineSpacing - **class ezdxf.enums.MTextLineSpacing(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **AT\_LEAST** - **EXACT** ### MTextBackgroundColor - **class ezdxf.enums.MTextBackgroundColor(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **OFF** - **COLOR** - **WINDOW** - **CANVAS** ### InsertUnits - **class ezdxf.enums.InsertUnits(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **Unitless** - **Inches** - **Feet** - **Miles** - **Millimeters** - **Centimeters** - **Meters** - **Kilometers** - **Microinches** - **Mils** - **Yards** - **Angstroms** - **Nanometers** - **Microns** - **Decimeters** - **Decameters** - **Hectometers** - **Gigameters** - **AstronomicalUnits** - **Lightyears** - **Parsecs** - **USSurveyFeet** - **USSurveyInch** - **USSurveyYard** - **USSurveyMile** ### Measurement - **class ezdxf.enums.Measurement(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **Imperial** - **Metric** ### LengthUnits - **class ezdxf.enums.LengthUnits(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **Scientific** - **Decimal** - **Engineering** - **Architectural** - **Fractional** ### AngularUnits - **class ezdxf.enums.AngularUnits(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **DecimalDegrees** - **DegreesMinutesSeconds** - **Grad** - **Radians** ### SortEntities - **class ezdxf.enums.SortEntities(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **DISABLE** - **SELECTION** Sorts for object selection - **SNAP** Sorts for object snap - **REDRAW** Sorts for redraws; obsolete - **MSLIDE** Sorts for MSLIDE command slide creation; obsolete - **REGEN** Sorts for REGEN commands - **PLOT** Sorts for plotting - **POSTSCRIPT** Sorts for PostScript output; obsolete ### ACI - **class ezdxf.enums.ACI(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** AutoCAD Color Index - **BYBLOCK** - **BYLAYER** - **BYOBJECT** - **RED** - **YELLOW** - **GREEN** - **CYAN** - **BLUE** - **MAGENTA** - **BLACK** - **WHITE** - **GRAY** - **LIGHT\_GRAY** ### EndCaps - **class ezdxf.enums.EndCaps(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Lineweight end caps setting for new objects. - **NONE** - **ROUND** - **ANGLE** - **SQUARE** ### JoinStyle - **class ezdxf.enums.JoinStyle(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** Lineweight joint setting for new objects. - **NONE** - **ROUND** - **ANGLE** - **FLAT** ### Math ### Core Math core module: *ezdxf.math* These are the core math functions and classes which should be imported from *ezdxf.math*. ### Utility Functions | | | | --- | --- | | *arc\_angle\_span\_deg* | Returns the counter-clockwise angle span from *start* to *end* in degrees. | | *arc\_angle\_span\_rad* | Returns the counter-clockwise angle span from *start* to *end* in radians. | | *arc\_chord\_length* | Returns the chord length for an arc defined by *radius* and the *sagitta*. | | *arc\_segment\_count* | Returns the count of required segments for the approximation of an arc for a given maximum *sagitta*. | | *area* | Returns the area of a polygon. | | *closest\_point* | Returns the closest point to a give *base* point. | | *ellipse\_param\_span* | Returns the counter-clockwise params span of an elliptic arc from start- to end param. | | *has\_matrix\_2d\_stretching* | Returns **True** if matrix *m* performs a non-uniform xy-scaling. | | *has\_matrix\_3d\_stretching* | Returns **True** if matrix *m* performs a non-uniform xyz-scaling. | | *open\_uniform\_knot\_vector* | Returns an open (clamped) uniform knot vector for a B-spline of *order* and *count* control points. | | *required\_knot\_values* | Returns the count of required knot-values for a B-spline of *order* and *count* control points. | | *uniform\_knot\_vector* | Returns an uniform knot vector for a B-spline of *order* and *count* control points. | | *xround* | Extended rounding function. | | *gps\_to\_world\_mercator* | Transform GPS (long/lat) to World Mercator. | | *world\_mercator\_to\_gps* | Transform World Mercator to GPS. | - **ezdxf.math.closest\_point(base: *UVec*, points: Iterable\[*UVec*\]) -\> *Vec3* \| None** Returns the closest point to a give *base* point. - **Parameters** - • **base** – base point as *Vec3* compatible object - • **points** – iterable of points as *Vec3* compatible object - **ezdxf.math.uniform\_knot\_vector(count: int, order: int, normalize=False) -\> list\[float\]** Returns an uniform knot vector for a B-spline of *order* and *count* control points. *order* = degree + 1 - **Parameters** - • **count** – count of control points - • **order** – spline order - • **normalize** – normalize values in range \[0, 1\] if **True** - **ezdxf.math.open\_uniform\_knot\_vector(count: int, order: int, normalize=False) -\> list\[float\]** Returns an open (clamped) uniform knot vector for a B-spline of *order* and *count* control points. *order* = degree + 1 - **Parameters** - • **count** – count of control points - • **order** – spline order - • **normalize** – normalize values in range \[0, 1\] if **True** - **ezdxf.math.required\_knot\_values(count: int, order: int) -\> int** Returns the count of required knot-values for a B-spline of *order* and *count* control points. - **Parameters** - • **count** – count of control points, in text-books referred as “n + 1” - • **order** – order of B-Spline, in text-books referred as “k” Relationship: “p” is the degree of the B-spline, text-book notation. - • k = p + 1 - • 2 ≤ k ≤ n + 1 - **ezdxf.math.xround(value: float, rounding: float = 0.) -\> float** Extended rounding function. The argument *rounding* defines the rounding limit: | | | | --- | --- | | 0 | remove fraction | | 0.1 | round next to x.1, x.2, … x.0 | | 0.25 | round next to x.25, x.50, x.75 or x.00 | | 0.5 | round next to x.5 or x.0 | | 1.0 | round to a multiple of 1: remove fraction | | 2.0 | round to a multiple of 2: xxx2, xxx4, xxx6 … | | 5.0 | round to a multiple of 5: xxx5 or xxx0 | | 10.0 | round to a multiple of 10: xx10, xx20, … | - **Parameters** - • **value** – float value to round - • **rounding** – rounding limit - **ezdxf.math.area(vertices: Iterable\[*UVec*\]) -\> float** Returns the area of a polygon. Returns the projected area in the xy-plane for any vertices (z-axis will be ignored). - **ezdxf.math.arc\_angle\_span\_deg(start: float, end: float) -\> float** Returns the counter-clockwise angle span from *start* to *end* in degrees. Returns the angle span in the range of \[0, 360\], 360 is a full circle. Full circle handling is a special case, because normalization of angles which describe a full circle would return 0 if treated as regular angles. e.g. (0, 360) → 360, (0, -360) → 360, (180, -180) → 360. Input angles with the same value always return 0 by definition: (0, 0) → 0, (-180, -180) → 0, (360, 360) → 0. - **ezdxf.math.arc\_angle\_span\_rad(start: float, end: float) -\> float** Returns the counter-clockwise angle span from *start* to *end* in radians. Returns the angle span in the range of \[0, 2π\], 2π is a full circle. Full circle handling is a special case, because normalization of angles which describe a full circle would return 0 if treated as regular angles. e.g. (0, 2π) → 2π, (0, -2π) → 2π, (π, -π) → 2π. Input angles with the same value always return 0 by definition: (0, 0) → 0, (-π, -π) → 0, (2π, 2π) → 0. - **ezdxf.math.arc\_segment\_count(radius: float, angle: float, sagitta: float) -\> int** Returns the count of required segments for the approximation of an arc for a given maximum *sagitta*. - **Parameters** - • **radius** – arc radius - • **angle** – angle span of the arc in radians - • **sagitta** – max. distance from the center of an arc segment to the center of its chord - **ezdxf.math.arc\_chord\_length(radius: float, sagitta: float) -\> float** Returns the chord length for an arc defined by *radius* and the *sagitta*. - **Parameters** - • **radius** – arc radius - • **sagitta** – distance from the center of the arc to the center of its base - **ezdxf.math.ellipse\_param\_span(start\_param: float, end\_param: float) -\> float** Returns the counter-clockwise params span of an elliptic arc from start- to end param. Returns the param span in the range \[0, 2π\], 2π is a full ellipse. Full ellipse handling is a special case, because normalization of params which describe a full ellipse would return 0 if treated as regular params. e.g. (0, 2π) → 2π, (0, -2π) → 2π, (π, -π) → 2π. Input params with the same value always return 0 by definition: (0, 0) → 0, (-π, -π) → 0, (2π, 2π) → 0. Alias to function: *ezdxf.math.arc\_angle\_span\_rad()* - **ezdxf.math.has\_matrix\_2d\_stretching(m: *Matrix44*) -\> bool** Returns **True** if matrix *m* performs a non-uniform xy-scaling. Uniform scaling is not stretching in this context. Does not check if the target system is a cartesian coordinate system, use the *Matrix44* property *is\_cartesian* for that. - **ezdxf.math.has\_matrix\_3d\_stretching(m: *Matrix44*) -\> bool** Returns **True** if matrix *m* performs a non-uniform xyz-scaling. Uniform scaling is not stretching in this context. Does not check if the target system is a cartesian coordinate system, use the *Matrix44* property *is\_cartesian* for that. - **ezdxf.math.gps\_to\_world\_mercator(longitude: float, latitude: float) -\> tuple\[float, float\]** Transform GPS (long/lat) to World Mercator. Transform WGS84 *EPSG:4326* location given as latitude and longitude in decimal degrees as used by GPS into World Mercator cartesian 2D coordinates in meters *EPSG:3395*. - **Parameters** - • **longitude** – represents the longitude value (East-West) in decimal degrees - • **latitude** – represents the latitude value (North-South) in decimal degrees. Added in version 1.3.0. - **ezdxf.math.world\_mercator\_to\_gps(x: float, y: float, tol: float = 1e-6) -\> tuple\[float, float\]** Transform World Mercator to GPS. Transform WGS84 World Mercator *EPSG:3395* location given as cartesian 2D coordinates x, y in meters into WGS84 decimal degrees as longitude and latitude *EPSG:4326* as used by GPS. - **Parameters** - • **x** – coordinate WGS84 World Mercator - • **y** – coordinate WGS84 World Mercator - • **tol** – accuracy for latitude calculation Added in version 1.3.0. ### Bulge Related Functions | | | | --- | --- | | *arc\_to\_bulge* | Returns bulge parameters from arc parameters. | | *bulge\_3\_points* | Returns bulge value defined by three points. | | *bulge\_center* | Returns center of arc described by the given bulge parameters. | | *bulge\_radius* | Returns radius of arc defined by the given bulge parameters. | | *bulge\_to\_arc* | Returns arc parameters from bulge parameters. | | *bulge\_from\_radius\_and\_chord* | Returns the bulge value for the given arc radius and chord length. | | *bulge\_from\_arc\_angle* | Returns the bulge value for the given arc angle. | **SEE ALSO:** Description of the *Bulge value*. - **ezdxf.math.arc\_to\_bulge(center: *UVec*, start\_angle: float, end\_angle: float, radius: float) -\> tuple\[*Vec2*, *Vec2*, float\]** Returns bulge parameters from arc parameters. - **Parameters** - • **center** – circle center point as *Vec2* compatible object - • **start\_angle** – start angle in radians - • **end\_angle** – end angle in radians - • **radius** – circle radius - **Returns** (start\_point, end\_point, bulge) - **Return type** tuple - **ezdxf.math.bulge\_3\_points(start\_point: *UVec*, end\_point: *UVec*, point: *UVec*) -\> float** Returns bulge value defined by three points. Based on 3-Points to Bulge by *Lee Mac*. - **Parameters** - • **start\_point** – start point as *Vec2* compatible object - • **end\_point** – end point as *Vec2* compatible object - • **point** – arbitrary point as *Vec2* compatible object - **ezdxf.math.bulge\_center(start\_point: *UVec*, end\_point: *UVec*, bulge: float) -\> *Vec2*** Returns center of arc described by the given bulge parameters. Based on Bulge Center by *Lee Mac*. - **Parameters** - • **start\_point** – start point as *Vec2* compatible object - • **end\_point** – end point as *Vec2* compatible object - • **bulge** – bulge value as float - **ezdxf.math.bulge\_radius(start\_point: *UVec*, end\_point: *UVec*, bulge: float) -\> float** Returns radius of arc defined by the given bulge parameters. Based on Bulge Radius by *Lee Mac* - **Parameters** - • **start\_point** – start point as *Vec2* compatible object - • **end\_point** – end point as *Vec2* compatible object - • **bulge** – bulge value - **ezdxf.math.bulge\_to\_arc(start\_point: *UVec*, end\_point: *UVec*, bulge: float) -\> tuple\[*Vec2*, float, float, float\]** Returns arc parameters from bulge parameters. The arcs defined by bulge values of *LWPolyline* and 2D *Polyline* entities start at the vertex which includes the bulge value and ends at the following vertex. **IMPORTANT:** The return values always describe a counter-clockwise oriented arc, so for clockwise arcs (negative bulge values) the start and end angles are swapped and the arc starts at the *end\_point* and ends at the *start\_point*. Based on Bulge to Arc by *Lee Mac*. - **Parameters** - • **start\_point** – start vertex as *Vec2* compatible object - • **end\_point** – end vertex as *Vec2* compatible object - • **bulge** – bulge value - **Returns** (center, start\_angle, end\_angle, radius) - **Return type** Tuple - **ezdxf.math.bulge\_from\_radius\_and\_chord(radius: float, chord: float) -\> float** Returns the bulge value for the given arc radius and chord length. Returns 0 if the radius is zero or the radius is too small for the given chord length to create an arc. - **Parameters** - • **radius** – arc radius - • **chord** – chord length - **ezdxf.math.bulge\_from\_arc\_angle(angle: float) -\> float** Returns the bulge value for the given arc angle. - **Parameters** **angle** – arc angle in radians ### 2D Graphic Functions | | | | --- | --- | | *convex\_hull\_2d* | Returns the 2D convex hull of given *points*. | | *distance\_point\_line\_2d* | Returns the normal distance from *point* to 2D line defined by *start-* and *end* point. | | *intersect\_polylines\_2d* | Returns the intersection points for two polylines as list of *Vec2* objects, the list is empty if no intersection points exist. | | *intersection\_line\_line\_2d* | Compute the intersection of two lines in the xy-plane. | | *is\_axes\_aligned\_rectangle\_2d* | Returns **True** if the given points represent a rectangle aligned with the coordinate system axes. | | *is\_convex\_polygon\_2d* | Returns **True** if the 2D *polygon* is convex. | | *is\_point\_in\_polygon\_2d* | Test if *point* is inside *polygon*. | | *is\_point\_left\_of\_line* | Returns **True** if *point* is "left of line" defined by *start-* and *end* point, a colinear point is also "left of line" if argument *colinear* is **True**. | | *is\_point\_on\_line\_2d* | Returns **True** if *point* is on *line*. | | *offset\_vertices\_2d* | Yields vertices of the offset line to the shape defined by *vertices*. | | *point\_to\_line\_relation* | Returns **-1** if *point* is left *line*, **+1** if *point* is right of *line* and **0** if *point* is on the *line*. | | *rytz\_axis\_construction* | The Rytz’s axis construction is a basic method of descriptive Geometry to find the axes, the semi-major axis and semi-minor axis, starting from two conjugated half-diameters. | - **ezdxf.math.convex\_hull\_2d(points: Iterable\[*UVec*\]) -\> list\[*Vec2*\]** Returns the 2D convex hull of given *points*. Returns a closed polyline, first vertex is equal to the last vertex. - **Parameters** **points** – iterable of points, z-axis is ignored - **ezdxf.math.distance\_point\_line\_2d(point: *Vec2*, start: *Vec2*, end: *Vec2*) -\> float** Returns the normal distance from *point* to 2D line defined by *start-* and *end* point. - **ezdxf.math.intersect\_polylines\_2d(p1: Sequence\[*Vec2*\], p2: Sequence\[*Vec2*\], abs\_tol=1e-10) -\> list\[*Vec2*\]** Returns the intersection points for two polylines as list of *Vec2* objects, the list is empty if no intersection points exist. Does not return self intersection points of *p1* or *p2*. Duplicate intersection points are removed from the result list, but the list does not have a particular order! You can sort the result list by **result.sort()** to introduce an order. - **Parameters** - • **p1** – first polyline as sequence of *Vec2* objects - • **p2** – second polyline as sequence of *Vec2* objects - • **abs\_tol** – absolute tolerance for comparisons - **ezdxf.math.intersection\_line\_line\_2d(line1: Sequence\[*Vec2*\], line2: Sequence\[*Vec2*\], virtual=True, abs\_tol=TOLERANCE) -\> *Vec2* \| None** Compute the intersection of two lines in the xy-plane. - **Parameters** - • **line1** – start- and end point of first line to test e.g. ((x1, y1), (x2, y2)). - • **line2** – start- and end point of second line to test e.g. ((x3, y3), (x4, y4)). - • **virtual** – **True** returns any intersection point, **False** returns only real intersection points. - • **abs\_tol** – tolerance for intersection test. - **Returns** **None** if there is no intersection point (parallel lines) or intersection point as *Vec2* - **ezdxf.math.is\_axes\_aligned\_rectangle\_2d(points: list\[*Vec2*\]) -\> bool** Returns **True** if the given points represent a rectangle aligned with the coordinate system axes. The sides of the rectangle must be parallel to the x- and y-axes of the coordinate system. The rectangle can be open or closed (first point == last point) and oriented clockwise or counter-clockwise. Only works with 4 or 5 vertices, rectangles that have sides with collinear edges are not considered rectangles. Added in version 1.2.0. - **ezdxf.math.is\_convex\_polygon\_2d(polygon: list\[*Vec2*\], \*, strict=False, epsilon=1e-6) -\> bool** Returns **True** if the 2D *polygon* is convex. This function supports open and closed polygons with clockwise or counter-clockwise vertex orientation. Coincident vertices will always be skipped and if argument *strict* is **True**, polygons with collinear vertices are not considered as convex. This solution works only for simple non-self-intersecting polygons! - **ezdxf.math.is\_point\_in\_polygon\_2d(point: *Vec2*, polygon: list\[*Vec2*\], abs\_tol=TOLERANCE) -\> int** Test if *point* is inside *polygon*. Returns +1 for inside, 0 for on the boundary and -1 for outside. Supports convex and concave polygons with clockwise or counter-clockwise oriented polygon vertices. Does not raise an exception for degenerated polygons. - **Parameters** - • **point** – 2D point to test as *Vec2* - • **polygon** – list of 2D points as *Vec2* - • **abs\_tol** – tolerance for distance check - **Returns** \+1 for inside, 0 for on the boundary, -1 for outside - **ezdxf.math.is\_point\_left\_of\_line(point: *Vec2*, start: *Vec2*, end: *Vec2*, colinear=False) -\> bool** Returns **True** if *point* is “left of line” defined by *start-* and *end* point, a colinear point is also “left of line” if argument *colinear* is **True**. - **Parameters** - • **point** – 2D point to test as *Vec2* - • **start** – line definition point as *Vec2* - • **end** – line definition point as *Vec2* - • **colinear** – a colinear point is also “left of line” if **True** - **ezdxf.math.is\_point\_on\_line\_2d(point: *Vec2*, start: *Vec2*, end: *Vec2*, ray=True, abs\_tol=TOLERANCE) -\> bool** Returns **True** if *point* is on *line*. - **Parameters** - • **point** – 2D point to test as *Vec2* - • **start** – line definition point as *Vec2* - • **end** – line definition point as *Vec2* - • **ray** – if **True** point has to be on the infinite ray, if **False** point has to be on the line segment - • **abs\_tol** – tolerance for on the line test - **ezdxf.math.offset\_vertices\_2d(vertices: Iterable\[*UVec*\], offset: float, closed: bool = False) -\> Iterable\[*Vec2*\]** Yields vertices of the offset line to the shape defined by *vertices*. The source shape consist of straight segments and is located in the xy-plane, the z-axis of input vertices is ignored. Takes closed shapes into account if argument *closed* is **True**, which yields intersection of first and last offset segment as first vertex for a closed shape. For closed shapes the first and last vertex can be equal, else an implicit closing segment from last to first vertex is added. A shape with equal first and last vertex is not handled automatically as closed shape. **WARNING:** Adjacent collinear segments in *opposite* directions, same as a turn by 180 degree (U-turn), leads to unexpected results. - **Parameters** - • **vertices** – source shape defined by vertices - • **offset** – line offset perpendicular to direction of shape segments defined by vertices order, offset \> **0** is ‘left’ of line segment, offset \< **0** is ‘right’ of line segment - • **closed** – **True** to handle as closed shape ``` source = [(0, 0), (3, 0), (3, 3), (0, 3)] result = list(offset_vertices_2d(source, offset=0.5, closed=True)) ``` \[image\] Example for a closed collinear shape, which creates 2 additional vertices and the first one has an unexpected location: ``` source = [(0, 0), (0, 1), (0, 2), (0, 3)] result = list(offset_vertices_2d(source, offset=0.5, closed=True)) ``` \[image\] - **ezdxf.math.point\_to\_line\_relation(point: *Vec2*, start: *Vec2*, end: *Vec2*, abs\_tol=TOLERANCE) -\> int** Returns **-1** if *point* is left *line*, **+1** if *point* is right of *line* and **0** if *point* is on the *line*. The *line* is defined by two vertices given as arguments *start* and *end*. - **Parameters** - • **point** – 2D point to test as *Vec2* - • **start** – line definition point as *Vec2* - • **end** – line definition point as *Vec2* - • **abs\_tol** – tolerance for minimum distance to line - **ezdxf.math.rytz\_axis\_construction(d1: *Vec3*, d2: *Vec3*) -\> tuple\[*Vec3*, *Vec3*, float\]** The Rytz’s axis construction is a basic method of descriptive Geometry to find the axes, the semi-major axis and semi-minor axis, starting from two conjugated half-diameters. Source: *Wikipedia* Given conjugated diameter *d1* is the vector from center C to point P and the given conjugated diameter *d2* is the vector from center C to point Q. Center of ellipse is always **(0, 0, 0)**. This algorithm works for 2D/3D vectors. - **Parameters** - • **d1** – conjugated semi-major axis as *Vec3* - • **d2** – conjugated semi-minor axis as *Vec3* - **Returns** Tuple of (major axis, minor axis, ratio) ### 3D Graphic Functions | | | | --- | --- | | *basic\_transformation* | Returns a combined transformation matrix for translation, scaling and rotation about the z-axis. | | *best\_fit\_normal* | Returns the "best fit" normal for a plane defined by three or more vertices. | | *bezier\_to\_bspline* | Convert multiple quadratic or cubic Bèzier curves into a single cubic B-spline. | | *closed\_uniform\_bspline* | Creates a closed uniform (periodic) *B-spline* curve (*open curve*). | | *cubic\_bezier\_bbox* | Returns the *BoundingBox* of a cubic Bézier curve of type *Bezier4P*. | | *cubic\_bezier\_from\_3p* | Returns a cubic Bèzier curve *Bezier4P* from three points. | | *cubic\_bezier\_from\_arc* | Returns an approximation for a circular 2D arc by multiple cubic Bézier-curves. | | *cubic\_bezier\_from\_ellipse* | Returns an approximation for an elliptic arc by multiple cubic Bézier-curves. | | *cubic\_bezier\_interpolation* | Returns an interpolation curve for given data *points* as multiple cubic Bézier-curves. | | *distance\_point\_line\_3d* | Returns the normal distance from a *point* to a 3D line. | | *estimate\_end\_tangent\_magnitude* | Estimate tangent magnitude of start- and end tangents. | | *estimate\_tangents* | Estimate tangents for curve defined by given fit points. | | *fit\_points\_to\_cad\_cv* | Returns a cubic *BSpline* from fit points as close as possible to common CAD applications like BricsCAD. | | *fit\_points\_to\_cubic\_bezier* | Returns a cubic *BSpline* from fit points **without** end tangents. | | *global\_bspline\_interpolation* | *B-spline* interpolation by the *Global Curve Interpolation*. | | *have\_bezier\_curves\_g1\_continuity* | Return **True** if the given adjacent Bézier curves have G1 continuity. | | *intersect\_polylines\_3d* | Returns the intersection points for two polylines as list of *Vec3* objects, the list is empty if no intersection points exist. | | *intersection\_line\_line\_3d* | Returns the intersection point of two 3D lines, returns **None** if lines do not intersect. | | *intersection\_line\_polygon\_3d* | Returns the intersection point of the 3D line form *start* to *end* and the given *polygon*. | | *intersection\_ray\_polygon\_3d* | Returns the intersection point of the infinite 3D ray defined by *origin* and the *direction* vector and the given *polygon*. | | *intersection\_ray\_ray\_3d* | Calculate intersection of two 3D rays, returns a 0-tuple for parallel rays, a 1-tuple for intersecting rays and a 2-tuple for not intersecting and not parallel rays with points of the closest approach on each ray. | | *is\_planar\_face* | Returns **True** if sequence of vectors is a planar face. | | *is\_vertex\_order\_ccw\_3d* | Returns **True** when the given 3D vertices have a counter-clockwise order around the given normal vector. | | *linear\_vertex\_spacing* | Returns *count* evenly spaced vertices from *start* to *end*. | | *local\_cubic\_bspline\_interpolation* | *B-spline* interpolation by 'Local Cubic Curve Interpolation', which creates B-spline from fit points and estimated tangent direction at start-, end- and passing points. | | *normal\_vector\_3p* | Returns normal vector for 3 points, which is the normalized cross product for: **a-\>b x a-\>c**. | | *open\_uniform\_bspline* | Creates an open uniform (periodic) *B-spline* curve (*open curve*). | | *quadratic\_bezier\_bbox* | Returns the *BoundingBox* of a quadratic Bézier curve of type *Bezier3P*. | | *quadratic\_bezier\_from\_3p* | Returns a quadratic Bèzier curve *Bezier3P* from three points. | | *quadratic\_to\_cubic\_bezier* | Convert quadratic Bèzier curves (*ezdxf.math.Bezier3P*) into cubic Bèzier curves (*ezdxf.math.Bezier4P*). | | *rational\_bspline\_from\_arc* | Returns a rational B-splines for a circular 2D arc. | | *rational\_bspline\_from\_ellipse* | Returns a rational B-splines for an elliptic arc. | | *safe\_normal\_vector* | Safe function to detect the normal vector for a face or polygon defined by 3 or more *vertices*. | | *spherical\_envelope* | Calculate the spherical envelope for the given points. | | *split\_bezier* | Split a Bèzier curve at parameter *t*. | | *split\_polygon\_by\_plane* | Split a convex *polygon* by the given *plane*. | | *subdivide\_face* | Subdivides faces by subdividing edges and adding a center vertex. | | *subdivide\_ngons* | Subdivides faces into triangles by adding a center vertex. | **SEE ALSO:** The free online book *3D Math Primer for Graphics and Game Development* is a very good resource for learning vector math and other graphic related topics, it is easy to read for beginners and especially targeted to programmers. - **ezdxf.math.basic\_transformation(move: *UVec* = (0, 0, 0), scale: *UVec* = (1, 1, 1), z\_rotation: float = 0) -\> *Matrix44*** Returns a combined transformation matrix for translation, scaling and rotation about the z-axis. - **Parameters** - • **move** – translation vector - • **scale** – x-, y- and z-axis scaling as float triplet, e.g. (2, 2, 1) - • **z\_rotation** – rotation angle about the z-axis in radians - **ezdxf.math.best\_fit\_normal(vertices: Iterable\[*UVec*\]) -\> *Vec3*** Returns the “best fit” normal for a plane defined by three or more vertices. This function tolerates imperfect plane vertices. Safe function to detect the extrusion vector of flat arbitrary polygons. - **ezdxf.math.bezier\_to\_bspline(curves: Iterable\[*Bezier3P* \| *Bezier4P*\]) -\> *BSpline*** Convert multiple quadratic or cubic Bèzier curves into a single cubic B-spline. For good results the curves must be lined up seamlessly, i.e. the starting point of the following curve must be the same as the end point of the previous curve. G1 continuity or better at the connection points of the Bézier curves is required to get best results. - **ezdxf.math.closed\_uniform\_bspline(control\_points: Iterable\[*UVec*\], order: int = 4, weights: Iterable\[float\] \| None = None) -\> *BSpline*** Creates a closed uniform (periodic) *B-spline* curve (*open curve*). This B-spline does not pass any of the control points. - **Parameters** - • **control\_points** – iterable of control points as *Vec3* compatible objects - • **order** – spline order (degree + 1) - • **weights** – iterable of weight values - **ezdxf.math.cubic\_bezier\_bbox(curve: *Bezier4P*, \*, abs\_tol=1e-12) -\> *BoundingBox*** Returns the *BoundingBox* of a cubic Bézier curve of type *Bezier4P*. - **ezdxf.math.cubic\_bezier\_from\_3p(p1: *UVec*, p2: *UVec*, p3: *UVec*) -\> *Bezier4P*** Returns a cubic Bèzier curve *Bezier4P* from three points. The curve starts at *p1*, goes through *p2* and ends at *p3*. (source: *pomax-2*) - **ezdxf.math.cubic\_bezier\_from\_arc(center: *UVec* = (0, 0, 0), radius: float = 1, start\_angle: float = 0, end\_angle: float = 360, segments: int = 1) -\> Iterator\[*Bezier4P*\[*Vec3*\]\]** Returns an approximation for a circular 2D arc by multiple cubic Bézier-curves. - **Parameters** - • **center** – circle center as *Vec3* compatible object - • **radius** – circle radius - • **start\_angle** – start angle in degrees - • **end\_angle** – end angle in degrees - • **segments** – count of Bèzier-curve segments, at least one segment for each quarter (90 deg), 1 for as few as possible. - **ezdxf.math.cubic\_bezier\_from\_ellipse(ellipse: *ConstructionEllipse*, segments: int = 1) -\> Iterator\[*Bezier4P*\[*Vec3*\]\]** Returns an approximation for an elliptic arc by multiple cubic Bézier-curves. - **Parameters** - • **ellipse** – ellipse parameters as *ConstructionEllipse* object - • **segments** – count of Bèzier-curve segments, at least one segment for each quarter (π/2), 1 for as few as possible. - **ezdxf.math.cubic\_bezier\_interpolation(points: Iterable\[*UVec*\]) -\> Iterable\[*Bezier4P*\[*Vec3*\]\]** Returns an interpolation curve for given data *points* as multiple cubic Bézier-curves. Returns n-1 cubic Bézier-curves for n given data points, curve i goes from point\[i\] to point\[i+1\]. - **Parameters** **points** – data points - **ezdxf.math.distance\_point\_line\_3d(point: *Vec3*, start: *Vec3*, end: *Vec3*) -\> float** Returns the normal distance from a *point* to a 3D line. - **Parameters** - • **point** – point to test - • **start** – start point of the 3D line - • **end** – end point of the 3D line - **ezdxf.math.estimate\_end\_tangent\_magnitude(points: list\[*Vec3*\], method: str = 'chord') -\> tuple\[float, float\]** Estimate tangent magnitude of start- and end tangents. Available estimation methods: - • “chord”: total chord length, curve approximation by straight segments - • “arc”: total arc length, curve approximation by arcs - • “bezier-n”: total length from cubic bezier curve approximation, n segments per section - **Parameters** - • **points** – start-, end- and passing points of curve - • **method** – tangent magnitude estimation method - **ezdxf.math.estimate\_tangents(points: list\[*Vec3*\], method: str = '5-points', normalize=True) -\> list\[*Vec3*\]** Estimate tangents for curve defined by given fit points. Calculated tangents are normalized (unit-vectors). Available tangent estimation methods: - • “3-points”: 3 point interpolation - • “5-points”: 5 point interpolation - • “bezier”: tangents from an interpolated cubic bezier curve - • “diff”: finite difference - **Parameters** - • **points** – start-, end- and passing points of curve - • **method** – tangent estimation method - • **normalize** – normalize tangents if **True** - **Returns** tangents as list of *Vec3* objects - **ezdxf.math.fit\_points\_to\_cad\_cv(fit\_points: Iterable\[*UVec*\], tangents: Iterable\[*UVec*\] \| None = None) -\> *BSpline*** Returns a cubic *BSpline* from fit points as close as possible to common CAD applications like BricsCAD. There exist infinite numerical correct solution for this setup, but some facts are known: - • CAD applications use the global curve interpolation with start- and end derivatives if the end tangents are defined otherwise the equation system will be completed by setting the second derivatives of the start and end point to 0, for more information read this answer on stackoverflow: *https://stackoverflow.com/a/74863330/6162864* - • The degree of the B-spline is always 3 regardless which degree is stored in the SPLINE entity, this is only valid for B-splines defined by fit points - • Knot parametrization method is “chord” - • Knot distribution is “natural” - **Parameters** - • **fit\_points** – points the spline is passing through - • **tangents** – start- and end tangent, default is autodetect - **ezdxf.math.fit\_points\_to\_cubic\_bezier(fit\_points: Iterable\[*UVec*\]) -\> *BSpline*** Returns a cubic *BSpline* from fit points **without** end tangents. This function uses the cubic Bèzier interpolation to create multiple Bèzier curves and combine them into a single B-spline, this works for short simple splines better than the *fit\_points\_to\_cad\_cv()*, but is worse for longer and more complex splines. - **Parameters** **fit\_points** – points the spline is passing through - **ezdxf.math.global\_bspline\_interpolation(fit\_points: Iterable\[*UVec*\], degree: int = 3, tangents: Iterable\[*UVec*\] \| None = None, method: str = 'chord') -\> *BSpline*** *B-spline* interpolation by the *Global Curve Interpolation*. Given are the fit points and the degree of the B-spline. The function provides 3 methods for generating the parameter vector t: - • “uniform”: creates a uniform t vector, from 0 to 1 evenly spaced, see *uniform* method - • “chord”, “distance”: creates a t vector with values proportional to the fit point distances, see *chord length* method - • “centripetal”, “sqrt\_chord”: creates a t vector with values proportional to the fit point sqrt(distances), see *centripetal* method - • “arc”: creates a t vector with values proportional to the arc length between fit points. It is possible to constraint the curve by tangents, by start- and end tangent if only two tangents are given or by one tangent for each fit point. If tangents are given, they represent 1st derivatives and should be scaled if they are unit vectors, if only start- and end tangents given the function *estimate\_end\_tangent\_magnitude()* helps with an educated guess, if all tangents are given, scaling by chord length is a reasonable choice (Piegl & Tiller). - **Parameters** - • **fit\_points** – fit points of B-spline, as list of *Vec3* compatible objects - • **tangents** – if only two vectors are given, take the first and the last vector as start- and end tangent constraints or if for all fit points a tangent is given use all tangents as interpolation constraints (optional) - • **degree** – degree of B-spline - • **method** – calculation method for parameter vector t - **Returns** *BSpline* - **ezdxf.math.have\_bezier\_curves\_g1\_continuity(b1: *Bezier3P* \| *Bezier4P*, b2: *Bezier3P* \| *Bezier4P*, g1\_tol: float = 1e-4) -\> bool** Return **True** if the given adjacent Bézier curves have G1 continuity. - **ezdxf.math.intersect\_polylines\_3d(p1: Sequence\[*Vec3*\], p2: Sequence\[*Vec3*\], abs\_tol=1e-10) -\> list\[*Vec3*\]** Returns the intersection points for two polylines as list of *Vec3* objects, the list is empty if no intersection points exist. Does not return self intersection points of *p1* or *p2*. Duplicate intersection points are removed from the result list, but the list does not have a particular order! You can sort the result list by **result.sort()** to introduce an order. - **Parameters** - • **p1** – first polyline as sequence of *Vec3* objects - • **p2** – second polyline as sequence of *Vec3* objects - • **abs\_tol** – absolute tolerance for comparisons - **ezdxf.math.intersection\_line\_line\_3d(line1: Sequence\[*Vec3*\], line2: Sequence\[*Vec3*\], virtual: bool = True, abs\_tol: float = 1e-10) -\> *Vec3* \| None** Returns the intersection point of two 3D lines, returns **None** if lines do not intersect. - **Parameters** - • **line1** – first line as tuple of two points as *Vec3* objects - • **line2** – second line as tuple of two points as *Vec3* objects - • **virtual** – **True** returns any intersection point, **False** returns only real intersection points - • **abs\_tol** – absolute tolerance for comparisons - **ezdxf.math.intersection\_line\_polygon\_3d(start: *Vec3*, end: *Vec3*, polygon: Iterable\[*Vec3*\], \*, coplanar=True, boundary=True, abs\_tol=PLANE\_EPSILON) -\> *Vec3* \| None** Returns the intersection point of the 3D line form *start* to *end* and the given *polygon*. - **Parameters** - • **start** – start point of 3D line as *Vec3* - • **end** – end point of 3D line as *Vec3* - • **polygon** – 3D polygon as iterable of *Vec3* - • **coplanar** – if **True** a coplanar start- or end point as intersection point is valid - • **boundary** – if **True** an intersection point at the polygon boundary line is valid - • **abs\_tol** – absolute tolerance for comparisons - **ezdxf.math.intersection\_ray\_polygon\_3d(origin: *Vec3*, direction: *Vec3*, polygon: Iterable\[*Vec3*\], \*, boundary=True, abs\_tol=PLANE\_EPSILON) -\> *Vec3* \| None** Returns the intersection point of the infinite 3D ray defined by *origin* and the *direction* vector and the given *polygon*. - **Parameters** - • **origin** – origin point of the 3D ray as *Vec3* - • **direction** – direction vector of the 3D ray as *Vec3* - • **polygon** – 3D polygon as iterable of *Vec3* - • **boundary** – if **True** intersection points at the polygon boundary line are valid - • **abs\_tol** – absolute tolerance for comparisons - **ezdxf.math.intersection\_ray\_ray\_3d(ray1: Sequence\[*Vec3*\], ray2: Sequence\[*Vec3*\], abs\_tol=TOLERANCE) -\> Sequence\[*Vec3*\]** Calculate intersection of two 3D rays, returns a 0-tuple for parallel rays, a 1-tuple for intersecting rays and a 2-tuple for not intersecting and not parallel rays with points of the closest approach on each ray. - **Parameters** - • **ray1** – first ray as tuple of two points as *Vec3* objects - • **ray2** – second ray as tuple of two points as *Vec3* objects - • **abs\_tol** – absolute tolerance for comparisons - **ezdxf.math.is\_planar\_face(face: Sequence\[*Vec3*\], abs\_tol=1e-9) -\> bool** Returns **True** if sequence of vectors is a planar face. - **Parameters** - • **face** – sequence of *Vec3* objects - • **abs\_tol** – tolerance for normals check - **ezdxf.math.is\_vertex\_order\_ccw\_3d(vertices: list\[*Vec3*\], normal: *Vec3*) -\> bool** Returns **True** when the given 3D vertices have a counter-clockwise order around the given normal vector. Works for convex and concave shapes. Does not check or care if all vertices are located in a flat plane or if the normal vector is really perpendicular to the shape, but the result may be incorrect in that cases. - **Parameters** - • **vertices** (*list*) – corner vertices of a flat shape (polygon) - • **normal** (*Vec3*) – normal vector of the shape - **Raises** **ValueError** – input has less than 3 vertices - **ezdxf.math.linear\_vertex\_spacing(start: *Vec3*, end: *Vec3*, count: int) -\> list\[*Vec3*\]** Returns *count* evenly spaced vertices from *start* to *end*. - **ezdxf.math.local\_cubic\_bspline\_interpolation(fit\_points: Iterable\[*UVec*\], method: str = '5-points', tangents: Iterable\[*UVec*\] \| None = None) -\> *BSpline*** *B-spline* interpolation by ‘Local Cubic Curve Interpolation’, which creates B-spline from fit points and estimated tangent direction at start-, end- and passing points. Source: Piegl & Tiller: “The NURBS Book” - chapter 9.3.4 Available tangent estimation methods: - • “3-points”: 3 point interpolation - • “5-points”: 5 point interpolation - • “bezier”: cubic bezier curve interpolation - • “diff”: finite difference or pass pre-calculated tangents, which overrides tangent estimation. - **Parameters** - • **fit\_points** – all B-spline fit points as *Vec3* compatible objects - • **method** – tangent estimation method - • **tangents** – tangents as *Vec3* compatible objects (optional) - **Returns** *BSpline* - **ezdxf.math.normal\_vector\_3p(a: *Vec3*, b: *Vec3*, c: *Vec3*) -\> *Vec3*** Returns normal vector for 3 points, which is the normalized cross product for: **a-\>b x a-\>c**. - **ezdxf.math.open\_uniform\_bspline(control\_points: Iterable\[*UVec*\], order: int = 4, weights: Iterable\[float\] \| None = None) -\> *BSpline*** Creates an open uniform (periodic) *B-spline* curve (*open curve*). This is an unclamped curve, which means the curve passes none of the control points. - **Parameters** - • **control\_points** – iterable of control points as *Vec3* compatible objects - • **order** – spline order (degree + 1) - • **weights** – iterable of weight values - **ezdxf.math.quadratic\_bezier\_bbox(curve: *Bezier3P*, \*, abs\_tol=1e-12) -\> *BoundingBox*** Returns the *BoundingBox* of a quadratic Bézier curve of type *Bezier3P*. - **ezdxf.math.quadratic\_bezier\_from\_3p(p1: *UVec*, p2: *UVec*, p3: *UVec*) -\> *Bezier3P*** Returns a quadratic Bèzier curve *Bezier3P* from three points. The curve starts at *p1*, goes through *p2* and ends at *p3*. (source: *pomax-2*) - **ezdxf.math.quadratic\_to\_cubic\_bezier(curve: *Bezier3P*) -\> *Bezier4P*** Convert quadratic Bèzier curves (*ezdxf.math.Bezier3P*) into cubic Bèzier curves (*ezdxf.math.Bezier4P*). - **ezdxf.math.rational\_bspline\_from\_arc(center: *Vec3* = (0, 0), radius: float = 1, start\_angle: float = 0, end\_angle: float = 360, segments: int = 1) -\> *BSpline*** Returns a rational B-splines for a circular 2D arc. - **Parameters** - • **center** – circle center as *Vec3* compatible object - • **radius** – circle radius - • **start\_angle** – start angle in degrees - • **end\_angle** – end angle in degrees - • **segments** – count of spline segments, at least one segment for each quarter (90 deg), default is 1, for as few as needed. - **ezdxf.math.rational\_bspline\_from\_ellipse(ellipse: *ConstructionEllipse*, segments: int = 1) -\> *BSpline*** Returns a rational B-splines for an elliptic arc. - **Parameters** - • **ellipse** – ellipse parameters as *ConstructionEllipse* object - • **segments** – count of spline segments, at least one segment for each quarter (π/2), default is 1, for as few as needed. - **ezdxf.math.safe\_normal\_vector(vertices: Sequence\[*Vec3*\]) -\> *Vec3*** Safe function to detect the normal vector for a face or polygon defined by 3 or more *vertices*. - **ezdxf.math.spherical\_envelope(points: Sequence\[*UVec*\]) -\> tuple\[*Vec3*, float\]** Calculate the spherical envelope for the given points. Returns the centroid (a.k.a. geometric center) and the radius of the enclosing sphere. **NOTE:** The result does not represent the minimal bounding sphere! - **ezdxf.math.split\_bezier(control\_points: Sequence\[T\], t: float) -\> tuple\[list\[T\], list\[T\]\]** Split a Bèzier curve at parameter *t*. Returns the control points for two new Bèzier curves of the same degree and type as the input curve. (source: *pomax-1*) - **Parameters** - • **control\_points** – of the Bèzier curve as *Vec2* or *Vec3* objects. Requires 3 points for a quadratic curve, 4 points for a cubic curve , … - • **t** – parameter where to split the curve in the range \[0, 1\] - **ezdxf.math.split\_polygon\_by\_plane(polygon: Iterable\[*Vec3*\], plane: *Plane*, \*, coplanar=True, abs\_tol=PLANE\_EPSILON) -\> tuple\[Sequence\[*Vec3*\], Sequence\[*Vec3*\]\]** Split a convex *polygon* by the given *plane*. Returns a tuple of front- and back vertices (front, back). Returns also coplanar polygons if the argument *coplanar* is **True**, the coplanar vertices goes into either front or back depending on their orientation with respect to this plane. - **ezdxf.math.subdivide\_face(face: Sequence\[*Vec3*\], quads: bool = True) -\> Iterator\[Sequence\[*Vec3*\]\]** Subdivides faces by subdividing edges and adding a center vertex. - **Parameters** - • **face** – a sequence of *Vec3* - • **quads** – create quad faces if **True** else create triangles - **ezdxf.math.subdivide\_ngons(faces: Iterable\[Sequence\[*Vec3*\]\], max\_vertex\_count=4) -\> Iterator\[Sequence\[*Vec3*\]\]** Subdivides faces into triangles by adding a center vertex. - **Parameters** - • **faces** – iterable of faces as sequence of *Vec3* - • **max\_vertex\_count** – subdivide only ngons with more vertices ### Transformation Classes | | | | --- | --- | | *Matrix44* | An optimized 4x4 *transformation matrix*. | | *OCS* | Establish an *OCS* for a given extrusion vector. | | *UCS* | Establish a user coordinate system (*UCS*). | ### OCS Class - **class ezdxf.math.OCS(extrusion: *UVec* = Z\_AXIS)** Establish an *OCS* for a given extrusion vector. - **Parameters** **extrusion** – extrusion vector. - **ux** x-axis unit vector - **uy** y-axis unit vector - **uz** z-axis unit vector - **from\_wcs(point: *UVec*) -\> *Vec3*** Returns OCS vector for WCS *point*. - **points\_from\_wcs(points: Iterable\[*UVec*\]) -\> Iterator\[*Vec3*\]** Returns iterable of OCS vectors from WCS *points*. - **to\_wcs(point: *UVec*) -\> *Vec3*** Returns WCS vector for OCS *point*. - **points\_to\_wcs(points: Iterable\[*UVec*\]) -\> Iterator\[*Vec3*\]** Returns iterable of WCS vectors for OCS *points*. - **render\_axis(layout: *BaseLayout*, length: float = 1, colors: *RGB* = RGB(1, 3, 5)) -\> None** Render axis as 3D lines into a *layout*. ### UCS Class - **class ezdxf.math.UCS(origin: *UVec* = (0, 0, 0), ux: *UVec* \| None = None, uy: *UVec* \| None = None, uz: *UVec* \| None = None)** Establish a user coordinate system (*UCS*). The UCS is defined by the origin and two unit vectors for the x-, y- or z-axis, all axis in *WCS*. The missing axis is the cross product of the given axis. If x- and y-axis are **None**: ux = **(1, 0, 0)**, uy = **(0, 1, 0)**, uz = **(0, 0, 1)**. Unit vectors don’t have to be normalized, normalization is done at initialization, this is also the reason why scaling gets lost by copying or rotating. - **Parameters** - • **origin** – defines the UCS origin in world coordinates - • **ux** – defines the UCS x-axis as vector in *WCS* - • **uy** – defines the UCS y-axis as vector in *WCS* - • **uz** – defines the UCS z-axis as vector in *WCS* - **ux** x-axis unit vector - **uy** y-axis unit vector - **uz** z-axis unit vector - **is\_cartesian** Returns **True** if cartesian coordinate system. - **copy() -\> *UCS*** Returns a copy of this UCS. - **to\_wcs(point: *Vec3*) -\> *Vec3*** Returns WCS point for UCS *point*. - **points\_to\_wcs(points: Iterable\[*Vec3*\]) -\> Iterator\[*Vec3*\]** Returns iterable of WCS vectors for UCS *points*. - **direction\_to\_wcs(vector: *Vec3*) -\> *Vec3*** Returns WCS direction for UCS *vector* without origin adjustment. - **from\_wcs(point: *Vec3*) -\> *Vec3*** Returns UCS point for WCS *point*. - **points\_from\_wcs(points: Iterable\[*Vec3*\]) -\> Iterator\[*Vec3*\]** Returns iterable of UCS vectors from WCS *points*. - **direction\_from\_wcs(vector: *Vec3*) -\> *Vec3*** Returns UCS vector for WCS *vector* without origin adjustment. - **to\_ocs(point: *Vec3*) -\> *Vec3*** Returns OCS vector for UCS *point*. The *OCS* is defined by the z-axis of the *UCS*. - **points\_to\_ocs(points: Iterable\[*Vec3*\]) -\> Iterator\[*Vec3*\]** Returns iterable of OCS vectors for UCS *points*. The *OCS* is defined by the z-axis of the *UCS*. - **Parameters** **points** – iterable of UCS vertices - **to\_ocs\_angle\_deg(angle: float) -\> float** Transforms *angle* from current UCS to the parent coordinate system (most likely the WCS) including the transformation to the OCS established by the extrusion vector *UCS.uz*. - **Parameters** **angle** – in UCS in degrees - **transform(m: *Matrix44*) -\> *UCS*** General inplace transformation interface, returns *self* (floating interface). - **Parameters** **m** – 4x4 transformation matrix (*ezdxf.math.Matrix44*) - **rotate(axis: *UVec*, angle: float) -\> *UCS*** Returns a new rotated UCS, with the same origin as the source UCS. The rotation vector is located in the origin and has *WCS* coordinates e.g. (0, 0, 1) is the WCS z-axis as rotation vector. - **Parameters** - • **axis** – arbitrary rotation axis as vector in *WCS* - • **angle** – rotation angle in radians - **rotate\_local\_x(angle: float) -\> *UCS*** Returns a new rotated UCS, rotation axis is the local x-axis. - **Parameters** **angle** – rotation angle in radians - **rotate\_local\_y(angle: float) -\> *UCS*** Returns a new rotated UCS, rotation axis is the local y-axis. - **Parameters** **angle** – rotation angle in radians - **rotate\_local\_z(angle: float) -\> *UCS*** Returns a new rotated UCS, rotation axis is the local z-axis. - **Parameters** **angle** – rotation angle in radians - **shift(delta: *UVec*) -\> *UCS*** Shifts current UCS by *delta* vector and returns *self*. - **Parameters** **delta** – shifting vector - **moveto(location: *UVec*) -\> *UCS*** Place current UCS at new origin *location* and returns *self*. - **Parameters** **location** – new origin in WCS - **static from\_x\_axis\_and\_point\_in\_xy(origin: *UVec*, axis: *UVec*, point: *UVec*) -\> *UCS*** Returns a new *UCS* defined by the origin, the x-axis vector and an arbitrary point in the xy-plane. - **Parameters** - • **origin** – UCS origin as (x, y, z) tuple in *WCS* - • **axis** – x-axis vector as (x, y, z) tuple in *WCS* - • **point** – arbitrary point unlike the origin in the xy-plane as (x, y, z) tuple in *WCS* - **static from\_x\_axis\_and\_point\_in\_xz(origin: *UVec*, axis: *UVec*, point: *UVec*) -\> *UCS*** Returns a new *UCS* defined by the origin, the x-axis vector and an arbitrary point in the xz-plane. - **Parameters** - • **origin** – UCS origin as (x, y, z) tuple in *WCS* - • **axis** – x-axis vector as (x, y, z) tuple in *WCS* - • **point** – arbitrary point unlike the origin in the xz-plane as (x, y, z) tuple in *WCS* - **static from\_y\_axis\_and\_point\_in\_xy(origin: *UVec*, axis: *UVec*, point: *UVec*) -\> *UCS*** Returns a new *UCS* defined by the origin, the y-axis vector and an arbitrary point in the xy-plane. - **Parameters** - • **origin** – UCS origin as (x, y, z) tuple in *WCS* - • **axis** – y-axis vector as (x, y, z) tuple in *WCS* - • **point** – arbitrary point unlike the origin in the xy-plane as (x, y, z) tuple in *WCS* - **static from\_y\_axis\_and\_point\_in\_yz(origin: *UVec*, axis: *UVec*, point: *UVec*) -\> *UCS*** Returns a new *UCS* defined by the origin, the y-axis vector and an arbitrary point in the yz-plane. - **Parameters** - • **origin** – UCS origin as (x, y, z) tuple in *WCS* - • **axis** – y-axis vector as (x, y, z) tuple in *WCS* - • **point** – arbitrary point unlike the origin in the yz-plane as (x, y, z) tuple in *WCS* - **static from\_z\_axis\_and\_point\_in\_xz(origin: *UVec*, axis: *UVec*, point: *UVec*) -\> *UCS*** Returns a new *UCS* defined by the origin, the z-axis vector and an arbitrary point in the xz-plane. - **Parameters** - • **origin** – UCS origin as (x, y, z) tuple in *WCS* - • **axis** – z-axis vector as (x, y, z) tuple in *WCS* - • **point** – arbitrary point unlike the origin in the xz-plane as (x, y, z) tuple in *WCS* - **static from\_z\_axis\_and\_point\_in\_yz(origin: *UVec*, axis: *UVec*, point: *UVec*) -\> *UCS*** Returns a new *UCS* defined by the origin, the z-axis vector and an arbitrary point in the yz-plane. - **Parameters** - • **origin** – UCS origin as (x, y, z) tuple in *WCS* - • **axis** – z-axis vector as (x, y, z) tuple in *WCS* - • **point** – arbitrary point unlike the origin in the yz-plane as (x, y, z) tuple in *WCS* - **render\_axis(layout: *BaseLayout*, length: float = 1, colors: *RGB* = RGB(1, 3, 5))** Render axis as 3D lines into a *layout*. ### Matrix44 - **class ezdxf.math.Matrix44(\*args)** An optimized 4x4 *transformation matrix*. The utility functions for constructing transformations and transforming vectors and points assumes that vectors are stored as row vectors, meaning when multiplied, transformations are applied left to right (e.g. vAB transforms v by A then by B). Matrix44 initialization: - • **Matrix44()** returns the identity matrix. - • **Matrix44(values)** values is an iterable with the 16 components of the matrix. - • **Matrix44(row1, row2, row3, row4)** four rows, each row with four values. - **\_\_repr\_\_() -\> str** Returns the representation string of the matrix in row-major order: **Matrix44((col0, col1, col2, col3), (...), (...), (...))** - **get\_row(row: int) -\> tuple\[float, ...\]** Get row as list of four float values. - **Parameters** **row** – row index \[0 .. 3\] - **set\_row(row: int, values: Sequence\[float\]) -\> None** Sets the values in a row. - **Parameters** - • **row** – row index \[0 .. 3\] - • **values** – iterable of four row values - **get\_col(col: int) -\> tuple\[float, ...\]** Returns a column as a tuple of four floats. - **Parameters** **col** – column index \[0 .. 3\] - **set\_col(col: int, values: Sequence\[float\])** Sets the values in a column. - **Parameters** - • **col** – column index \[0 .. 3\] - • **values** – iterable of four column values - **copy() -\> *Matrix44*** Returns a copy of same type. - **\_\_copy\_\_() -\> *Matrix44*** Returns a copy of same type. - **classmethod scale(sx: float, sy: float \| None = None, sz: float \| None = None) -\> *Matrix44*** Returns a scaling transformation matrix. If *sy* is **None**, *sy* = *sx*, and if *sz* is **None** *sz* = *sx*. - **classmethod translate(dx: float, dy: float, dz: float) -\> *Matrix44*** Returns a translation matrix for translation vector (dx, dy, dz). - **classmethod x\_rotate(angle: float) -\> *Matrix44*** Returns a rotation matrix about the x-axis. - **Parameters** **angle** – rotation angle in radians - **classmethod y\_rotate(angle: float) -\> *Matrix44*** Returns a rotation matrix about the y-axis. - **Parameters** **angle** – rotation angle in radians - **classmethod z\_rotate(angle: float) -\> *Matrix44*** Returns a rotation matrix about the z-axis. - **Parameters** **angle** – rotation angle in radians - **classmethod axis\_rotate(axis: *UVec*, angle: float) -\> *Matrix44*** Returns a rotation matrix about an arbitrary *axis*. - **Parameters** - • **axis** – rotation axis as **(x, y, z)** tuple or *Vec3* object - • **angle** – rotation angle in radians - **classmethod xyz\_rotate(angle\_x: float, angle\_y: float, angle\_z: float) -\> *Matrix44*** Returns a rotation matrix for rotation about each axis. - **Parameters** - • **angle\_x** – rotation angle about x-axis in radians - • **angle\_y** – rotation angle about y-axis in radians - • **angle\_z** – rotation angle about z-axis in radians - **classmethod shear\_xy(angle\_x: float = 0, angle\_y: float = 0) -\> *Matrix44*** Returns a translation matrix for shear mapping (visually similar to slanting) in the xy-plane. - **Parameters** - • **angle\_x** – slanting angle in x direction in radians - • **angle\_y** – slanting angle in y direction in radians - **classmethod perspective\_projection(left: float, right: float, top: float, bottom: float, near: float, far: float) -\> *Matrix44*** Returns a matrix for a 2D projection. - **Parameters** - • **left** – Coordinate of left of screen - • **right** – Coordinate of right of screen - • **top** – Coordinate of the top of the screen - • **bottom** – Coordinate of the bottom of the screen - • **near** – Coordinate of the near clipping plane - • **far** – Coordinate of the far clipping plane - **classmethod perspective\_projection\_fov(fov: float, aspect: float, near: float, far: float) -\> *Matrix44*** Returns a matrix for a 2D projection. - **Parameters** - • **fov** – The field of view (in radians) - • **aspect** – The aspect ratio of the screen (width / height) - • **near** – Coordinate of the near clipping plane - • **far** – Coordinate of the far clipping plane - **static chain(\*matrices: *Matrix44*) -\> *Matrix44*** Compose a transformation matrix from one or more *matrices*. - **static ucs(ux: *Vec3* = X\_AXIS, uy: *Vec3* = Y\_AXIS, uz: *Vec3* = Z\_AXIS, origin: *Vec3* = NULLVEC) -\> *Matrix44*** Returns a matrix for coordinate transformation from WCS to UCS. For transformation from UCS to WCS, transpose the returned matrix. - **Parameters** - • **ux** – x-axis for UCS as unit vector - • **uy** – y-axis for UCS as unit vector - • **uz** – z-axis for UCS as unit vector - • **origin** – UCS origin as location vector - **\_\_hash\_\_()** Return hash(self). - **\_\_getitem\_\_(index: tuple\[int, int\])** Get (row, column) element. - **\_\_setitem\_\_(index: tuple\[int, int\], value: float)** Set (row, column) element. - **\_\_iter\_\_() -\> Iterator\[float\]** Iterates over all matrix values. - **rows() -\> Iterator\[tuple\[float, ...\]\]** Iterate over rows as 4-tuples. - **columns() -\> Iterator\[tuple\[float, ...\]\]** Iterate over columns as 4-tuples. - **\_\_mul\_\_(other: *Matrix44*) -\> *Matrix44*** Returns a new matrix as result of the matrix multiplication with another matrix. - **\_\_imul\_\_(other: *Matrix44*) -\> *Matrix44*** Inplace multiplication with another matrix. - **transform(vector: *UVec*) -\> *Vec3*** Returns a transformed vertex. - **transform\_direction(vector: *UVec*, normalize=False) -\> *Vec3*** Returns a transformed direction vector without translation. - **transform\_vertices(vectors: Iterable\[*UVec*\]) -\> Iterator\[*Vec3*\]** Returns an iterable of transformed vertices. - **fast\_2d\_transform(points: Iterable\[*UVec*\]) -\> Iterator\[*Vec2*\]** Fast transformation of 2D points. For 3D input points the z-axis will be ignored. This only works reliable if only 2D transformations have been applied to the 4x4 matrix! Profiling results - speed gains over *transform\_vertices()*: - • pure Python code: ~1.6x - • Python with C-extensions: less than 1.1x - • PyPy 3.8: ~4.3x But speed isn’t everything, returning the processed input points as *Vec2* instances is another advantage. Added in version 1.1. - **transform\_directions(vectors: Iterable\[*UVec*\], normalize=False) -\> Iterator\[*Vec3*\]** Returns an iterable of transformed direction vectors without translation. - **transpose() -\> None** Swaps the rows for columns inplace. - **determinant() -\> float** Returns determinant. - **inverse() -\> None** Calculates the inverse of the matrix. - **Raises** **ZeroDivisionError** – if matrix has no inverse. - **property is\_cartesian: bool** Returns **True** if target coordinate system is a right handed orthogonal coordinate system. - **property is\_orthogonal: bool** Returns **True** if target coordinate system has orthogonal axis. Does not check for left- or right handed orientation, any orientation of the axis valid. ### Basic Construction Classes | | | | --- | --- | | *BoundingBox* | 3D bounding box. | | *BoundingBox2d* | 2D bounding box. | | *ConstructionArc* | Construction tool for 2D arcs. | | *ConstructionBox* | Construction tool for 2D rectangles. | | *ConstructionCircle* | Construction tool for 2D circles. | | *ConstructionEllipse* | Construction tool for 3D ellipsis. | | *ConstructionLine* | Construction tool for 2D lines. | | *ConstructionPolyline* | Construction tool for 3D polylines. | | *ConstructionRay* | Construction tool for infinite 2D rays. | | *Plane* | Construction tool for 3D planes. | | *Shape2d* | Construction tools for 2D shapes. | | *Vec2* | Immutable 2D vector class. | | *Vec3* | Immutable 3D vector class. | ### UVec - **class ezdxf.math.UVec** Type alias for **Union\[Sequence\[float\], Vec2, Vec3\]** ### Vec3 - **class ezdxf.math.Vec3(\*args)** Immutable 3D vector class. This class is optimized for universality not for speed. Immutable means you can’t change (x, y, z) components after initialization: ``` v1 = Vec3(1, 2, 3) v2 = v1 v2.z = 7 # this is not possible, raises AttributeError v2 = Vec3(v2.x, v2.y, 7) # this creates a new Vec3() object assert v1.z == 3 # and v1 remains unchanged ``` *Vec3* initialization: - • **Vec3()**, returns **Vec3(0, 0, 0)** - • **Vec3((x, y))**, returns **Vec3(x, y, 0)** - • **Vec3((x, y, z))**, returns **Vec3(x, y, z)** - • **Vec3(x, y)**, returns **Vec3(x, y, 0)** - • **Vec3(x, y, z)**, returns **Vec3(x, y, z)** Addition, subtraction, scalar multiplication and scalar division left and right-handed are supported: ``` v = Vec3(1, 2, 3) v + (1, 2, 3) == Vec3(2, 4, 6) (1, 2, 3) + v == Vec3(2, 4, 6) v - (1, 2, 3) == Vec3(0, 0, 0) (1, 2, 3) - v == Vec3(0, 0, 0) v * 3 == Vec3(3, 6, 9) 3 * v == Vec3(3, 6, 9) Vec3(3, 6, 9) / 3 == Vec3(1, 2, 3) -Vec3(1, 2, 3) == (-1, -2, -3) ``` Comparison between vectors and vectors or tuples is supported: ``` Vec3(1, 2, 3) < Vec3 (2, 2, 2) (1, 2, 3) < tuple(Vec3(2, 2, 2)) # conversion necessary Vec3(1, 2, 3) == (1, 2, 3) bool(Vec3(1, 2, 3)) is True bool(Vec3(0, 0, 0)) is False ``` - **x** x-axis value - **y** y-axis value - **z** z-axis value - **xy** Vec3 as **(x, y, 0)**, projected on the xy-plane. - **xyz** Vec3 as **(x, y, z)** tuple. - **vec2** Real 2D vector as *Vec2* object. - **magnitude** Length of vector. - **magnitude\_xy** Length of vector in the xy-plane. - **magnitude\_square** Square length of vector. - **is\_null** **Vec3(0, 0, 0)**. Has a fixed absolute testing tolerance of 1e-12! - **Type** **True** if all components are close to zero - **angle** Angle between vector and x-axis in the xy-plane in radians. - **angle\_deg** Returns angle of vector and x-axis in the xy-plane in degrees. - **spatial\_angle** Spatial angle between vector and x-axis in radians. - **spatial\_angle\_deg** Spatial angle between vector and x-axis in degrees. - **\_\_str\_\_() -\> str** Return **'(x, y, z)'** as string. - **\_\_repr\_\_() -\> str** Return **'Vec3(x, y, z)'** as string. - **\_\_len\_\_() -\> int** Returns always **3**. - **\_\_hash\_\_() -\> int** Returns hash value of vector, enables the usage of vector as key in **set** and **dict**. - **copy() -\> *Vec3*** Returns a copy of vector as *Vec3* object. - **\_\_copy\_\_() -\> *Vec3*** Returns a copy of vector as *Vec3* object. - **\_\_deepcopy\_\_(memodict: dict) -\> *Vec3*** **copy.deepcopy()** support. - **\_\_getitem\_\_(index: int) -\> float** Support for indexing: - • v\[0\] is v.x - • v\[1\] is v.y - • v\[2\] is v.z - **\_\_iter\_\_() -\> Iterator\[float\]** Returns iterable of x-, y- and z-axis. - **\_\_abs\_\_() -\> float** Returns length (magnitude) of vector. - **replace(x: float \| None = None, y: float \| None = None, z: float \| None = None) -\> *Vec3*** Returns a copy of vector with replaced x-, y- and/or z-axis. - **classmethod generate(items: Iterable\[*UVec*\]) -\> Iterator\[*Vec3*\]** Returns an iterable of *Vec3* objects. - **classmethod list(items: Iterable\[*UVec*\]) -\> list\[*Vec3*\]** Returns a list of *Vec3* objects. - **classmethod tuple(items: Iterable\[*UVec*\]) -\> Sequence\[*Vec3*\]** Returns a tuple of *Vec3* objects. - **classmethod from\_angle(angle: float, length: float = 1.0) -\> *Vec3*** Returns a *Vec3* object from *angle* in radians in the xy-plane, z-axis = **0**. - **classmethod from\_deg\_angle(angle: float, length: float = 1.0) -\> *Vec3*** Returns a *Vec3* object from *angle* in degrees in the xy-plane, z-axis = **0**. - **orthogonal(ccw: bool = True) -\> *Vec3*** Returns orthogonal 2D vector, z-axis is unchanged. - **Parameters** **ccw** – counter-clockwise if **True** else clockwise - **lerp(other: *UVec*, factor=0.5) -\> *Vec3*** Returns linear interpolation between *self* and *other*. - **Parameters** - • **other** – end point as *Vec3* compatible object - • **factor** – interpolation factor (0 = self, 1 = other, 0.5 = mid point) - **is\_parallel(other: *Vec3*, \*, rel\_tol: float = 1e-9, abs\_tol: float = 1e-12) -\> bool** Returns **True** if *self* and *other* are parallel to vectors. - **project(other: *UVec*) -\> *Vec3*** Returns projected vector of *other* onto *self*. - **normalize(length: float = 1.0) -\> *Vec3*** Returns normalized vector, optional scaled by *length*. - **reversed() -\> *Vec3*** Returns negated vector (-*self*). - **isclose(other: *UVec*, \*, rel\_tol: float = 1e-9, abs\_tol: float = 1e-12) -\> bool** Returns **True** if *self* is close to *other*. Uses **math.isclose()** to compare all axis. Learn more about the **math.isclose()** function in *PEP 485*. - **\_\_neg\_\_() -\> *Vec3*** Returns negated vector (-*self*). - **\_\_bool\_\_() -\> bool** Returns **True** if vector is not (0, 0, 0). - **\_\_eq\_\_(other: *UVec*) -\> bool** Equal operator. - **Parameters** **other** – *Vec3* compatible object - **\_\_lt\_\_(other: *UVec*) -\> bool** Lower than operator. - **Parameters** **other** – *Vec3* compatible object - **\_\_add\_\_(other: *UVec*) -\> *Vec3*** Add *Vec3* operator: *self* + *other*. - **\_\_radd\_\_(other: *UVec*) -\> *Vec3*** RAdd *Vec3* operator: *other* + *self*. - **\_\_sub\_\_(other: *UVec*) -\> *Vec3*** Sub *Vec3* operator: *self* - *other*. - **\_\_rsub\_\_(other: *UVec*) -\> *Vec3*** RSub *Vec3* operator: *other* - *self*. - **\_\_mul\_\_(other: float) -\> *Vec3*** Scalar Mul operator: *self* \* *other*. - **\_\_rmul\_\_(other: float) -\> *Vec3*** Scalar RMul operator: *other* \* *self*. - **\_\_truediv\_\_(other: float) -\> *Vec3*** Scalar Div operator: *self* / *other*. - **dot(other: *UVec*) -\> float** Dot operator: *self* . *other* - **Parameters** **other** – *Vec3* compatible object - **cross(other: *UVec*) -\> *Vec3*** Cross operator: *self* x *other* - **Parameters** **other** – *Vec3* compatible object - **distance(other: *UVec*) -\> float** Returns distance between *self* and *other* vector. - **angle\_about(base: *UVec*, target: *UVec*) -\> float** Returns counter-clockwise angle in radians about *self* from *base* to *target* when projected onto the plane defined by *self* as the normal vector. - **Parameters** - • **base** – base vector, defines angle 0 - • **target** – target vector - **angle\_between(other: *UVec*) -\> float** Returns angle between *self* and *other* in radians. +angle is counter clockwise orientation. - **Parameters** **other** – *Vec3* compatible object - **rotate(angle: float) -\> *Vec3*** Returns vector rotated about *angle* around the z-axis. - **Parameters** **angle** – angle in radians - **rotate\_deg(angle: float) -\> *Vec3*** Returns vector rotated about *angle* around the z-axis. - **Parameters** **angle** – angle in degrees - **static sum(items: Iterable\[*UVec*\]) -\> *Vec3*** Add all vectors in *items*. - **ezdxf.math.X\_AXIS** **Vec3(1, 0, 0)** - **ezdxf.math.Y\_AXIS** **Vec3(0, 1, 0)** - **ezdxf.math.Z\_AXIS** **Vec3(0, 0, 1)** - **ezdxf.math.NULLVEC** **Vec3(0, 0, 0)** ### Vec2 - **class ezdxf.math.Vec2(v=(0.0, 0.0), y=None)** Immutable 2D vector class. - **Parameters** - • **v** – vector object with **x** and **y** attributes/properties or a sequence of float **\[x, y, ...\]** or x-axis as float if argument *y* is not **None** - • **y** – second float for **Vec2(x, y)** *Vec2* implements a subset of *Vec3*. ### Plane - **class ezdxf.math.Plane(normal: *Vec3*, distance: float)** Construction tool for 3D planes. Represents a plane in 3D space as a normal vector and the perpendicular distance from the origin. - **normal** Normal vector of the plane. - **distance\_from\_origin** The (perpendicular) distance of the plane from origin (0, 0, 0). - **vector** Returns the location vector. - **classmethod from\_3p(a: *Vec3*, b: *Vec3*, c: *Vec3*) -\> *Plane*** Returns a new plane from 3 points in space. - **classmethod from\_vector(vector: *UVec*) -\> *Plane*** Returns a new plane from the given location vector. - **copy() -\> *Plane*** Returns a copy of the plane. - **signed\_distance\_to(v: *Vec3*) -\> float** Returns signed distance of vertex *v* to plane, if distance is \> 0, *v* is in ‘front’ of plane, in direction of the normal vector, if distance is \< 0, *v* is at the ‘back’ of the plane, in the opposite direction of the normal vector. - **distance\_to(v: *Vec3*) -\> float** Returns absolute (unsigned) distance of vertex *v* to plane. - **is\_coplanar\_vertex(v: *Vec3*, abs\_tol=1e-9) -\> bool** Returns **True** if vertex *v* is coplanar, distance from plane to vertex *v* is 0. - **is\_coplanar\_plane(p: *Plane*, abs\_tol=1e-9) -\> bool** Returns **True** if plane *p* is coplanar, normal vectors in same or opposite direction. - **intersect\_line(start: *Vec3*, end: *Vec3*, \*, coplanar=True, abs\_tol=PLANE\_EPSILON) -\> *Vec3* \| None** Returns the intersection point of the 3D line from *start* to *end* and this plane or **None** if there is no intersection. If the argument *coplanar* is **False** the start- or end point of the line are ignored as intersection points. - **intersect\_ray(origin: *Vec3*, direction: *Vec3*) -\> *Vec3* \| None** Returns the intersection point of the infinite 3D ray defined by *origin* and the *direction* vector and this plane or **None** if there is no intersection. A coplanar ray does not intersect the plane! ### BoundingBox - **class ezdxf.math.BoundingBox(vertices: Iterable\[*UVec*\] \| None = None)** 3D bounding box. - **Parameters** **vertices** – iterable of **(x, y, z)** tuples or *Vec3* objects - **extmin** “lower left” corner of bounding box - **extmax** “upper right” corner of bounding box - **property is\_empty: bool** Returns **True** if the bounding box is empty or the bounding box has a size of 0 in any or all dimensions or is undefined. - **property has\_data: bool** Returns **True** if the bonding box has known limits. - **property size: T** Returns size of bounding box. - **property center: T** Returns center of bounding box. - **inside(vertex: *UVec*) -\> bool** Returns **True** if *vertex* is inside this bounding box. Vertices at the box border are inside! - **any\_inside(vertices: Iterable\[*UVec*\]) -\> bool** Returns **True** if any vertex is inside this bounding box. Vertices at the box border are inside! - **all\_inside(vertices: Iterable\[*UVec*\]) -\> bool** Returns **True** if all vertices are inside this bounding box. Vertices at the box border are inside! - **has\_intersection(other: AbstractBoundingBox\[T\]) -\> bool** Returns **True** if this bounding box intersects with *other* but does not include touching bounding boxes, see also *has\_overlap()*: ``` bbox1 = BoundingBox([(0, 0, 0), (1, 1, 1)]) bbox2 = BoundingBox([(1, 1, 1), (2, 2, 2)]) assert bbox1.has_intersection(bbox2) is False ``` - **has\_overlap(other: AbstractBoundingBox\[T\]) -\> bool** Returns **True** if this bounding box intersects with *other* but in contrast to *has\_intersection()* includes touching bounding boxes too: ``` bbox1 = BoundingBox([(0, 0, 0), (1, 1, 1)]) bbox2 = BoundingBox([(1, 1, 1), (2, 2, 2)]) assert bbox1.has_overlap(bbox2) is True ``` - **contains(other: AbstractBoundingBox\[T\]) -\> bool** Returns **True** if the *other* bounding box is completely inside this bounding box. - **extend(vertices: Iterable\[*UVec*\]) -\> None** Extend bounds by *vertices*. - **Parameters** **vertices** – iterable of vertices - **union(other: AbstractBoundingBox\[T\]) -\> AbstractBoundingBox\[T\]** Returns a new bounding box as union of this and *other* bounding box. - **intersection(other: AbstractBoundingBox\[T\]) -\> *BoundingBox*** Returns the bounding box of the intersection cube of both 3D bounding boxes. Returns an empty bounding box if the intersection volume is 0. - **rect\_vertices() -\> Sequence\[*Vec2*\]** Returns the corners of the bounding box in the xy-plane as *Vec2* objects. - **cube\_vertices() -\> Sequence\[*Vec3*\]** Returns the 3D corners of the bounding box as *Vec3* objects. - **grow(value: float) -\> None** Grow or shrink the bounding box by an uniform value in x, y and z-axis. A negative value shrinks the bounding box. Raises **ValueError** for shrinking the size of the bounding box to zero or below in any dimension. ### BoundingBox2d - **class ezdxf.math.BoundingBox2d(vertices: Iterable\[*UVec*\] \| None = None)** 2D bounding box. - **Parameters** **vertices** – iterable of **(x, y\[, z\])** tuples or *Vec3* objects - **extmin** “lower left” corner of bounding box - **extmax** “upper right” corner of bounding box - **property is\_empty: bool** Returns **True** if the bounding box is empty. The bounding box has a size of 0 in any or all dimensions or is undefined. - **property has\_data: bool** Returns **True** if the bonding box has known limits. - **property size: T** Returns size of bounding box. - **property center: T** Returns center of bounding box. - **inside(vertex: *UVec*) -\> bool** Returns **True** if *vertex* is inside this bounding box. Vertices at the box border are inside! - **any\_inside(vertices: Iterable\[*UVec*\]) -\> bool** Returns **True** if any vertex is inside this bounding box. Vertices at the box border are inside! - **all\_inside(vertices: Iterable\[*UVec*\]) -\> bool** Returns **True** if all vertices are inside this bounding box. Vertices at the box border are inside! - **has\_intersection(other: AbstractBoundingBox\[T\]) -\> bool** Returns **True** if this bounding box intersects with *other* but does not include touching bounding boxes, see also *has\_overlap()*: ``` bbox1 = BoundingBox2d([(0, 0), (1, 1)]) bbox2 = BoundingBox2d([(1, 1), (2, 2)]) assert bbox1.has_intersection(bbox2) is False ``` - **has\_overlap(other: AbstractBoundingBox\[T\]) -\> bool** Returns **True** if this bounding box intersects with *other* but in contrast to *has\_intersection()* includes touching bounding boxes too: ``` bbox1 = BoundingBox2d([(0, 0), (1, 1)]) bbox2 = BoundingBox2d([(1, 1), (2, 2)]) assert bbox1.has_overlap(bbox2) is True ``` - **contains(other: AbstractBoundingBox\[T\]) -\> bool** Returns **True** if the *other* bounding box is completely inside this bounding box. - **extend(vertices: Iterable\[*UVec*\]) -\> None** Extend bounds by *vertices*. - **Parameters** **vertices** – iterable of vertices - **union(other: AbstractBoundingBox\[T\]) -\> AbstractBoundingBox\[T\]** Returns a new bounding box as union of this and *other* bounding box. - **intersection(other: AbstractBoundingBox\[T\]) -\> *BoundingBox2d*** Returns the bounding box of the intersection rectangle of both 2D bounding boxes. Returns an empty bounding box if the intersection area is 0. - **rect\_vertices() -\> Sequence\[*Vec2*\]** Returns the corners of the bounding box in the xy-plane as *Vec2* objects. ### ConstructionRay - **class ezdxf.math.ConstructionRay(p1: *UVec*, p2: *UVec* \| None = None, angle: float \| None = None)** Construction tool for infinite 2D rays. - **Parameters** - • **p1** – definition point 1 - • **p2** – ray direction as 2nd point or **None** - • **angle** – ray direction as angle in radians or **None** - **location** Location vector as *Vec2*. - **direction** Direction vector as *Vec2*. - **slope** Slope of ray or **None** if vertical. - **angle** Angle between x-axis and ray in radians. - **angle\_deg** Angle between x-axis and ray in degrees. - **is\_vertical** **True** if ray is vertical (parallel to y-axis). - **is\_horizontal** **True** if ray is horizontal (parallel to x-axis). - **\_\_str\_\_()** Return str(self). - **is\_parallel(other: *ConstructionRay*) -\> bool** Returns **True** if rays are parallel. - **intersect(other: *ConstructionRay*) -\> *Vec2*** Returns the intersection point as **(x, y)** tuple of *self* and *other*. - **Raises** **ParallelRaysError** – if rays are parallel - **orthogonal(location: *UVec*) -\> *ConstructionRay*** Returns orthogonal ray at *location*. - **bisectrix(other: *ConstructionRay*) -\> *ConstructionRay*** Bisectrix between *self* and *other*. - **yof(x: float) -\> float** Returns y-value of ray for *x* location. - **Raises** **ArithmeticError** – for vertical rays - **xof(y: float) -\> float** Returns x-value of ray for *y* location. - **Raises** **ArithmeticError** – for horizontal rays ### ConstructionLine - **class ezdxf.math.ConstructionLine(start: *UVec*, end: *UVec*)** Construction tool for 2D lines. The *ConstructionLine* class is similar to *ConstructionRay*, but has a start- and endpoint. The direction of line goes from start- to endpoint, “left of line” is always in relation to this line direction. - **Parameters** - • **start** – start point of line as *Vec2* compatible object - • **end** – end point of line as *Vec2* compatible object - **start** start point as *Vec2* - **end** end point as *Vec2* - **bounding\_box** bounding box of line as *BoundingBox2d* object. - **ray** collinear *ConstructionRay*. - **is\_vertical** **True** if line is vertical. - **is\_horizontal** **True** if line is horizontal. - **\_\_str\_\_()** Return str(self). - **translate(dx: float, dy: float) -\> None** Move line about *dx* in x-axis and about *dy* in y-axis. - **Parameters** - • **dx** – translation in x-axis - • **dy** – translation in y-axis - **length() -\> float** Returns length of line. - **midpoint() -\> *Vec2*** Returns mid point of line. - **inside\_bounding\_box(point: *UVec*) -\> bool** Returns **True** if *point* is inside of line bounding box. - **intersect(other: *ConstructionLine*, abs\_tol: float = TOLERANCE) -\> *Vec2* \| None** Returns the intersection point of to lines or **None** if they have no intersection point. - **Parameters** - • **other** – other *ConstructionLine* - • **abs\_tol** – tolerance for distance check - **has\_intersection(other: *ConstructionLine*, abs\_tol: float = TOLERANCE) -\> bool** Returns **True** if has intersection with *other* line. - **is\_point\_left\_of\_line(point: *UVec*, colinear=False) -\> bool** Returns **True** if *point* is left of construction line in relation to the line direction from start to end. If *colinear* is **True**, a colinear point is also left of the line. ### ConstructionCircle - **class ezdxf.math.ConstructionCircle(center: *UVec*, radius: float = 1.0)** Construction tool for 2D circles. - **Parameters** - • **center** – center point as *Vec2* compatible object - • **radius** – circle radius \> *0* - **center** center point as *Vec2* - **radius** radius as float - **bounding\_box** 2D bounding box of circle as *BoundingBox2d* object. - **static from\_3p(p1: *UVec*, p2: *UVec*, p3: *UVec*) -\> *ConstructionCircle*** Creates a circle from three points, all points have to be compatible to *Vec2* class. - **\_\_str\_\_() -\> str** Returns string representation of circle “ConstructionCircle(center, radius)”. - **translate(dx: float, dy: float) -\> None** Move circle about *dx* in x-axis and about *dy* in y-axis. - **Parameters** - • **dx** – translation in x-axis - • **dy** – translation in y-axis - **point\_at(angle: float) -\> *Vec2*** Returns point on circle at *angle* as *Vec2* object. - **Parameters** **angle** – angle in radians, angle goes counter clockwise around the z-axis, x-axis = 0 deg. - **vertices(angles: Iterable\[float\]) -\> Iterable\[*Vec2*\]** Yields vertices of the circle for iterable *angles*. - **Parameters** **angles** – iterable of angles as radians, angle goes counter-clockwise around the z-axis, x-axis = 0 deg. - **flattening(sagitta: float) -\> Iterator\[*Vec2*\]** Approximate the circle by vertices, argument *sagitta* is the max. distance from the center of an arc segment to the center of its chord. Returns a closed polygon where the start vertex is coincident with the end vertex! - **inside(point: *UVec*) -\> bool** Returns **True** if *point* is inside circle. - **tangent(angle: float) -\> *ConstructionRay*** Returns tangent to circle at *angle* as *ConstructionRay* object. - **Parameters** **angle** – angle in radians - **intersect\_ray(ray: *ConstructionRay*, abs\_tol: float = 1e-10) -\> Sequence\[*Vec2*\]** Returns intersection points of circle and *ray* as sequence of *Vec2* objects. - **Parameters** - • **ray** – intersection ray - • **abs\_tol** – absolute tolerance for tests (e.g. test for tangents) - **Returns** tuple of *Vec2* objects | | | | --- | --- | | tuple size | Description | | 0 | no intersection | | 1 | ray is a tangent to circle | | 2 | ray intersects with the circle | - **intersect\_line(line: *ConstructionLine*, abs\_tol: float = 1e-10) -\> Sequence\[*Vec2*\]** Returns intersection points of circle and *line* as sequence of *Vec2* objects. - **Parameters** - • **line** – intersection line - • **abs\_tol** – absolute tolerance for tests (e.g. test for tangents) - **Returns** tuple of *Vec2* objects | | | | --- | --- | | tuple size | Description | | 0 | no intersection | | 1 | line intersects or touches the circle at one point | | 2 | line intersects the circle at two points | - **intersect\_circle(other: *ConstructionCircle*, abs\_tol: float = 1e-10) -\> Sequence\[*Vec2*\]** Returns intersection points of two circles as sequence of *Vec2* objects. - **Parameters** - • **other** – intersection circle - • **abs\_tol** – absolute tolerance for tests - **Returns** tuple of *Vec2* objects | | | | --- | --- | | tuple size | Description | | 0 | no intersection | | 1 | circle touches the *other* circle at one point | | 2 | circle intersects with the *other* circle | ### ConstructionArc - **class ezdxf.math.ConstructionArc(center: *UVec* = (0, 0), radius: float = 1.0, start\_angle: float = 0.0, end\_angle: float = 360.0, is\_counter\_clockwise: bool \| None = True)** Construction tool for 2D arcs. *ConstructionArc* represents a 2D arc in the xy-plane, use an *UCS* to place a DXF *Arc* entity in 3D space, see method *add\_to\_layout()*. Implements the 2D transformation tools: *translate()*, *scale\_uniform()* and *rotate\_z()* - **Parameters** - • **center** – center point as *Vec2* compatible object - • **radius** – radius - • **start\_angle** – start angle in degrees - • **end\_angle** – end angle in degrees - • **is\_counter\_clockwise** – swaps start- and end angle if **False** - **center** center point as *Vec2* - **radius** radius as float - **start\_angle** start angle in degrees - **end\_angle** end angle in degrees - **angle\_span** Returns angle span of arc from start- to end param. - **start\_angle\_rad** Returns the start angle in radians. - **end\_angle\_rad** Returns the end angle in radians. - **start\_point** start point of arc as *Vec2*. - **end\_point** end point of arc as *Vec2*. - **bounding\_box** bounding box of arc as *BoundingBox2d*. - **angles(num: int) -\> Iterable\[float\]** Returns *num* angles from start- to end angle in degrees in counter-clockwise order. All angles are normalized in the range from \[0, 360). - **vertices(a: Iterable\[float\]) -\> Iterable\[*Vec2*\]** Yields vertices on arc for angles in iterable *a* in WCS as location vectors. - **Parameters** **a** – angles in the range from 0 to 360 in degrees, arc goes counter clockwise around the z-axis, WCS x-axis = 0 deg. - **tangents(a: Iterable\[float\]) -\> Iterable\[*Vec2*\]** Yields tangents on arc for angles in iterable *a* in WCS as direction vectors. - **Parameters** **a** – angles in the range from 0 to 360 in degrees, arc goes counter-clockwise around the z-axis, WCS x-axis = 0 deg. - **translate(dx: float, dy: float) -\> *ConstructionArc*** Move arc about *dx* in x-axis and about *dy* in y-axis, returns *self* (floating interface). - **Parameters** - • **dx** – translation in x-axis - • **dy** – translation in y-axis - **scale\_uniform(s: float) -\> *ConstructionArc*** Scale arc inplace uniform about *s* in x- and y-axis, returns *self* (floating interface). - **rotate\_z(angle: float) -\> *ConstructionArc*** Rotate arc inplace about z-axis, returns *self* (floating interface). - **Parameters** **angle** – rotation angle in degrees - **classmethod from\_2p\_angle(start\_point: *UVec*, end\_point: *UVec*, angle: float, ccw: bool = True) -\> *ConstructionArc*** Create arc from two points and enclosing angle. Additional precondition: arc goes by default in counter-clockwise orientation from *start\_point* to *end\_point*, can be changed by *ccw* = **False**. - **Parameters** - • **start\_point** – start point as *Vec2* compatible object - • **end\_point** – end point as *Vec2* compatible object - • **angle** – enclosing angle in degrees - • **ccw** – counter-clockwise direction if **True** - **classmethod from\_2p\_radius(start\_point: *UVec*, end\_point: *UVec*, radius: float, ccw: bool = True, center\_is\_left: bool = True) -\> *ConstructionArc*** Create arc from two points and arc radius. Additional precondition: arc goes by default in counter-clockwise orientation from *start\_point* to *end\_point* can be changed by *ccw* = **False**. The parameter *center\_is\_left* defines if the center of the arc is left or right of the line from *start\_point* to *end\_point*. Parameter *ccw* = **False** swaps start- and end point, which also inverts the meaning of **center\_is\_left**. - **Parameters** - • **start\_point** – start point as *Vec2* compatible object - • **end\_point** – end point as *Vec2* compatible object - • **radius** – arc radius - • **ccw** – counter-clockwise direction if **True** - • **center\_is\_left** – center point of arc is left of line from start- to end point if **True** - **classmethod from\_3p(start\_point: *UVec*, end\_point: *UVec*, def\_point: *UVec*, ccw: bool = True) -\> *ConstructionArc*** Create arc from three points. Additional precondition: arc goes in counter-clockwise orientation from *start\_point* to *end\_point*. - **Parameters** - • **start\_point** – start point as *Vec2* compatible object - • **end\_point** – end point as *Vec2* compatible object - • **def\_point** – additional definition point as *Vec2* compatible object - • **ccw** – counter-clockwise direction if **True** - **add\_to\_layout(layout: *BaseLayout*, ucs: *UCS* \| None = None, dxfattribs=None) -\> *Arc*** Add arc as DXF *Arc* entity to a layout. Supports 3D arcs by using an *UCS*. An *ConstructionArc* is always defined in the xy-plane, but by using an arbitrary UCS, the arc can be placed in 3D space, automatically OCS transformation included. - **Parameters** - • **layout** – destination layout as *BaseLayout* object - • **ucs** – place arc in 3D space by *UCS* object - • **dxfattribs** – additional DXF attributes for the ARC entity - **intersect\_ray(ray: *ConstructionRay*, abs\_tol: float = 1e-10) -\> Sequence\[*Vec2*\]** Returns intersection points of arc and *ray* as sequence of *Vec2* objects. - **Parameters** - • **ray** – intersection ray - • **abs\_tol** – absolute tolerance for tests (e.g. test for tangents) - **Returns** tuple of *Vec2* objects | | | | --- | --- | | tuple size | Description | | 0 | no intersection | | 1 | line intersects or touches the arc at one point | | 2 | line intersects the arc at two points | - **intersect\_line(line: *ConstructionLine*, abs\_tol: float = 1e-10) -\> Sequence\[*Vec2*\]** Returns intersection points of arc and *line* as sequence of *Vec2* objects. - **Parameters** - • **line** – intersection line - • **abs\_tol** – absolute tolerance for tests (e.g. test for tangents) - **Returns** tuple of *Vec2* objects | | | | --- | --- | | tuple size | Description | | 0 | no intersection | | 1 | line intersects or touches the arc at one point | | 2 | line intersects the arc at two points | - **intersect\_circle(circle: *ConstructionCircle*, abs\_tol: float = 1e-10) -\> Sequence\[*Vec2*\]** Returns intersection points of arc and *circle* as sequence of *Vec2* objects. - **Parameters** - • **circle** – intersection circle - • **abs\_tol** – absolute tolerance for tests - **Returns** tuple of *Vec2* objects | | | | --- | --- | | tuple size | Description | | 0 | no intersection | | 1 | circle intersects or touches the arc at one point | | 2 | circle intersects the arc at two points | - **intersect\_arc(other: *ConstructionArc*, abs\_tol: float = 1e-10) -\> Sequence\[*Vec2*\]** Returns intersection points of two arcs as sequence of *Vec2* objects. - **Parameters** - • **other** – other intersection arc - • **abs\_tol** – absolute tolerance for tests - **Returns** tuple of *Vec2* objects | | | | --- | --- | | tuple size | Description | | 0 | no intersection | | 1 | other arc intersects or touches the arc at one point | | 2 | other arc intersects the arc at two points | ### ConstructionEllipse - **class ezdxf.math.ConstructionEllipse(center: *UVec* = NULLVEC, major\_axis: *UVec* = X\_AXIS, extrusion: *UVec* = Z\_AXIS, ratio: float = 1, start\_param: float = 0, end\_param: float = math.tau, ccw: bool = True)** Construction tool for 3D ellipsis. - **Parameters** - • **center** – 3D center point - • **major\_axis** – major axis as 3D vector - • **extrusion** – normal vector of ellipse plane - • **ratio** – ratio of minor axis to major axis - • **start\_param** – start param in radians - • **end\_param** – end param in radians - • **ccw** – is counter-clockwise flag - swaps start- and end param if **False** - **center** center point as *Vec3* - **major\_axis** major axis as *Vec3* - **minor\_axis** minor axis as *Vec3*, automatically calculated from *major\_axis* and *extrusion*. - **extrusion** extrusion vector (normal of ellipse plane) as *Vec3* - **ratio** ratio of minor axis to major axis (float) - **start** start param in radians (float) - **end** end param in radians (float) - **start\_point** Returns start point of ellipse as Vec3. - **end\_point** Returns end point of ellipse as Vec3. - **property param\_span: float** Returns the counter-clockwise params span from start- to end param, see also *ezdxf.math.ellipse\_param\_span()* for more information. - **to\_ocs() -\> *ConstructionEllipse*** Returns ellipse parameters as OCS representation. OCS elevation is stored in **center.z**. - **params(num: int) -\> Iterable\[float\]** Returns *num* params from start- to end param in counter-clockwise order. All params are normalized in the range from \[0, 2π). - **vertices(params: Iterable\[float\]) -\> Iterable\[*Vec3*\]** Yields vertices on ellipse for iterable *params* in WCS. - **Parameters** **params** – param values in the range from \[0, 2π) in radians, param goes counter-clockwise around the extrusion vector, major\_axis = local x-axis = 0 rad. - **flattening(distance: float, segments: int = 4) -\> Iterable\[*Vec3*\]** Adaptive recursive flattening. The argument *segments* is the minimum count of approximation segments, if the distance from the center of the approximation segment to the curve is bigger than *distance* the segment will be subdivided. Returns a closed polygon for a full ellipse: start vertex == end vertex. - **Parameters** - • **distance** – maximum distance from the projected curve point onto the segment chord. - • **segments** – minimum segment count - **params\_from\_vertices(vertices: Iterable\[*UVec*\]) -\> Iterable\[float\]** Yields ellipse params for all given *vertices*. The vertex don’t have to be exact on the ellipse curve or in the range from start- to end param or even in the ellipse plane. Param is calculated from the intersection point of the ray projected on the ellipse plane from the center of the ellipse through the vertex. **WARNING:** An input for start- and end vertex at param 0 and 2π return unpredictable results because of floating point inaccuracy, sometimes 0 and sometimes 2π. - **dxfattribs() -\> dict\[str, Any\]** Returns required DXF attributes to build an ELLIPSE entity. Entity ELLIPSE has always a ratio in range from 1e-6 to 1. - **main\_axis\_points() -\> Iterable\[*Vec3*\]** Yields main axis points of ellipse in the range from start- to end param. - **classmethod from\_arc(center: *UVec* = NULLVEC, radius: float = 1, extrusion: *UVec* = Z\_AXIS, start\_angle: float = 0, end\_angle: float = 360, ccw: bool = True) -\> *ConstructionEllipse*** Returns *ConstructionEllipse* from arc or circle. Arc and Circle parameters defined in OCS. - **Parameters** - • **center** – center in OCS - • **radius** – arc or circle radius - • **extrusion** – OCS extrusion vector - • **start\_angle** – start angle in degrees - • **end\_angle** – end angle in degrees - • **ccw** – arc curve goes counter clockwise from start to end if **True** - **transform(m: *Matrix44*) -\> None** Transform ellipse in place by transformation matrix *m*. - **swap\_axis() -\> None** Swap axis and adjust start- and end parameter. - **add\_to\_layout(layout: *BaseLayout*, dxfattribs=None) -\> *Ellipse*** Add ellipse as DXF *Ellipse* entity to a layout. - **Parameters** - • **layout** – destination layout as *BaseLayout* object - • **dxfattribs** – additional DXF attributes for the ELLIPSE entity ### ConstructionBox - **class ezdxf.math.ConstructionBox(center: *UVec* = (0, 0), width: float = 1, height: float = 1, angle: float = 0)** Construction tool for 2D rectangles. - **Parameters** - • **center** – center of rectangle - • **width** – width of rectangle - • **height** – height of rectangle - • **angle** – angle of rectangle in degrees - **center** box center - **width** box width - **height** box height - **angle** rotation angle in degrees - **corners** box corners as sequence of *Vec2* objects. - **bounding\_box** *BoundingBox2d* - **incircle\_radius** incircle radius - **circumcircle\_radius** circum circle radius - **\_\_iter\_\_() -\> Iterable\[*Vec2*\]** Iterable of box corners as *Vec2* objects. - **\_\_getitem\_\_(corner) -\> *Vec2*** Get corner by index *corner*, **list** like slicing is supported. - **\_\_repr\_\_() -\> str** Returns string representation of box as **ConstructionBox(center, width, height, angle)** - **classmethod from\_points(p1: *UVec*, p2: *UVec*) -\> *ConstructionBox*** Creates a box from two opposite corners, box sides are parallel to x- and y-axis. - **Parameters** - • **p1** – first corner as *Vec2* compatible object - • **p2** – second corner as *Vec2* compatible object - **translate(dx: float, dy: float) -\> None** Move box about *dx* in x-axis and about *dy* in y-axis. - **Parameters** - • **dx** – translation in x-axis - • **dy** – translation in y-axis - **expand(dw: float, dh: float) -\> None** Expand box: *dw* expand width, *dh* expand height. - **scale(sw: float, sh: float) -\> None** Scale box: *sw* scales width, *sh* scales height. - **rotate(angle: float) -\> None** Rotate box by *angle* in degrees. - **is\_inside(point: *UVec*) -\> bool** Returns **True** if *point* is inside of box. - **is\_any\_corner\_inside(other: *ConstructionBox*) -\> bool** Returns **True** if any corner of *other* box is inside this box. - **is\_overlapping(other: *ConstructionBox*) -\> bool** Returns **True** if this box and *other* box do overlap. - **border\_lines() -\> Sequence\[*ConstructionLine*\]** Returns borderlines of box as sequence of *ConstructionLine*. - **intersect(line: *ConstructionLine*) -\> list\[*Vec2*\]** Returns 0, 1 or 2 intersection points between *line* and box borderlines. - **Parameters** **line** – line to intersect with borderlines - **Returns** list of intersection points | | | | --- | --- | | list size | Description | | 0 | no intersection | | 1 | line touches box at one corner | | 2 | line intersects with box | ### ConstructionPolyline - **class ezdxf.math.ConstructionPolyline(vertices: Iterable\[*UVec*\], close: bool = False, rel\_tol: float = REL\_TOL)** Construction tool for 3D polylines. A polyline construction tool to measure, interpolate and divide anything that can be approximated or flattened into vertices. This is an immutable data structure which supports the **Sequence** interface. - **Parameters** - • **vertices** – iterable of polyline vertices - • **close** – **True** to close the polyline (first vertex == last vertex) - • **rel\_tol** – relative tolerance for floating point comparisons Example to measure or divide a SPLINE entity: ``` import ezdxf from ezdxf.math import ConstructionPolyline doc = ezdxf.readfile("your.dxf") msp = doc.modelspace() spline = msp.query("SPLINE").first if spline is not None: polyline = ConstructionPolyline(spline.flattening(0.01)) print(f"Entity {spline} has an approximated length of {polyline.length}") # get dividing points with a distance of 1.0 drawing unit to each other points = list(polyline.divide_by_length(1.0)) ``` - **property length: float** Returns the overall length of the polyline. - **property is\_closed: bool** Returns **True** if the polyline is closed (first vertex == last vertex). - **data(index: int) -\> tuple\[float, float, *Vec3*\]** Returns the tuple (distance from start, distance from previous vertex, vertex). All distances measured along the polyline. - **index\_at(distance: float) -\> int** Returns the data index of the exact or next data entry for the given *distance*. Returns the index of last entry if *distance* \> *length*. - **vertex\_at(distance: float) -\> *Vec3*** Returns the interpolated vertex at the given *distance* from the start of the polyline. - **divide(count: int) -\> Iterator\[*Vec3*\]** Returns *count* interpolated vertices along the polyline. Argument *count* has to be greater than 2 and the start- and end vertices are always included. - **divide\_by\_length(length: float, force\_last: bool = False) -\> Iterator\[*Vec3*\]** Returns interpolated vertices along the polyline. Each vertex has a fix distance *length* from its predecessor. Yields the last vertex if argument *force\_last* is **True** even if the last distance is not equal to *length*. ### Shape2d - **class ezdxf.math.Shape2d(vertices: Iterable\[*UVec*\] \| None = None)** Construction tools for 2D shapes. A 2D geometry object as list of *Vec2* objects, vertices can be moved, rotated and scaled. - **Parameters** **vertices** – iterable of *Vec2* compatible objects. - **vertices** List of *Vec2* objects - **bounding\_box** Returns the bounding box of the shape. - **\_\_len\_\_() -\> int** Returns *count* of vertices. - **\_\_getitem\_\_(item: int) -\> *Vec2*** - **\_\_getitem\_\_(item: slice) -\> list\[*Vec2*\]** Get vertex by index *item*, supports **list** like slicing. - **append(vertex: *UVec*) -\> None** Append single *vertex*. - **Parameters** **vertex** – vertex as *Vec2* compatible object - **extend(vertices: Iterable\[*UVec*\]) -\> None** Append multiple *vertices*. - **Parameters** **vertices** – iterable of vertices as *Vec2* compatible objects - **translate(vector: *UVec*) -\> None** Translate shape about *vector*. - **scale(sx: float = 1.0, sy: float = 1.0) -\> None** Scale shape about *sx* in x-axis and *sy* in y-axis. - **scale\_uniform(scale: float) -\> None** Scale shape uniform about *scale* in x- and y-axis. - **rotate(angle: float, center: *UVec* \| None = None) -\> None** Rotate shape around rotation *center* about *angle* in degrees. - **rotate\_rad(angle: float, center: *UVec* \| None = None) -\> None** Rotate shape around rotation *center* about *angle* in radians. - **offset(offset: float, closed: bool = False) -\> *Shape2d*** Returns a new offset shape, for more information see also *ezdxf.math.offset\_vertices\_2d()* function. - **Parameters** - • **offset** – line offset perpendicular to direction of shape segments defined by vertices order, offset \> **0** is ‘left’ of line segment, offset \< **0** is ‘right’ of line segment - • **closed** – **True** to handle as closed shape - **convex\_hull() -\> *Shape2d*** Returns convex hull as new shape. ### Curves | | | | --- | --- | | *ApproxParamT* | Approximation tool for parametrized curves. | | *BSpline* | B-spline construction tool. | | *Bezier* | Generic *Bézier curve* of any degree. | | *Bezier3P* | Implements an optimized quadratic *Bézier curve* for exact 3 control points. | | *Bezier4P* | Implements an optimized cubic *Bézier curve* for exact 4 control points. | | *EulerSpiral* | This class represents an euler spiral (clothoid) for *curvature* (Radius of curvature). | ### BSpline - **class ezdxf.math.BSpline(control\_points: Iterable\[*UVec*\], order: int = 4, knots: Iterable\[float\] \| None = None, weights: Iterable\[float\] \| None = None)** B-spline construction tool. Internal representation of a *B-spline* curve. The default configuration of the knot vector is a uniform open *knot* vector (“clamped”). Factory functions: - • *fit\_points\_to\_cad\_cv()* - • *fit\_points\_to\_cubic\_bezier()* - • *open\_uniform\_bspline()* - • *closed\_uniform\_bspline()* - • *rational\_bspline\_from\_arc()* - • *rational\_bspline\_from\_ellipse()* - • *global\_bspline\_interpolation()* - • *local\_cubic\_bspline\_interpolation()* - **Parameters** - • **control\_points** – iterable of control points as *Vec3* compatible objects - • **order** – spline order (degree + 1) - • **knots** – iterable of knot values - • **weights** – iterable of weight values - **property control\_points: Sequence\[*Vec3*\]** Control points as tuple of *Vec3* - **property count: int** Count of control points, (n + 1 in text book notation). - **property order: int** Order (k) of B-spline = p + 1 - **property degree: int** Degree (p) of B-spline = order - 1 - **property max\_t: float** Biggest *knot* value. - **property is\_rational** Returns **True** if curve is a rational B-spline. (has weights) - **property is\_clamped** Returns **True** if curve is a clamped (open) B-spline. - **knots() -\> Sequence\[float\]** Returns a tuple of *knot* values as floats, the knot vector **always** has order + count values (n + p + 2 in text book notation). - **weights() -\> Sequence\[float\]** Returns a tuple of weights values as floats, one for each control point or an empty tuple. - **params(segments: int) -\> Iterable\[float\]** Yield evenly spaced parameters for given segment count. - **reverse() -\> *BSpline*** Returns a new *BSpline* object with reversed control point order. - **transform(m: *Matrix44*) -\> *BSpline*** Returns a new *BSpline* object transformed by a *Matrix44* transformation matrix. - **approximate(segments: int = 20) -\> Iterable\[*Vec3*\]** Approximates curve by vertices as *Vec3* objects, vertices count = segments + 1. - **flattening(distance: float, segments: int = 4) -\> Iterator\[*Vec3*\]** Adaptive recursive flattening. The argument *segments* is the minimum count of approximation segments between two knots, if the distance from the center of the approximation segment to the curve is bigger than *distance* the segment will be subdivided. - **Parameters** - • **distance** – maximum distance from the projected curve point onto the segment chord. - • **segments** – minimum segment count between two knots - **point(t: float) -\> *Vec3*** Returns point for parameter *t*. - **Parameters** **t** – parameter in range \[0, max\_t\] - **points(t: Iterable\[float\]) -\> Iterable\[*Vec3*\]** Yields points for parameter vector *t*. - **Parameters** **t** – parameters in range \[0, max\_t\] - **derivative(t: float, n: int = 2) -\> list\[*Vec3*\]** Return point and derivatives up to *n* \<= degree for parameter *t*. e.g. n=1 returns point and 1st derivative. - **Parameters** - • **t** – parameter in range \[0, max\_t\] - • **n** – compute all derivatives up to n \<= degree - **Returns** n+1 values as *Vec3* objects - **derivatives(t: Iterable\[float\], n: int = 2) -\> Iterable\[list\[*Vec3*\]\]** Yields points and derivatives up to *n* \<= degree for parameter vector *t*. e.g. n=1 returns point and 1st derivative. - **Parameters** - • **t** – parameters in range \[0, max\_t\] - • **n** – compute all derivatives up to n \<= degree - **Returns** List of n+1 values as *Vec3* objects - **insert\_knot(t: float) -\> *BSpline*** Insert an additional knot, without altering the shape of the curve. Returns a new *BSpline* object. - **Parameters** **t** – position of new knot 0 \< t \< max\_t - **knot\_refinement(u: Iterable\[float\]) -\> *BSpline*** Insert multiple knots, without altering the shape of the curve. Returns a new *BSpline* object. - **Parameters** **u** – vector of new knots t and for each t: 0 \< t \< max\_t - **static from\_ellipse(ellipse: *ConstructionEllipse*) -\> *BSpline*** Returns the ellipse as *BSpline* of 2nd degree with as few control points as possible. - **static from\_arc(arc: *ConstructionArc*) -\> *BSpline*** Returns the arc as *BSpline* of 2nd degree with as few control points as possible. - **static from\_fit\_points(points: Iterable\[*UVec*\], degree=3, method='chord') -\> *BSpline*** Returns *BSpline* defined by fit points. - **static arc\_approximation(arc: *ConstructionArc*, num: int = 16) -\> *BSpline*** Returns an arc approximation as *BSpline* with *num* control points. - **static ellipse\_approximation(ellipse: *ConstructionEllipse*, num: int = 16) -\> *BSpline*** Returns an ellipse approximation as *BSpline* with *num* control points. - **bezier\_decomposition() -\> Iterable\[list\[*Vec3*\]\]** Decompose a non-rational B-spline into multiple Bézier curves. This is the preferred method to represent the most common non-rational B-splines of 3rd degree by cubic Bézier curves, which are often supported by render backends. - **Returns** Yields control points of Bézier curves, each Bézier segment has degree+1 control points e.g. B-spline of 3rd degree yields cubic Bézier curves of 4 control points. - **cubic\_bezier\_approximation(level: int = 3, segments: int \| None = None) -\> Iterable\[*Bezier4P*\]** Approximate arbitrary B-splines (degree != 3 and/or rational) by multiple segments of cubic Bézier curves. The choice of cubic Bézier curves is based on the widely support of this curves by many render backends. For cubic non-rational B-splines, which is maybe the most common used B-spline, is *bezier\_decomposition()* the better choice. - 1\. approximation by *level*: an educated guess, the first level of approximation segments is based on the count of control points and their distribution along the B-spline, every additional level is a subdivision of the previous level. E.g. a B-Spline of 8 control points has 7 segments at the first level, 14 at the 2nd level and 28 at the 3rd level, a level \>= 3 is recommended. - 2\. approximation by a given count of evenly distributed approximation segments. - **Parameters** - • **level** – subdivision level of approximation segments (ignored if argument *segments* is not **None**) - • **segments** – absolute count of approximation segments - **Returns** Yields control points of cubic Bézier curves as *Bezier4P* objects - **degree\_elevation(t: int) -\> *BSpline*** Returns a new *BSpline* with a t-times elevated degree. Degree elevation increases the degree of a curve without changing the shape of the curve. This method implements the algorithm A5.9 of the “The NURBS Book” by Piegl & Tiller. Added in version 1.4. - **point\_inversion(point: *UVec*, \*, epsilon=1e-8, max\_iterations=100, init=8) -\> float** Returns the parameter t for a point on the curve that is closest to the input point. This is an iterative search using Newton’s method, so there is no guarantee of success, especially for splines with many turns. - **Parameters** - • **point** (*UVec*) – point on the curve or near the curve - • **epsilon** (*float*) – desired precision (distance input point to point on curve) - • **max\_iterations** (*int*) – max iterations for Newton’s method - • **init** (*int*) – number of points to calculate in the initialization phase Added in version 1.4. - **measure(segments: int = 100) -\> *Measurement*** Returns a B-spline measurement tool. All measurements are based on the approximated curve. - **Parameters** **segments** – count of segments for B-spline approximation. Added in version 1.4. - **split(t: float) -\> tuple\[*BSpline*, *BSpline*\]** Splits the B-spline at parameter *t* and returns two new B-splines. - **Raises** **ValuerError** – t out of range 0 \< t \< max\_t Added in version 1.4. - **class ezdxf.math.bspline.Measurement(spline: *BSpline*, segments: int)** B-spline measurement tool. All measurements are based on the approximated curve. Added in version 1.4. - **extmin** minimum extents of the approximated curve as *Vec3* - **extmax** maximum extents of the approximated curve as *Vec3* - **property length: float** Returns the approximated length of the B-spline. - **distance(t: float) -\> float** Returns the distance along the curve from the start point for then given parameter t. - **param\_at(distance: float) -\> float** Returns the parameter t for a given distance along the curve from the start point. - **divide(count: int) -\> list\[float\]** Returns the interpolated B-spline parameters for dividing the curve into *count* segments of equal length. The method yields only the dividing parameters, the first (0.0) and last parameter (max\_t) are not included e.g. dividing a B-spline by 3 yields two parameters \[t1, t2\] that divides the B-spline into 3 parts of equal length. ### Bezier - **class ezdxf.math.Bezier(defpoints: Iterable\[*UVec*\])** Generic *Bézier curve* of any degree. A *Bézier curve* is a parametric curve used in computer graphics and related fields. Bézier curves are used to model smooth curves that can be scaled indefinitely. “Paths”, as they are commonly referred to in image manipulation programs, are combinations of linked Bézier curves. Paths are not bound by the limits of rasterized images and are intuitive to modify. (Source: Wikipedia) This is a generic implementation which works with any count of definition points greater than 2, but it is a simple and slow implementation. For more performance look at the specialized *Bezier4P* and *Bezier3P* classes. Objects are immutable. - **Parameters** **defpoints** – iterable of definition points as *Vec3* compatible objects. - **control\_points** Control points as tuple of *Vec3* objects. - **params(segments: int) -\> Iterable\[float\]** Yield evenly spaced parameters from 0 to 1 for given segment count. - **reverse() -\> *Bezier*** Returns a new Bèzier-curve with reversed control point order. - **transform(m: *Matrix44*) -\> *Bezier*** General transformation interface, returns a new *Bezier* curve. - **Parameters** **m** – 4x4 transformation matrix (*ezdxf.math.Matrix44*) - **approximate(segments: int = 20) -\> Iterable\[*Vec3*\]** Approximates curve by vertices as *Vec3* objects, vertices count = segments + 1. - **flattening(distance: float, segments: int = 4) -\> Iterable\[*Vec3*\]** Adaptive recursive flattening. The argument *segments* is the minimum count of approximation segments, if the distance from the center of the approximation segment to the curve is bigger than *distance* the segment will be subdivided. - **Parameters** - • **distance** – maximum distance from the center of the curve (Cn) to the center of the linear (C1) curve between two approximation points to determine if a segment should be subdivided. - • **segments** – minimum segment count - **point(t: float) -\> *Vec3*** Returns a point for parameter *t* in range \[0, 1\] as *Vec3* object. - **points(t: Iterable\[float\]) -\> Iterable\[*Vec3*\]** Yields multiple points for parameters in vector *t* as *Vec3* objects. Parameters have to be in range \[0, 1\]. - **derivative(t: float) -\> tuple\[*Vec3*, *Vec3*, *Vec3*\]** Returns (point, 1st derivative, 2nd derivative) tuple for parameter *t* in range \[0, 1\] as *Vec3* objects. - **derivatives(t: Iterable\[float\]) -\> Iterable\[tuple\[*Vec3*, *Vec3*, *Vec3*\]\]** Returns multiple (point, 1st derivative, 2nd derivative) tuples for parameter vector *t* as *Vec3* objects. Parameters in range \[0, 1\] ### Bezier4P - **class ezdxf.math.Bezier4P(defpoints: Sequence\[T\])** Implements an optimized cubic *Bézier curve* for exact 4 control points. A *Bézier curve* is a parametric curve, parameter *t* goes from 0 to 1, where 0 is the first control point and 1 is the fourth control point. The class supports points of type *Vec2* and *Vec3* as input, the class instances are immutable. - **Parameters** **defpoints** – sequence of definition points as *Vec2* or *Vec3* compatible objects. - **control\_points** Control points as tuple of *Vec3* or *Vec2* objects. - **reverse() -\> *Bezier4P*\[T\]** Returns a new Bèzier-curve with reversed control point order. - **transform(m: *Matrix44*) -\> *Bezier4P*\[*Vec3*\]** General transformation interface, returns a new **Bezier4p** curve as a 3D curve. - **Parameters** **m** – 4x4 transformation *Matrix44* - **approximate(segments: int) -\> Iterator\[T\]** Approximate *Bézier curve* by vertices, yields *segments* + 1 vertices as **(x, y\[, z\])** tuples. - **Parameters** **segments** – count of segments for approximation - **flattening(distance: float, segments: int = 4) -\> Iterator\[T\]** Adaptive recursive flattening. The argument *segments* is the minimum count of approximation segments, if the distance from the center of the approximation segment to the curve is bigger than *distance* the segment will be subdivided. - **Parameters** - • **distance** – maximum distance from the center of the cubic (C3) curve to the center of the linear (C1) curve between two approximation points to determine if a segment should be subdivided. - • **segments** – minimum segment count - **approximated\_length(segments: int = 128) -\> float** Returns estimated length of Bèzier-curve as approximation by line *segments*. - **point(t: float) -\> T** Returns point for location *t* at the Bèzier-curve. - **Parameters** **t** – curve position in the range **\[0, 1\]** - **tangent(t: float) -\> T** Returns direction vector of tangent for location *t* at the Bèzier-curve. - **Parameters** **t** – curve position in the range **\[0, 1\]** ### Bezier3P - **class ezdxf.math.Bezier3P(defpoints: Sequence\[T\])** Implements an optimized quadratic *Bézier curve* for exact 3 control points. The class supports points of type *Vec2* and *Vec3* as input, the class instances are immutable. - **Parameters** **defpoints** – sequence of definition points as *Vec2* or *Vec3* compatible objects. - **control\_points** Control points as tuple of *Vec3* or *Vec2* objects. - **reverse() -\> *Bezier3P*\[T\]** Returns a new Bèzier-curve with reversed control point order. - **transform(m: *Matrix44*) -\> *Bezier3P*\[*Vec3*\]** General transformation interface, returns a new *Bezier3P* curve and it is always a 3D curve. - **Parameters** **m** – 4x4 transformation *Matrix44* - **approximate(segments: int) -\> Iterator\[T\]** Approximate *Bézier curve* by vertices, yields *segments* + 1 vertices as **(x, y\[, z\])** tuples. - **Parameters** **segments** – count of segments for approximation - **flattening(distance: float, segments: int = 4) -\> Iterator\[T\]** Adaptive recursive flattening. The argument *segments* is the minimum count of approximation segments, if the distance from the center of the approximation segment to the curve is bigger than *distance* the segment will be subdivided. - **Parameters** - • **distance** – maximum distance from the center of the quadratic (C2) curve to the center of the linear (C1) curve between two approximation points to determine if a segment should be subdivided. - • **segments** – minimum segment count - **approximated\_length(segments: int = 128) -\> float** Returns estimated length of Bèzier-curve as approximation by line *segments*. - **point(t: float) -\> T** Returns point for location *t* at the Bèzier-curve. - **Parameters** **t** – curve position in the range **\[0, 1\]** - **tangent(t: float) -\> T** Returns direction vector of tangent for location *t* at the Bèzier-curve. - **Parameters** **t** – curve position in the range **\[0, 1\]** ### ApproxParamT - **class ezdxf.math.ApproxParamT(curve, \*, max\_t: float = 1.0, segments: int = 100)** Approximation tool for parametrized curves. - • approximate parameter *t* for a given distance from the start of the curve - • approximate the distance for a given parameter *t* from the start of the curve These approximations can be applied to all parametrized curves which provide a **point()** method, like *Bezier4P*, *Bezier3P* and *BSpline*. The approximation is based on equally spaced parameters from 0 to *max\_t* for a given segment count. The **flattening()** method can not be used for the curve approximation, because the required parameter *t* is not logged by the flattening process. - **Parameters** - • **curve** – curve object, requires a method **point()** - • **max\_t** – the max. parameter value - • **segments** – count of approximation segments - **property max\_t: float** - **property polyline: *ConstructionPolyline*** - **param\_t(distance: float)** Approximate parameter t for the given *distance* from the start of the curve. - **distance(t: float) -\> float** Approximate the distance from the start of the curve to the point *t* on the curve. ### EulerSpiral - **class ezdxf.math.EulerSpiral(curvature: float = 1.0)** This class represents an euler spiral (clothoid) for *curvature* (Radius of curvature). This is a parametric curve, which always starts at the origin = **(0, 0)**. - **Parameters** **curvature** – radius of curvature - **radius(t: float) -\> float** Get radius of circle at distance *t*. - **tangent(t: float) -\> *Vec3*** Get tangent at distance *t* as *Vec3* object. - **distance(radius: float) -\> float** Get distance L from origin for *radius*. - **point(t: float) -\> *Vec3*** Get point at distance *t* as *Vec3*. - **circle\_center(t: float) -\> *Vec3*** Get circle center at distance *t*. - **approximate(length: float, segments: int) -\> Iterable\[*Vec3*\]** Approximate curve of length with line segments. Generates segments+1 vertices as *Vec3* objects. - **bspline(length: float, segments: int = 10, degree: int = 3, method: str = 'uniform') -\> *BSpline*** Approximate euler spiral as B-spline. - **Parameters** - • **length** – length of euler spiral - • **segments** – count of fit points for B-spline calculation - • **degree** – degree of BSpline - • **method** – calculation method for parameter vector t - **Returns** *BSpline* ### Clipping Clipping module: *ezdxf.math.clipping* - **ezdxf.math.clipping.greiner\_hormann\_union(p1: Iterable\[*UVec*\], p2: Iterable\[*UVec*\]) -\> list\[list\[*Vec2*\]\]** Returns the UNION of polygon *p1* \| polygon *p2*. This algorithm works only for polygons with real intersection points and line end points on face edges are not considered as such intersection points! - **ezdxf.math.clipping.greiner\_hormann\_difference(p1: Iterable\[*UVec*\], p2: Iterable\[*UVec*\]) -\> list\[list\[*Vec2*\]\]** Returns the DIFFERENCE of polygon *p1* - polygon *p2*. This algorithm works only for polygons with real intersection points and line end points on face edges are not considered as such intersection points! - **ezdxf.math.clipping.greiner\_hormann\_intersection(p1: Iterable\[*UVec*\], p2: Iterable\[*UVec*\]) -\> list\[list\[*Vec2*\]\]** Returns the INTERSECTION of polygon *p1* & polygon *p2*. This algorithm works only for polygons with real intersection points and line end points on face edges are not considered as such intersection points! - **class ezdxf.math.clipping.ConvexClippingPolygon2d(vertices: Iterable\[*Vec2*\], ccw\_check=True, abs\_tol=TOLERANCE)** The clipping path is an arbitrary convex 2D polygon. - **clip\_polygon(polygon: Sequence\[*Vec2*\]) -\> Sequence\[Sequence\[*Vec2*\]\]** Returns the parts of the clipped polygon. A polygon is a closed polyline. - **clip\_polyline(polyline: Sequence\[*Vec2*\]) -\> Sequence\[Sequence\[*Vec2*\]\]** Returns the parts of the clipped polyline. - **clip\_line(start: *Vec2*, end: *Vec2*) -\> Sequence\[tuple\[*Vec2*, *Vec2*\]\]** Returns the parts of the clipped line. - **is\_inside(point: *Vec2*) -\> bool** Returns **True** if *point* is inside the clipping polygon. - **class ezdxf.math.clipping.ClippingRect2d(bottom\_left: *Vec2*, top\_right: *Vec2*, abs\_tol=TOLERANCE)** The clipping path is an axis-aligned rectangle, where all sides are parallel to the x- and y-axis. - **clip\_polygon(polygon: Sequence\[*Vec2*\]) -\> Sequence\[Sequence\[*Vec2*\]\]** Returns the parts of the clipped polygon. A polygon is a closed polyline. - **clip\_polyline(polyline: Sequence\[*Vec2*\]) -\> Sequence\[Sequence\[*Vec2*\]\]** Returns the parts of the clipped polyline. - **clip\_line(start: *Vec2*, end: *Vec2*) -\> Sequence\[tuple\[*Vec2*, *Vec2*\]\]** Returns the clipped line. - **is\_inside(point: *Vec2*) -\> bool** Returns **True** if *point* is inside the clipping rectangle. - **class ezdxf.math.clipping.ConcaveClippingPolygon2d(vertices: Iterable\[*Vec2*\], abs\_tol=TOLERANCE)** The clipping path is an arbitrary concave 2D polygon. - **clip\_polygon(polygon: Sequence\[*Vec2*\]) -\> Sequence\[Sequence\[*Vec2*\]\]** Returns the parts of the clipped polygon. A polygon is a closed polyline. - **clip\_polyline(polyline: Sequence\[*Vec2*\]) -\> Sequence\[Sequence\[*Vec2*\]\]** Returns the parts of the clipped polyline. - **clip\_line(start: *Vec2*, end: *Vec2*) -\> Sequence\[tuple\[*Vec2*, *Vec2*\]\]** Returns the clipped line. - **is\_inside(point: *Vec2*) -\> bool** Returns **True** if *point* is inside the clipping polygon. - **class ezdxf.math.clipping.InvertedClippingPolygon2d(inner\_polygon: Iterable\[*Vec2*\], outer\_bounds: *BoundingBox2d*, abs\_tol=TOLERANCE)** This class represents an inverted clipping path. Everything between the inner polygon and the outer extents is considered as inside. The inner clipping path is an arbitrary 2D polygon. **IMPORTANT:** The *outer\_bounds* must be larger than the content to clip to work correctly. - **clip\_polygon(polygon: Sequence\[*Vec2*\]) -\> Sequence\[Sequence\[*Vec2*\]\]** Returns the parts of the clipped polygon. A polygon is a closed polyline. - **clip\_polyline(polyline: Sequence\[*Vec2*\]) -\> Sequence\[Sequence\[*Vec2*\]\]** Returns the parts of the clipped polyline. - **clip\_line(start: *Vec2*, end: *Vec2*) -\> Sequence\[tuple\[*Vec2*, *Vec2*\]\]** Returns the clipped line. - **is\_inside(point: *Vec2*) -\> bool** Returns **True** if *point* is inside the clipping polygon. ### Clustering Clustering module: *ezdxf.math.clustering* - **ezdxf.math.clustering.average\_cluster\_radius(clusters: list\[list\[*Vec2* \| *Vec3*\]\]) -\> float** Returns the average cluster radius. - **ezdxf.math.clustering.average\_intra\_cluster\_distance(clusters: list\[list\[*Vec2* \| *Vec3*\]\]) -\> float** Returns the average point-to-point intra cluster distance. - **ezdxf.math.clustering.dbscan(points: list\[*Vec2* \| *Vec3*\], \*, radius: float, min\_points: int = 4, rtree: *RTree* \| None = None, max\_node\_size: int = 5) -\> list\[list\[*Vec2* \| *Vec3*\]\]** DBSCAN clustering. *https://en.wikipedia.org/wiki/DBSCAN* - **Parameters** - • **points** – list of points to cluster - • **radius** – radius of the dense regions - • **min\_points** – minimum number of points that needs to be within the *radius* for a point to be a core point (must be \>= 2) - • **rtree** – optional *RTree* - • **max\_node\_size** – max node size for internally created RTree - **Returns** list of clusters, each cluster is a list of points - **ezdxf.math.clustering.k\_means(points: list\[*Vec2* \| *Vec3*\], k: int, max\_iter: int = 10) -\> list\[list\[*Vec2* \| *Vec3*\]\]** K-means clustering. *https://en.wikipedia.org/wiki/K-means\_clustering* - **Parameters** - • **points** – list of points to cluster - • **k** – number of clusters - • **max\_iter** – max iterations - **Returns** list of clusters, each cluster is a list of points ### Linear Algebra Linear algebra module **for internal usage**: *ezdxf.math.linalg* ### Functions - **ezdxf.math.linalg.tridiagonal\_vector\_solver(A: List\[List\[float\]\], B: Iterable\[float\]) -\> list\[float\]** Solves the linear equation system given by a tri-diagonal nxn Matrix A . x = B, right-hand side quantities as vector B. Matrix A is diagonal matrix defined by 3 diagonals \[-1 (a), 0 (b), +1 (c)\]. Note: a0 is not used but has to be present, cn-1 is also not used and must not be present. If an **ZeroDivisionError** exception occurs, the equation system can possibly be solved by **BandedMatrixLU(A, 1, 1).solve\_vector(B)** - **Parameters** - • **A** – diagonal matrix \[\[a0..an-1\], \[b0..bn-1\], \[c0..cn-1\]\] ``` [[b0, c0, 0, 0, ...], [a1, b1, c1, 0, ...], [0, a2, b2, c2, ...], ... ] ``` - • **B** – iterable of floats \[\[b1, b1, …, bn\] - **Returns** list of floats - **Raises** **ZeroDivisionError** – singular matrix - **ezdxf.math.linalg.tridiagonal\_matrix\_solver(A: List\[List\[float\]\] \| ndarray\[tuple\[int, ...\], dtype\[float64\]\], B: List\[List\[float\]\] \| ndarray\[tuple\[int, ...\], dtype\[float64\]\]) -\> *Matrix*** Solves the linear equation system given by a tri-diagonal nxn Matrix A . x = B, right-hand side quantities as nxm Matrix B. Matrix A is diagonal matrix defined by 3 diagonals \[-1 (a), 0 (b), +1 (c)\]. Note: a0 is not used but has to be present, cn-1 is also not used and must not be present. If an **ZeroDivisionError** exception occurs, the equation system can possibly be solved by **BandedMatrixLU(A, 1, 1).solve\_vector(B)** - **Parameters** - • **A** – diagonal matrix \[\[a0..an-1\], \[b0..bn-1\], \[c0..cn-1\]\] ``` [[b0, c0, 0, 0, ...], [a1, b1, c1, 0, ...], [0, a2, b2, c2, ...], ... ] ``` - • **B** – matrix \[\[b11, b12, …, b1m\], \[b21, b22, …, b2m\], … \[bn1, bn2, …, bnm\]\] - **Returns** matrix as *Matrix* object - **Raises** **ZeroDivisionError** – singular matrix - **ezdxf.math.linalg.banded\_matrix(A: *Matrix*, check\_all=True) -\> tuple\[*Matrix*, int, int\]** Transform matrix A into a compact banded matrix representation. Returns compact representation as *Matrix* object and lower- and upper band count m1 and m2. - **Parameters** - • **A** – input *Matrix* - • **check\_all** – check all diagonals if **True** or abort testing after first all zero diagonal if **False**. - **ezdxf.math.linalg.detect\_banded\_matrix(A: *Matrix*, check\_all=True) -\> tuple\[int, int\]** Returns lower- and upper band count m1 and m2. - **Parameters** - • **A** – input *Matrix* - • **check\_all** – check all diagonals if **True** or abort testing after first all zero diagonal if **False**. - **ezdxf.math.linalg.compact\_banded\_matrix(A: *Matrix*, m1: int, m2: int) -\> *Matrix*** Returns compact banded matrix representation as *Matrix* object. - **Parameters** - • **A** – matrix to transform - • **m1** – lower band count, excluding main matrix diagonal - • **m2** – upper band count, excluding main matrix diagonal ### Matrix Class - **class ezdxf.math.linalg.Matrix(items: Any = None, shape: Tuple\[int, int\] \| None = None, matrix: List\[List\[float\]\] \| ndarray\[tuple\[int, ...\], dtype\[float64\]\] \| None = None)** Basic matrix implementation based **numpy.ndarray**. Matrix data is stored in row major order, this means in a list of rows, where each row is a list of floats. Initialization: - • Matrix(shape=(rows, cols)) … new matrix filled with zeros - • Matrix(matrix\[, shape=(rows, cols)\]) … from copy of matrix and optional reshape - • Matrix(\[\[row\_0\], \[row\_1\], …, \[row\_n\]\]) … from Iterable\[Iterable\[float\]\] - • Matrix(\[a1, a2, …, an\], shape=(rows, cols)) … from Iterable\[float\] and shape Changed in version 1.2: Implementation based on **numpy.ndarray**. - **matrix** matrix data as **numpy.ndarray** - **nrows** Count of matrix rows. - **ncols** Count of matrix columns. - **shape** Shape of matrix as (n, m) tuple for n rows and m columns. - **append\_col(items: Sequence\[float\]) -\> None** Append a column to the matrix. - **append\_row(items: Sequence\[float\]) -\> None** Append a row to the matrix. - **col(index: int) -\> list\[float\]** Return column *index* as list of floats. - **cols() -\> list\[list\[float\]\]** Return a list of all columns. - **determinant() -\> float** Returns determinant of matrix, raises **ZeroDivisionError** if matrix is singular. - **diag(index: int) -\> list\[float\]** Returns diagonal *index* as list of floats. An *index* of 0 specifies the main diagonal, negative values specifies diagonals below the main diagonal and positive values specifies diagonals above the main diagonal. e.g. given a 4x4 matrix: - • index 0 is \[00, 11, 22, 33\], - • index -1 is \[10, 21, 32\] and - • index +1 is \[01, 12, 23\] - **freeze() -\> *Matrix*** Returns a frozen matrix, all data is stored in immutable tuples. - **classmethod identity(shape: Tuple\[int, int\]) -\> *Matrix*** Returns the identity matrix for configuration *shape*. - **inverse() -\> *Matrix*** Returns inverse of matrix as new object. - **isclose(other: object) -\> bool** Returns **True** if matrices are close to equal, tolerance value for comparison is adjustable by the attribute **Matrix.abs\_tol**. - **static reshape(items: Iterable\[float\], shape: Tuple\[int, int\]) -\> *Matrix*** Returns a new matrix for iterable *items* in the configuration of *shape*. - **row(index: int) -\> list\[float\]** Returns row *index* as list of floats. - **rows() -\> list\[list\[float\]\]** Return a list of all rows. - **set\_col(index: int, items: float \| Iterable\[float\] = 1.0) -\> None** Set column values to a fixed value or from an iterable of floats. - **set\_diag(index: int = 0, items: float \| Iterable\[float\] = 1.0) -\> None** Set diagonal values to a fixed value or from an iterable of floats. An *index* of **0** specifies the main diagonal, negative values specifies diagonals below the main diagonal and positive values specifies diagonals above the main diagonal. e.g. given a 4x4 matrix: index **0** is \[00, 11, 22, 33\], index **-1** is \[10, 21, 32\] and index **+1** is \[01, 12, 23\] - **set\_row(index: int, items: float \| Iterable\[float\] = 1.0) -\> None** Set row values to a fixed value or from an iterable of floats. - **transpose() -\> *Matrix*** Returns a new transposed matrix. - **\_\_getitem\_\_(item: tuple\[int, int\]) -\> float** Get value by (row, col) index tuple, fancy slicing as known from numpy is not supported. - **\_\_setitem\_\_(item: tuple\[int, int\], value: float)** Set value by (row, col) index tuple, fancy slicing as known from numpy is not supported. - **\_\_eq\_\_(other: object) -\> bool** Returns **True** if matrices are equal. - **\_\_add\_\_(other: *Matrix* \| float) -\> *Matrix*** Matrix addition by another matrix or a float, returns a new matrix. - **\_\_sub\_\_(other: *Matrix* \| float) -\> *Matrix*** Matrix subtraction by another matrix or a float, returns a new matrix. - **\_\_mul\_\_(other: *Matrix* \| float) -\> *Matrix*** Matrix multiplication by another matrix or a float, returns a new matrix. ### NumpySolver - **class ezdxf.math.linalg.NumpySolver(A: List\[List\[float\]\] \| ndarray\[tuple\[int, ...\], dtype\[float64\]\])** Replaces in v1.2 the **LUDecomposition** solver. - **solve\_vector(B: Iterable\[float\]) -\> list\[float\]** Solves the linear equation system given by the nxn Matrix A . x = B, right-hand side quantities as vector B with n elements. - **Parameters** **B** – vector \[b1, b2, …, bn\] - **Raises** **numpy.linalg.LinAlgError** – singular matrix - **solve\_matrix(B: List\[List\[float\]\] \| ndarray\[tuple\[int, ...\], dtype\[float64\]\]) -\> *Matrix*** Solves the linear equation system given by the nxn Matrix A . x = B, right-hand side quantities as nxm Matrix B. - **Parameters** **B** – matrix \[\[b11, b12, …, b1m\], \[b21, b22, …, b2m\], … \[bn1, bn2, …, bnm\]\] - **Raises** **numpy.linalg.LinAlgError** – singular matrix ### BandedMatrixLU Class - **class ezdxf.math.linalg.BandedMatrixLU(A: *Matrix*, m1: int, m2: int)** Represents a LU decomposition of a compact banded matrix. - **upper** Upper triangle - **lower** Lower triangle - **m1** Lower band count, excluding main matrix diagonal - **m2** Upper band count, excluding main matrix diagonal - **index** Swapped indices - **nrows** Count of matrix rows. - **solve\_vector(B: Iterable\[float\]) -\> list\[float\]** Solves the linear equation system given by the banded nxn Matrix A . x = B, right-hand side quantities as vector B with n elements. - **Parameters** **B** – vector \[b1, b2, …, bn\] - **Returns** vector as list of floats - **solve\_matrix(B: List\[List\[float\]\] \| ndarray\[tuple\[int, ...\], dtype\[float64\]\]) -\> *Matrix*** Solves the linear equation system given by the banded nxn Matrix A . x = B, right-hand side quantities as nxm Matrix B. - **Parameters** **B** – matrix \[\[b11, b12, …, b1m\], \[b21, b22, …, b2m\], … \[bn1, bn2, …, bnm\]\] - **Returns** matrix as *Matrix* object ### RTree RTree module: *ezdxf.math.rtree* - **class ezdxf.math.rtree.RTree(points: Iterable\[T\], max\_node\_size: int = 5)** Immutable spatial search tree loosely based on *R-trees*. The search tree is buildup once at initialization and immutable afterwards, because rebuilding the tree after inserting or deleting nodes is very costly and makes the implementation very complex. Without the ability to alter the content the restrictions which forces the tree balance at growing and shrinking of the original *R-trees*, are ignored, like the fixed minimum and maximum node size. This class uses internally only 3D bounding boxes, but also supports **Vec2** as well as **Vec3** objects as input data, but point types should not be mixed in a search tree. The point objects keep their type and identity and the returned points of queries can be compared by the **is** operator for identity to the input points. The implementation requires a maximum node size of at least 2 and does not support empty trees! - **Raises** **ValueError** – max. node size too small or no data given - **\_\_len\_\_()** Returns the count of points in the search tree. - **\_\_iter\_\_() -\> Iterator\[T\]** Yields all points in the search tree. - **contains(point: T) -\> bool** Returns **True** if *point* exists, the comparison is done by the **isclose()** method and not by the identity operator **is**. - **nearest\_neighbor(target: T) -\> tuple\[T, float\]** Returns the closest point to the *target* point and the distance between these points. - **points\_in\_sphere(center: T, radius: float) -\> Iterator\[T\]** Returns all points in the range of the given sphere including the points at the boundary. - **points\_in\_bbox(bbox: *BoundingBox*) -\> Iterator\[T\]** Returns all points in the range of the given bounding box including the points at the boundary. - **avg\_leaf\_size(spread: float = 1.0) -\> float** Returns the average size of the leaf bounding boxes. The size of a leaf bounding box is the maximum size in all dimensions. Excludes outliers of sizes beyond mean + standard deviation \* spread. Returns 0.0 if less than two points in tree. - **avg\_spherical\_envelope\_radius(spread: float = 1.0) -\> float** Returns the average radius of spherical envelopes of the leaf nodes. Excludes outliers with radius beyond mean + standard deviation \* spread. Returns 0.0 if less than two points in tree. - **avg\_nn\_distance(spread: float = 1.0) -\> float** Returns the average of the nearest neighbor distances inside (!) leaf nodes. Excludes outliers with a distance beyond the overall mean + standard deviation \* spread. Returns 0.0 if less than two points in tree. **WARNING:** This is a brute force check with O(n!) for each leaf node, where n is the point count of the leaf node. ### Triangulation Triangulation module: *ezdxf.math.triangulation* - **ezdxf.math.triangulation.mapbox\_earcut\_2d(exterior: Iterable\[*UVec*\], holes: Iterable\[Iterable\[*UVec*\]\] \| None = None) -\> list\[Sequence\[*Vec2*\]\]** Mapbox triangulation algorithm with hole support for 2D polygons. Implements a modified ear slicing algorithm, optimized by z-order curve hashing and extended to handle holes, twisted polygons, degeneracies and self-intersections in a way that doesn’t guarantee correctness of triangulation, but attempts to always produce acceptable results for practical data. Source: *https://github.com/mapbox/earcut* - **Parameters** - • **exterior** – exterior polygon as iterable of **Vec2** objects - • **holes** – iterable of holes as iterable of **Vec2** objects, a hole with single point represents a *Steiner point*. - **Returns** yields the result as 3-tuples of **Vec2** objects - **ezdxf.math.triangulation.mapbox\_earcut\_3d(exterior: Iterable\[*UVec*\], holes: Iterable\[Iterable\[*UVec*\]\] \| None = None) -\> Iterator\[Sequence\[*Vec3*\]\]** Mapbox triangulation algorithm with hole support for flat 3D polygons. Implements a modified ear slicing algorithm, optimized by z-order curve hashing and extended to handle holes, twisted polygons, degeneracies and self-intersections in a way that doesn’t guarantee correctness of triangulation, but attempts to always produce acceptable results for practical data. Source: *https://github.com/mapbox/earcut* - **Parameters** - • **exterior** – exterior polygon as iterable of **Vec3** objects - • **holes** – iterable of holes as iterable of **Vec3** objects, a hole with single point represents a *Steiner point*. - **Returns** yields the result as 3-tuples of **Vec3** objects - **Raises** - • **TypeError** – invalid input data type - • **ZeroDivisionError** – normal vector calculation failed ### Construction ### ACIS Tools The *ezdxf.acis* sub-package provides some *ACIS* data management tools. The main goals of this tools are: - 1\. load and parse simple and known *ACIS* data structures - 2\. create and export simple and known *ACIS* data structures It is NOT a goal to load and edit arbitrary existing *ACIS* structures. Don’t even try it! These tools cannot replace the official *ACIS* SDK due to the complexity of the data structures and the absence of an *ACIS* kernel. Without access to the full documentation it is very cumbersome to reverse-engineer entities and their properties, therefore the analysis of the *ACIS* data structures is limited to the use as embedded data in DXF and DWG files. The *ezdxf* library does not provide an *ACIS* kernel and there are no plans for implementing one because this is far beyond my capabilities, but it is possible to extract geometries made up only by flat polygonal faces (polyhedron) from ACIS data. Exporting polyhedrons as ACIS data and loading this DXF file by Autodesk products or BricsCAD works for *SAT* data for DXF R2000-R2010 and for *SAB* data for DXF R2013-R2018. **IMPORTANT:** Always import from the public interface module *ezdxf.acis.api*, the internal package and module structure may change in the future and imports from other modules than **api** will break. ### Functions - **ezdxf.acis.api.load\_dxf(entity: DXFEntity) -\> list\[*Body*\]** Load the *ACIS* bodies from the given DXF entity. This is the recommended way to load ACIS data. The DXF entity has to be an ACIS based entity and inherit from *ezdxf.entities.Body*. The entity has to be bound to a valid DXF document and the DXF version of the document has to be DXF R2000 or newer. - **Raises** - • *DXFTypeError* – invalid DXF entity type - • *DXFValueError* – invalid DXF document - • *DXFVersionError* – invalid DXF version **WARNING:** Only a limited count of *ACIS* entities is supported, all unsupported entities are loaded as **NONE\_ENTITY** and their data is lost. Exporting such **NONE\_ENTITIES** will raise an *ExportError* exception. To emphasize that again: **It is not possible to load and re-export** **arbitrary ACIS data!** Example: ``` import ezdxf from ezdxf.acis import api as acis doc = ezdxf.readfile("your.dxf") msp = doc.modelspace() for e in msp.query("3DSOLID"): bodies = acis.load_dxf(e) ... ``` - **ezdxf.acis.api.export\_dxf(entity: DXFEntity, bodies: Sequence\[*Body*\])** Store the *ACIS* bodies in the given DXF entity. This is the recommended way to set ACIS data of DXF entities. The DXF entity has to be an ACIS based entity and inherit from *ezdxf.entities.Body*. The entity has to be bound to a valid DXF document and the DXF version of the document has to be DXF R2000 or newer. - **Raises** - • *DXFTypeError* – invalid DXF entity type - • *DXFValueError* – invalid DXF document - • *DXFVersionError* – invalid DXF version Example: ``` import ezdxf from ezdxf.render import forms from ezdxf.acis import api as acis doc = ezdxf.new("R2000") msp = doc.modelspace() # create an ACIS body from a simple cube-mesh body = acis.body_from_mesh(forms.cube()) solid3d = msp.add_3dsolid() acis.export_dxf(solid3d, [body]) doc.saveas("cube.dxf") ``` - **ezdxf.acis.api.load(data: str \| Sequence\[str\] \| bytes \| bytearray) -\> list\[*Body*\]** Returns a list of **Body** entities from *SAT* or *SAB* data. Accepts *SAT* data as a single string or a sequence of strings and *SAB* data as bytes or bytearray. - **ezdxf.acis.api.export\_sat(bodies: Sequence\[*Body*\], version: int = const.DEFAULT\_SAT\_VERSION) -\> list\[str\]** Export one or more **Body** entities as text based *SAT* data. ACIS version 700 is sufficient for DXF versions R2000, R2004, R2007 and R2010, later DXF versions require *SAB* data. - **Raises** - • *ExportError* – ACIS structures contain unsupported entities - • *InvalidLinkStructure* – corrupt link structure - **ezdxf.acis.api.export\_sab(bodies: Sequence\[*Body*\], version: int = const.DEFAULT\_SAB\_VERSION) -\> bytes** Export one or more **Body** entities as binary encoded *SAB* data. ACIS version 21800 is sufficient for DXF versions R2013 and R2018, earlier DXF versions require *SAT* data. - **Raises** - • *ExportError* – ACIS structures contain unsupported entities - • *InvalidLinkStructure* – corrupt link structure - **ezdxf.acis.api.mesh\_from\_body(body: *Body*, merge\_lumps=True) -\> list\[MeshTransformer\]** Returns a list of *MeshTransformer* instances from the given ACIS **Body** entity. The list contains multiple meshes if *merge\_lumps* is **False** or just a single mesh if *merge\_lumps* is **True**. The ACIS format stores the faces in counter-clockwise orientation where the face-normal points outwards (away) from the solid body (material). **NOTE:** This function returns meshes build up only from flat polygonal **Face** entities, for a tessellation of more complex ACIS entities (spline surfaces, tori, cones, …) is an ACIS kernel required which *ezdxf* does not provide. - **Parameters** - • **body** – ACIS entity of type **Body** - • **merge\_lumps** – returns all **Lump** entities from a body as a single mesh if **True** otherwise each **Lump** entity is a separated mesh - **Raises** **TypeError** – given *body* entity has invalid type The following images show the limitations of the *mesh\_from\_body()* function. The first image shows the source **3DSOLID** entities with subtraction of entities with flat and curved faces: \[image\] Example script to extracts all flat polygonal faces as meshes: ``` import ezdxf from ezdxf.acis import api as acis doc = ezdxf.readfile("3dsolids.dxf") msp = doc.modelspace() doc_out = ezdxf.new() msp_out = doc_out.modelspace() for e in msp.query("3DSOLID"): for body in acis.load_dxf(data): for mesh in acis.mesh_from_body(body): mesh.render_mesh(msp_out) doc_out.saveas("meshes.dxf") ``` The second image shows the flat faces extracted from the **3DSOLID** entities and exported as *Mesh* entities: \[image\] As you can see all faces which do not have straight lines as boundaries are lost. - **ezdxf.acis.api.body\_from\_mesh(mesh: MeshBuilder, precision: int = 6) -\> *Body*** Returns a *ACIS* *Body* entity from a *MeshBuilder* instance. This entity can be assigned to a *Solid3d* DXF entity as *SAT* or *SAB* data according to the version your DXF document uses (SAT for DXF R2000 to R2010 and SAB for DXF R2013 and later). If the *mesh* contains multiple separated meshes, each mesh will be a separated *Lump* node. If each mesh should get its own *Body* entity, separate the meshes beforehand by the method *separate\_meshes()*. A closed mesh creates a solid body and an open mesh creates an open (hollow) shell. The detection if the mesh is open or closed is based on the edges of the mesh: if **all** edges of mesh have two adjacent faces the mesh is closed. The current implementation applies automatically a vertex optimization, which merges coincident vertices into a single vertex. - **ezdxf.acis.api.vertices\_from\_body(body: *Body*) -\> list\[*Vec3*\]** Returns all stored vertices in the given **Body** entity. The result is not optimized, meaning the vertices are in no particular order and there are duplicates. This function can be useful to determining the approximate bounding box of an *ACIS* entity. The result is exact for polyhedra with flat faces with straight edges, but not for bodies with curved edges and faces. - **Parameters** **body** – ACIS entity of type **Body** - **Raises** **TypeError** – given *body* entity has invalid type ### Exceptions - **class ezdxf.acis.api.AcisException** Base exception of the *ezdxf.acis* package. - **class ezdxf.acis.api.ParsingError** Exception raised when loading invalid or unknown *ACIS* structures. - **class ezdxf.acis.api.ExportError** Exception raised when exporting invalid or unknown *ACIS* structures. - **class ezdxf.acis.api.InvalidLinkStructure** Exception raised when the internal link structure is damaged. ### Entities A document (*sat.pdf*) about the basic ACIS 7.0 file format is floating in the internet. This section contains the additional information about the entities, I got from analyzing the SAT data extracted from DXF files exported by BricsCAD. This documentation ignores the differences to the ACIS format prior to version 7.0 and all this differences are handled internally. Writing support for ACIS version \< 7.0 is not required because all CAD applications should be able to process version 7.0, even if embedded in a very old DXF R2000 format (tested with Autodesk TrueView, BricsCAD and Nemetschek Allplan). The first goal is to document the entities which are required to represent a geometry as flat polygonal faces (polyhedron), which can be converted into a *MeshBuilder* object. Topology Entities: - • *Body* - • *Lump* - • *Shell* - • *Face* - • *Loop* - • *Coedge* - • *Edge* - • *Vertex* Geometry Entities: - • *Transform* - • *Surface* - • *Plane* - • *Curve* - • *StraightCurve* - • *Point* - **ezdxf.acis.entities.NONE\_REF** Special sentinel entity which supports the **type** attribute and the **is\_none** property. Represents all unset entities. Use this idiom on any entity type to check if an entity is unset: ``` if entity.is_none: ... ``` ### AcisEntity - **class ezdxf.acis.entities.AcisEntity** Base class for all ACIS entities. - **type** Name of the type as str. - **id** Unique id as int or -1 if not set. - **attributes** Reference to the first **Attribute** entity (not supported). - **is\_none** **True** for unset entities represented by the *NONE\_REF* instance. ### Transform - **class ezdxf.acis.entities.Transform(AcisEntity)** Represents an affine transformation operation which transform the **body** to the final location, size and rotation. - **matrix** Transformation matrix of type *ezdxf.math.Matrix44*. ### Body - **class ezdxf.acis.entities.Body(AcisEntity)** Represents a solid geometry, which can consist of multiple *Lump* entities. - **pattern** Reference to the *Pattern* entity. - **lump** Reference to the first *Lump* entity - **wire** Reference to the first *Wire* entity - **transform** Reference to the *Transform* entity (optional) - **lumps() -\> list\[*Lump*\]** Returns all linked *Lump* entities as a list. - **append\_lump(lump: *Lump*) -\> None** Append a *Lump* entity as last lump. ### Pattern - **class ezdxf.acis.entities.Pattern(AcisEntity)** Not implemented. ### Lump - **class ezdxf.acis.entities.Lump(AcisEntity)** The lump represents a connected entity and there can be multiple lumps in a *Body*. Multiple lumps are linked together by the *next\_lump* attribute which points to the next lump entity the last lump has a **NONE\_REF** as next lump. The *body* attribute references to the parent *Body* entity. - **next\_lump** Reference to the next *Lump* entity, the last lump references *NONE\_REF*. - **shell** Reference to the *Shell* entity. - **body** Reference to the parent *Body* entity. - **shells() -\> list\[*Shell*\]** Returns all linked *Shell* entities as a list. - **append\_shell(shell: *Shell*) -\> None** Append a *Shell* entity as last shell. ### Wire - **class ezdxf.acis.entities.Wire(AcisEntity)** Not implemented. ### Shell - **class ezdxf.acis.entities.Shell(AcisEntity)** A shell defines the boundary of a solid object or a void (subtraction object). A shell references a list of *Face* and *Wire* entities. All linked *Shell* entities are disconnected. - **next\_shell** Reference to the next *Shell* entity, the last shell references *NONE\_REF*. - **subshell** Reference to the first *Subshell* entity. - **face** Reference to the first *Face* entity. - **wire** Reference to the first *Wire* entity. - **lump** Reference to the parent *Lump* entity. - **faces() -\> list\[*Face*\]** Returns all linked *Face* entities as a list. - **append\_face(face: *Face*) -\> None** Append a *Face* entity as last face. ### Subshell - **class ezdxf.acis.entities.Subshell(AcisEntity)** Not implemented. ### Face - **class ezdxf.acis.entities.Face(AcisEntity)** A face is the building block for *Shell* entities. The boundary of a face is represented by one or more *Loop* entities. The spatial geometry of the face is defined by the *surface* object, which is a bounded or unbounded parametric 3d surface (plane, ellipsoid, spline-surface, …). - **next\_face** Reference to the next *Face* entity, the last face references *NONE\_REF*. - **loop** Reference to the first *Loop* entity. - **shell** Reference to the parent *Shell* entity. - **subshell** Reference to the parent *Subshell* entity. - **surface** Reference to the parametric *Surface* geometry. - **sense** Boolean value of direction of the face normal with respect to the *Surface* entity: - • **True**: “reversed” direction of the face normal - • **False**: “forward” for same direction of the face normal - **double\_sided** Boolean value which indicates the sides of the face: - • **True**: the face is part of a hollow object and has two sides. - • **False**: the face is part of a solid object and has only one side which points away from the “material”. - **containment** Unknown meaning. If *double\_sided* is **True**: - • **True** is “in” - • **False** is “out” - **loops() -\> list\[*Loop*\]** Returns all linked *Loop* entities as a list. - **append\_loop(loop: *Loop*) -\> None** Append a *Loop* entity as last loop. ### Loop - **class ezdxf.acis.entities.Loop(AcisEntity)** A loop represents connected coedges which are building the boundaries of a *Face*, there can be multiple loops for a single face e.g. faces can contain holes. The *coedge* attribute references the first *Coedge* of the loop, the additional coedges are linked to this first *Coedge*. In closed loops the coedges are organized as a circular list, in open loops the last coedge references the *NONE\_REF* entity as **next\_coedge** and the first coedge references the *NONE\_REF* as **prev\_coedge**. - **next\_loop** Reference to the next *Loop* entity, the last loop references *NONE\_REF*. - **coedge** Reference to the first *Coedge* entity. - **face** Reference to the parent *Face* entity. - **coedges() -\> list\[*Coedge*\]** Returns all linked *Coedge* entities as a list. - **set\_coedges(coedges: list\[*Coedge*\], close=True) -\> None** Set all coedges of a loop at once. ### Coedge - **class ezdxf.acis.entities.Coedge(AcisEntity)** The coedges are a double linked list where *next\_coedge* points to the next *Coedge* and *prev\_coedge* to the previous *Coedge*. The *partner\_coedge* attribute references the first partner *Coedge* of an adjacent *Face*, the partner edges are organized as a circular list. In a manifold closed surface each *Face* is connected to one partner face by an *Coedge*. In a non-manifold surface a face can have more than one partner face. - **next\_coedge** References the next *Coedge*, reference the *NONE\_REF* if it is the last coedge in an open *Loop*. - **prev\_coedge** References the previous *Coedge*, reference the *NONE\_REF* if it is the first coedge in an open *Loop*. - **partner\_coedge** References the partner *Coedge* of an adjacent *Face* entity. The partner coedges are organized in a circular list. - **edge** References the *Edge* entity. - **loop** References the parent *Loop* entity. - **pcurve** References the *PCurve* entity. ### Edge - **class ezdxf.acis.entities.Edge(AcisEntity)** The *Edge* entity represents the physical edge of an object. Its geometry is defined by the bounded portion of a parametric space curve. This bounds are stored as object-space *Vertex* entities. - **start\_vertex** The start *Vertex* of the space-curve in object coordinates, if *NONE\_REF* the curve is unbounded in this direction. - **start\_param** The parametric starting bound for the parametric curve. Evaluating the *curve* for this parameter should return the coordinates of the *start\_vertex*. - **end\_vertex** The end *Vertex* of the space-curve in object coordinates, if *NONE\_REF* the curve is unbounded in this direction. - **end\_param** The parametric end bound for the parametric curve. - **coedge** Parent *Coedge* of this edge. - **curve** The parametric space-curve which defines this edge. The curve can be the **NULL\_REF** while both *Vertex* entities are the same vertex. In this case the *Edge* represents an single point like the apex of a cone. - **sense** Boolean value which indicates the direction of the edge: - • **True**: the edge has the “reversed” direction as the underlying curve - • **False**: the edge has the same direction as the underlying curve (“forward”) - **convexity** Unknown meaning, always the string “unknown”. ### Vertex - **class ezdxf.acis.entities.Vertex(AcisEntity)** Represents a vertex of an *Edge* entity and references a *Point* entity. - **point** The spatial location in object-space as *Point* entity. - **edge** Parent *Edge* of this vertex. The vertex can be referenced by multiple edges, anyone of them can be the parent of the vertex. ### Surface - **class ezdxf.acis.entities.Surface(AcisEntity)** Abstract base class for all parametric surfaces. The parameterization of any *Surface* maps a 2D rectangle (u, v parameters) into the spatial object-space (x, y, z). - **u\_bounds** Tuple of (start bound, end bound) parameters as two floats which define the bounds of the parametric surface in the u-direction, one or both values can be **math.inf** which indicates an unbounded state of the surface in that direction. - **v\_bounds** Tuple of (start bound, end bound) parameters as two floats which define the bounds of the parametric surface in the v-direction, one or both values can be **math.inf** which indicates an unbounded state of the surface in that direction. - **abstract evaluate(u: float, v: float) -\> *Vec3*** Returns the spatial location at the parametric surface for the given parameters *u* and *v*. ### Plane - **class ezdxf.acis.entities.Plane(Surface)** Defines a flat plan as parametric surface. - **origin** Location vector of the origin of the flat plane as *Vec3*. - **normal** Normal vector of the plane as *Vec3*. Has to be an unit-vector! - **u\_dir** Direction vector of the plane in u-direction as *Vec3*. Has to be an unit-vector! - **v\_dir** Direction vector of the plane in v-direction as *Vec3*. Has to be an unit-vector! - **reverse\_v** Boolean value which indicates the orientation of the coordinate system: - • **True**: left-handed system, the v-direction is reversed and the normal vector is *v\_dir* cross *u\_dir*. - • **False**: right-handed system and the normal vector is *u\_dir* cross *v\_dir*. ### Curve - **class ezdxf.acis.entities.Curve(AcisEntity)** Abstract base class for all parametric curves. The parameterization of any *Curve* maps a 1D line (the parameter) into the spatial object-space (x, y, z). - **bounds** Tuple of (start bound, end bound) parameters as two floats which define the bounds of the parametric curve, one or both values can be **math.inf** which indicates an unbounded state of the curve in that direction. - **abstract evaluate(param: float) -\> *Vec3*** Returns the spatial location at the parametric curve for the given parameter. ### StraightCurve - **class ezdxf.acis.entities.StraightCurve(Curve)** Defines a straight line as parametric curve. - **origin** Location vector of the origin of the straight line as *Vec3*. - **direction** Direction vector the straight line as *Vec3*. Has to be an unit-vector! ### PCurve - **class ezdxf.acis.entities.PCurve(AcisEntity)** Not implemented. ### Point - **class ezdxf.acis.entities.Point(AcisEntity)** Represents a point in the 3D object-space. - **location** Cartesian coordinates as *Vec3*. ### Bounding Box The *ezdxf.bbox* module provide tools to calculate bounding boxes for many DXF entities, but not for all. The bounding box calculation is based on the *ezdxf.disassemble* module and therefore has the same limitation. **WARNING:** If accurate boundary boxes for text entities are important for you, read this first: *Text Boundary Calculation*. TL;DR: Boundary boxes for text entities are **not accurate!** Unsupported DXF entities: - • All ACIS based types like BODY, 3DSOLID or REGION - • External references (XREF) and UNDERLAY object - • RAY and XRAY, extend into infinite - • ACAD\_TABLE, no basic support - only preserved by *ezdxf* Unsupported entities are silently ignored, filtering of these DXF types is not necessary. The base type for bounding boxes is the *BoundingBox* class from the module *ezdxf.math*. The *entities* iterable as input can be the whole modelspace, an entity query or any iterable container of DXF entities. The Calculation of bounding boxes of curves is done by flattening the curve by a default flattening distance of 0.01. Set argument *flatten* to 0 to speedup the bounding box calculation by accepting less precision for curved objects by using only the control vertices. The **optional** caching object *Cache* has to be instantiated by the user, this is only useful if the same entities will be processed multiple times. Example usage with caching: ``` from ezdxf import bbox msp = doc.modelspace() cache = bbox.Cache() # get overall bounding box first_bbox = bbox.extents(msp, cache=cache) # bounding box of all LINE entities second_bbox = bbox.extend(msp.query("LINE"), cache=cache) ``` ### Functions - **ezdxf.bbox.extents(entities: Iterable\[*DXFEntity*\], \*, fast=False, cache: *Cache* \| None = None) -\> *BoundingBox*** Returns a single bounding box for all given *entities*. If argument *fast* is **True** the calculation of Bézier curves is based on their control points, this may return a slightly larger bounding box. - **ezdxf.bbox.multi\_flat(entities: Iterable\[*DXFEntity*\], \*, fast=False, cache: *Cache* \| None = None) -\> Iterable\[*BoundingBox*\]** Yields a bounding box for each of the given *entities*. If argument *fast* is **True** the calculation of Bézier curves is based on their control points, this may return a slightly larger bounding box. - **ezdxf.bbox.multi\_recursive(entities: Iterable\[*DXFEntity*\], \*, fast=False, cache: *Cache* \| None = None) -\> Iterable\[*BoundingBox*\]** Yields all bounding boxes for the given *entities* **or** all bounding boxes for their sub entities. If an entity (INSERT) has sub entities, only the bounding boxes of these sub entities will be yielded, **not** the bounding box of the entity (INSERT) itself. If argument *fast* is **True** the calculation of Bézier curves is based on their control points, this may return a slightly larger bounding box. ### Caching Strategies Because *ezdxf* is not a CAD application, *ezdxf* does not manage data structures which are optimized for a usage by a CAD kernel. This means that the content of complex entities like block references or leaders has to be created on demand by DXF primitives on the fly. These temporarily created entities are called virtual entities and have no handle and are not stored in the entity database. All this is required to calculate the bounding box of complex entities, and it is therefore a very time consuming task. By using a *Cache* object it is possible to speedup this calculations, but this is not a magically feature, it requires an understanding of what is happening under the hood to achieve any performance gains. For a single bounding box calculation, without any reuse of entities it makes no sense of using a *Cache* object, e.g. calculation of the modelspace extents: ``` from pathlib import Path import ezdxf from ezdxf import bbox CADKitSamples = Path(ezdxf.EZDXF_TEST_FILES) / 'CADKitSamples' doc = ezdxf.readfile(CADKitSamples / 'A_000217.dxf') cache = bbox.Cache() ext = bbox.extents(doc.modelspace(), cache) print(cache) ``` 1226 cached objects and not a single cache hit: ``` Cache(n=1226, hits=0, misses=3273) ``` The result for using UUIDs to cache virtual entities is not better: ``` Cache(n=2206, hits=0, misses=3273) ``` Same count of hits and misses, but now the cache also references ~1000 virtual entities, which block your memory until the cache is deleted, luckily this is a small DXF file (~838 kB). Bounding box calculations for multiple entity queries, which have overlapping entity results, using a *Cache* object may speedup the calculation: ``` doc = ezdxf.readfile(CADKitSamples / 'A_000217.dxf.dxf') msp = doc.modelspace() cache = bbox.Cache(uuid=False) ext = bbox.extents(msp, cache) print(cache) # process modelspace again ext = bbox.extents(msp, cache) print(cache) ``` Processing the same data again leads some hits: ``` 1st run: Cache(n=1226, hits=0, misses=3273) 2nd run: Cache(n=1226, hits=1224, misses=3309) ``` Using **uuid=True** leads not to more hits, but more cache entries: ``` 1st run: Cache(n=2206, hits=0, misses=3273) 2nd run: Cache(n=2206, hits=1224, misses=3309) ``` Creating stable virtual entities by disassembling the entities at first leads to more hits: ``` from ezdxf import disassemble entities = list(disassemble.recursive_decompose(msp)) cache = bbox.Cache(uuid=False) bbox.extents(entities, cache) print(cache) bbox.extents(entities, cache) print(cache) ``` First without UUID for stable virtual entities: ``` 1st run: Cache(n=1037, hits=0, misses=4074) 2nd run: Cache(n=1037, hits=1037, misses=6078) ``` Using UUID for stable virtual entities leads to more hits: ``` 1st run: Cache(n=2019, hits=0, misses=4074) 2nd run: Cache(n=2019, hits=2018, misses=4116) ``` But caching virtual entities needs also more memory. In conclusion: Using a cache is only useful, if you often process **nearly the same data**; only then can an increase in performance be expected. ### Cache Class - **class ezdxf.bbox.Cache(uuid=False)** Caching object for *ezdxf.math.BoundingBox* objects. - **Parameters** **uuid** – use UUIDs for virtual entities - **has\_data** **True** if the cache contains any bounding boxes - **hits** - **misses** - **invalidate(entities: Iterable\[*DXFEntity*\]) -\> None** Invalidate cache entries for the given DXF *entities*. If entities are changed by the user, it is possible to invalidate individual entities. Use with care - discarding the whole cache is the safer workflow. Ignores entities which are not stored in cache. ### Disassemble This module provide tools for the recursive decomposition of nested block reference structures into a flat stream of DXF entities and converting DXF entities into geometric primitives of *Path* and **MeshBuilder** objects encapsulated into intermediate *Primitive* classes. **WARNING:** Do not expect advanced vectorization capabilities: Text entities like TEXT, ATTRIB, ATTDEF and MTEXT get only a rough border box representation. The *text2path* add-on can convert text into paths. VIEWPORT, IMAGE and WIPEOUT are represented by their clipping path. Unsupported entities: all ACIS based entities, XREF, UNDERLAY, ACAD\_TABLE, RAY, XLINE. Unsupported entities will be ignored. ### Text Boundary Calculation Text boundary calculations are based on monospaced (fixed-pitch, fixed-width, non-proportional) font metrics, which do not provide a good accuracy for text height calculation and much less accuracy for text width calculation. It is possible to improve this results by using the font support from the **optional** *Matplotlib* package. Install Matplotlib from command line: ``` C:\> pip3 install matplotlib ``` The *Matplotlib* font support will improve the results for TEXT, ATTRIB and ATTDEF. The MTEXT entity has many advanced features which would require a full “Rich Text Format” rendering and that is far beyond the goals and capabilities of this library, therefore the boundary box for MTEXT will **never** be as accurate as in a dedicated CAD application. Using the *Matplotlib* font support adds **runtime overhead**, therefore it is possible to deactivate the *Matplotlib* font support by setting the global option: ``` options.use_matplotlib_font_support = False ``` ### Flatten Complex DXF Entities - **ezdxf.disassemble.recursive\_decompose(entities: Iterable\[DXFEntity\]) -\> Iterable\[DXFEntity\]** Recursive decomposition of the given DXF entity collection into a flat stream of DXF entities. All block references (INSERT) and entities which provide a **virtual\_entities()** method will be disassembled into simple DXF sub-entities, therefore the returned entity stream does not contain any INSERT entity. Point entities will **not** be disassembled into DXF sub-entities, as defined by the current point style $PDMODE. These entity types include sub-entities and will be decomposed into simple DXF entities: - • INSERT - • DIMENSION - • LEADER - • MLEADER - • MLINE Decomposition of XREF, UNDERLAY and ACAD\_TABLE entities is not supported. This function does not apply the clipping path created by the XCLIP command. The function returns all entities and ignores the clipping path polygon and no entity is clipped. ### Entity Deconstruction These functions disassemble DXF entities into simple geometric objects like meshes, paths or vertices. The *Primitive* is a simplified intermediate class to use a common interface on various DXF entities. - **ezdxf.disassemble.make\_primitive(entity: DXFEntity, max\_flattening\_distance=None) -\> *Primitive*** Factory to create path/mesh primitives. The *max\_flattening\_distance* defines the max distance between the approximation line and the original curve. Use *max\_flattening\_distance* to override the default value. Returns an **empty primitive** for unsupported entities. The *empty* state of a primitive can be checked by the property **is\_empty**. The **path** and the **mesh** attributes of an empty primitive are **None** and the **vertices()** method yields no vertices. - **ezdxf.disassemble.to\_primitives(entities: Iterable\[DXFEntity\], max\_flattening\_distance: float \| None = None) -\> Iterable\[*Primitive*\]** Yields all DXF entities as path or mesh primitives. Yields unsupported entities as empty primitives, see *make\_primitive()*. - **Parameters** - • **entities** – iterable of DXF entities - • **max\_flattening\_distance** – override the default value - **ezdxf.disassemble.to\_meshes(primitives: Iterable\[*Primitive*\]) -\> Iterable\[MeshBuilder\]** Yields all *MeshBuilder* objects from the given *primitives*. Ignores primitives without a defined mesh. - **ezdxf.disassemble.to\_paths(primitives: Iterable\[*Primitive*\]) -\> Iterable\[Path\]** Yields all *Path* objects from the given *primitives*. Ignores primitives without a defined path. - **ezdxf.disassemble.to\_vertices(primitives: Iterable\[*Primitive*\]) -\> Iterable\[*Vec3*\]** Yields all vertices from the given *primitives*. Paths will be flattened to create the associated vertices. See also *to\_control\_vertices()* to collect only the control vertices from the paths without flattening. - **ezdxf.disassemble.to\_control\_vertices(primitives: Iterable\[*Primitive*\]) -\> Iterable\[*Vec3*\]** Yields all path control vertices and all mesh vertices from the given *primitives*. Like *to\_vertices()*, but without flattening. - **class ezdxf.disassemble.Primitive** Interface class for path/mesh primitives. - **entity** Reference to the source DXF entity of this primitive. - **max\_flattening\_distance** The *max\_flattening\_distance* attribute defines the max distance in drawing units between the approximation line and the original curve. Set the value by direct attribute access. (float) default = 0.01 - **property path: Path \| None** *Path* representation or **None**, idiom to check if is a path representation (could be empty): ``` if primitive.path is not None: process(primitive.path) ``` - **property mesh: MeshBuilder \| None** **MeshBuilder** representation or **None**, idiom to check if is a mesh representation (could be empty): ``` if primitive.mesh is not None: process(primitive.mesh) ``` - **property is\_empty: bool** Returns *True* if represents an empty primitive which do not yield any vertices. - **abstract vertices() -\> Iterable\[*Vec3*\]** Yields all vertices of the path/mesh representation as *Vec3* objects. - **bbox(fast=False) -\> *BoundingBox*** Returns the *BoundingBox* of the path/mesh representation. Returns the precise bounding box for the path representation if *fast* is **False**, otherwise the bounding box for Bézier curves is based on their control points. ### EdgeMiner Added in version 1.4. ### Purpose of this Module This is a helper tool to: - • build polylines from DXF primitives like LINE, ARC, ELLIPSE, SPLINE - • build hatch boundary paths from DXF primitives - • find open chains or closed loops in an unordered heap of DXF primitives (edges) - • in general: find connections between edges ### What are Edges? An edge is a linear structure with an start- and end point and an optional length. This module is not limited to DXF primitives. Anything that can be represented by an start- and end point can be processed. This makes this module to a versatile tool with the disadvantage that intersections between edges are not known and cannot be calculated. e.g. When each arc is represented by an edge, the HATCH boundary path on the left can be found because the arcs are connected by their end points. Finding the HATCH boundary path on the right is not possible because the intersections points of the arcs (edges) are not known: \[image\] ### How to Create Edges? The process of creating edges is separated from this module and is done in the companion module *ezdxf.edgesmith*. The **edgeminer** module doesn’t really know what an edge represents or what it looks like. ### Terminology I try to use the terminology of *Graph Theory* but there are differences where I think a different term is better suited for this module like loop for cycle. - **Edge** A linear connection between two points. The shape of an edge is not known. Intersection points between edges are not known and cannot be calculated. \[image\] - **Vertex** A connection point of two or more edges. - **Degree** The degree of a vertex is the number of connected edges. \[image\] - **Leaf** A leaf is a vertex of degree 1. A leaf is a loose end of an edge, which is not connected to other edges. - **Junction** A junction is a vertex of degree greater 2. A junction has more than two adjacent edges. A junction is an ambiguity when searching for open chains or closed loops. Graph Theory: multiple adjacency - **Chain** A chain has sequential connected edges. The end point of an edge is connected to the start point of the following edge. A chain has unique edges, each edge appears only once in the chain. A chain can contain vertices of degree greater 2. A solitary edge is also a chain. Graph Theory: Trail - no edge is repeated, vertex is repeated \[image\] - **Simple Chain (special to this module)** A simple chain contains only vertices of degree 2, except the start- and end vertex. The start- and end vertices are leafs (degree of 1) or junctions (degree greater 2). The following image shows 3 simple chains: \[1-2-3\], \[4-5-6\] and \[7-8-9\]. Simple chains are easy to detect and can be replaced by a single edge and reduces so the search space. \[image\] - **Open Chain** An open chain is a chain which starts and ends with a leaf. A solitary edge is also an open chain. Graph Theory: Path - no edge is repeated, no vertex is repeated, endings not connected - **Loop** A loop is a simple chain with connected start- and end vertices. A loop has two or more edges. A loop contains only vertices of degree 2. Graph Theory: Cycle - no edge is repeated, no vertex is repeated, endings connected; a loop in Graph Theory is something different! - **Network** A network has two or more edges that are directly and indirectly connected. The edges in a network have no order. A network can contain vertices of degree greater 2 (junctions). A solitary edge is not a network. A chain with two or more edges is a network. Graph Theory: multigraph; a network in Graph Theory is something different! - **Gap Tolerance** Maximum vertex distance to consider two edges as connected - **Forward Connection** An edge is forward connected when the end point of the edge is connected to the start point of the following edge. **SEE ALSO:** - • *Tutorial for Finding Chains and Loops* - • *ezdxf.edgesmith* module **IMPORTANT:** This is the reference documentation and not a tutorial how to use this module. ### High Level Functions - **ezdxf.edgeminer.find\_sequential\_chain(edges: Sequence\[*Edge*\], \*, gap\_tol=GAP\_TOL) -\> Sequence\[*Edge*\]** Returns a simple chain beginning at the first edge. The search stops at the first edge without a forward connection from the previous edge. Edges will be reversed if required to create connection. - **Parameters** - • **edges** – edges to be examined - • **gap\_tol** – maximum vertex distance to consider two edges as connected - **Raises** **TypeError** – invalid data in sequence *edges* - **ezdxf.edgeminer.find\_all\_sequential\_chains(edges: Sequence\[*Edge*\], \*, gap\_tol=GAP\_TOL) -\> Iterator\[Sequence\[*Edge*\]\]** Yields all simple chains from sequence *edges*. The search progresses strictly in order of the input sequence. The search starts a new chain at every edge without a forward connection from the previous edge. Edges will be reversed if required to create connection. Each chain has one or more edges. - **Parameters** - • **edges** – sequence of edges - • **gap\_tol** – maximum vertex distance to consider two edges as connected - **Raises** **TypeError** – invalid data in sequence *edges* - **ezdxf.edgeminer.find\_simple\_chain(deposit: *Deposit*, start: *Edge*) -\> Sequence\[*Edge*\]** Returns a simple chain containing *start* edge. A simple chain start and ends at a leaf or a junction. All connected edges have vertices of degree 2, except the first and last vertex. The first and the last vertex have a degree of 1 (leaf) or greater 2 (junction). - **ezdxf.edgeminer.find\_all\_simple\_chains(deposit: *Deposit*) -\> Sequence\[Sequence\[*Edge*\]\]** Returns all simple chains from *deposit*. Each chains starts and ends at a leaf (degree of 1) or a junction (degree greater 2). All vertices between the start- and end vertex have a degree of 2. The result doesn’t include reversed solutions. - **ezdxf.edgeminer.find\_all\_open\_chains(deposit: *Deposit*, timeout: float = TIMEOUT) -\> Sequence\[Sequence\[*Edge*\]\]** Returns all open chains from *deposit*. Returns only simple chains ending on both sides with a leaf. A leaf is a vertex of degree 1 without further connections. All vertices have a degree of 2 except for the leafs at the start and end. The result does not include reversed solutions or closed loops. **NOTE:** This is a recursive backtracking algorithm with time complexity of O(n!). - **Parameters** - • **deposit** (*Deposit*) – edge deposit - • **timeout** (*float*) – timeout in seconds - **Raises** *TimeoutError* – search process has timed out - **ezdxf.edgeminer.find\_loop(deposit: *Deposit*, \*, timeout: float = TIMEOUT) -\> Sequence\[*Edge*\]** Returns the first closed loop in *deposit*. Returns only simple loops, where all vertices have a degree of 2 (only two adjacent edges). **NOTE:** This is a recursive backtracking algorithm with time complexity of O(n!). - **Parameters** - • **deposit** (*Deposit*) – edge deposit - • **timeout** (*float*) – timeout in seconds - **Raises** *TimeoutError* – search process has timed out - **ezdxf.edgeminer.find\_loop\_by\_edge(deposit: *Deposit*, start: *Edge*, clockwise=True) -\> Sequence\[*Edge*\]** Returns the first loop found including the given *start* edge. Returns an empty sequence if no loop was found. - **Parameters** - • **deposit** (*Deposit*) – edge deposit - • **start** (*Edge*) – starting edge of the search - • **clockwise** (*bool*) – search orientation, counter-clockwise when **False** - **ezdxf.edgeminer.find\_all\_loops(deposit: *Deposit*, \*, timeout: float = TIMEOUT) -\> Sequence\[Sequence\[*Edge*\]\]** Returns all closed loops from *deposit*. Returns only simple loops, where all vertices have a degree of 2 (only two adjacent edges). The result does not include reversed solutions. **NOTE:** This is a recursive backtracking algorithm with time complexity of O(n!). - **Parameters** - • **deposit** (*Deposit*) – edge deposit - • **timeout** (*float*) – timeout in seconds - **Raises** *TimeoutError* – search process has timed out ### Low Level Functions - **ezdxf.edgeminer.filter\_coincident\_edges(deposit: *Deposit*, eq\_fn: Callable\[\[*Edge*, *Edge*\], bool\] = line\_checker()) -\> Sequence\[*Edge*\]** Returns all edges from deposit that are not coincident to any other edge in the deposit. Coincident edges are detected by the given *eq\_fn* function. - **ezdxf.edgeminer.flatten(edges: *Edge* \| Iterable\[*Edge*\]) -\> Iterator\[*Edge*\]** Yields all edges from any nested structure of edges as a flat stream of edges. - **ezdxf.edgeminer.is\_chain(edges: Sequence\[*Edge*\], \*, gap\_tol=GAP\_TOL) -\> bool** Returns **True** if all edges in the sequence have a forward connection. - **Parameters** - • **edges** – sequence of edges - • **gap\_tol** – maximum vertex distance to consider two edges as connected - **ezdxf.edgeminer.is\_forward\_connected(a: *Edge*, b: *Edge*, \*, gap\_tol=GAP\_TOL) -\> bool** Returns **True** if the edges have a forward connection. Forward connection: distance from **a.end** to **b.start** \<= gap\_tol - **Parameters** - • **a** – first edge - • **b** – second edge - • **gap\_tol** – maximum vertex distance to consider two edges as connected - **ezdxf.edgeminer.is\_loop(edges: Sequence\[*Edge*\], \*, gap\_tol=GAP\_TOL) -\> bool** Return **True** if the sequence of edges is a closed loop. - **Parameters** - • **edges** – sequence of edges - • **gap\_tol** – maximum vertex distance to consider two edges as connected - **ezdxf.edgeminer.is\_wrapped\_chain(edge: *Edge*) -\> bool** Returns **True** if *edge* is a wrapper for linked edges. - **ezdxf.edgeminer.isclose(a: *Vec3*, b: *Vec3*, \*, gap\_tol=GAP\_TOL) -\> bool** This function should be used to test whether two vertices are close to each other to get consistent results. - **ezdxf.edgeminer.length(edges: Sequence\[*Edge*\]) -\> float** Returns the length of a sequence of edges. - **ezdxf.edgeminer.longest\_chain(chains: Iterable\[Sequence\[*Edge*\]\]) -\> Sequence\[*Edge*\]** Returns the longest chain of connected edges. **NOTE:** This function does not verify if the input sequences are connected edges! - **ezdxf.edgeminer.make\_edge(start: *UVec*, end: *UVec*, length: float = -1.0, \*, payload: Any = None) -\> *Edge*** Creates a new *Edge* with a unique id. - **Parameters** - • **start** – start point - • **end** – end point - • **length** – default is the distance between start and end - • **payload** – arbitrary data attached to the edge - **ezdxf.edgeminer.reverse\_chain(chain: Sequence\[*Edge*\]) -\> list\[*Edge*\]** Returns the reversed chain. The sequence order of the edges will be reversed as well as the start- and end points of the edges. - **ezdxf.edgeminer.shortest\_chain(chains: Iterable\[Sequence\[*Edge*\]\]) -\> Sequence\[*Edge*\]** Returns the shortest chain of connected edges. **NOTE:** This function does not verify if the input sequences are connected edges! - **ezdxf.edgeminer.subtract\_edges(base: Iterable\[*Edge*\], edges: Iterable\[*Edge*\]) -\> list\[*Edge*\]** Returns all edges from the iterable *base* that do not exist in the iterable *edges* e.g. remove solutions from the search space. - **ezdxf.edgeminer.unwrap\_simple\_chain(edge: *Edge*) -\> Sequence\[*Edge*\]** Unwraps a simple chain which is wrapped into a single edge. - **ezdxf.edgeminer.wrap\_simple\_chain(chain: Sequence\[*Edge*\], \*, gap\_tol=GAP\_TOL) -\> *Edge*** Wraps a sequence of linked edges (simple chain) into a single edge. Two or more linked edges required. Closed loops cannot be wrapped into a single edge. - **Raises** **ValueError** – less than two edges; not a chain; chain is a closed loop ### Classes - **class ezdxf.edgeminer.Edge(id: int, start: *Vec3*, end: *Vec3*, is\_reverse: bool = False, length: float = 1.0, payload: Any = None)** Represents an immutable edge. An edge can represent any linear curve (line, elliptical arc, spline, …), but it does not know this shape; only the start and end vertices are stored, not the shape itself. Therefore, the length of the edge must be specified if the length calculation for a sequence of edges should be possible. Intersection points between edges are not known and cannot be calculated. **IMPORTANT:** Use only the *make\_edge()* function to create new edges to get unique ids! - **id** unique id - **Type** int - **start** start vertex - **Type** *Vec3* - **end** end vertex - **Type** *Vec3* - **is\_reverse** flag to indicate that the edge is reversed compared to its initial state - **Type** bool - **length** length of the edge, default is 1.0 - **Type** float - **payload** arbitrary data attached to the edge, default is **None** - **Type** Any - **\_\_eq\_\_(other) -\> bool** Return **True** if the ids of the edges are equal. **IMPORTANT:** An edge is equal to its reversed copy! - **\_\_hash\_\_() -\> int** The edge *id* is used as hash value. An Edge and its reversed edge have the same hash value and cannot both exist in the same **set**. - **reversed() -\> Self** Returns a reversed copy. The reversed edge has the same *id* as the source edge, because they represent the same edge. - **class ezdxf.edgeminer.Deposit(edges: Sequence\[*Edge*\], \*, gap\_tol=GAP\_TOL)** The edge deposit stores all available edges for further searches. The edges and the search index are immutable after instantiation. The *gap\_tol* attribute is mutable. - **Parameters** - • **edges** – sequence of *Edge* - • **gap\_tol** – maximum vertex distance to consider two edges as connected - **gap\_tol** maximum vertex distance to consider two edges as connected (mutable) - **property edges: Sequence\[*Edge*\]** Sequence of edges stored in this deposit. - **property max\_degree: int** Returns the maximum degree of all vertices in this deposit. - **degree\_counter() -\> Counter\[int\]** Returns a **Counter** for the degree of all vertices. - • **Counter\[degree\]** returns the count of vertices of this degree. - • **Counter.keys()** returns all existing degrees in this deposit A new counter will be created for every method call! The *gap\_tol* attribute is mutable and different gap tolerances may yield different results. - **degree(vertex: *UVec*) -\> int** Returns the degree of the given vertex. - • degree of 0: not in this deposit - • degree of 1: one edge is connected to this vertex - • degree of 2: two edges are connected to this vertex - • degree of 3: three edges … and so on Check if a vertex exist in a deposit: ``` if deposit.degree(vertex): ... ``` - **degrees(vertices: Iterable\[*UVec*\]) -\> Sequence\[int\]** Returns the degree of the given vertices. - **edges\_linked\_to(vertex: *UVec*, radius: float = -1) -\> Sequence\[*Edge*\]** Returns all edges linked to *vertex* in range of *radius*. - **Parameters** - • **vertex** – 3D search location - • **radius** – search range, default radius is *Deposit.gap\_tol* - **find\_all\_networks() -\> Sequence\[set\[*Edge*\]\]** Returns all separated networks in this deposit in ascending order of edge count. - **find\_leafs() -\> Iterator\[*Edge*\]** Yields all edges that have at least one end point without connection to other edges. - **find\_nearest\_edge(vertex: *UVec*) -\> *Edge* \| None** Return the nearest edge to the given vertex. The distance is measured to the connection line from start to end of the edge. This is not correct for edges that represent arcs or splines. - **find\_network(edge: *Edge*) -\> set\[*Edge*\]** Returns the network of all edges that are directly and indirectly linked to *edge*. A network has two or more edges, a solitary edge is not a network. - **unique\_vertices() -\> set\[*Vec3*\]** Returns all unique vertices from this deposit. Ignores vertices that are close to another vertex (within the range of gap\_tol). It is not determined which of the close vertices is returned. e.g. if the vertices a, b are close together, you don’t know if you get a or b, but it’s guaranteed that you only get one of them - **class ezdxf.edgeminer.TimeoutError(msg: str, solutions: Sequence\[Sequence\[*Edge*\]\] = tuple())** - **solutions** solutions found until time out occur ### Global Constants ``` GAP_TOL = 1e-9 ABS_TOL = 1e-9 TIMEOUT = 60.0 # in seconds ``` ### EdgeSmith Added in version 1.4. ### Purpose of this Module This is a companion module to the *ezdxf.edgeminer* module: - • create *Edge* instances from DXF primitives for processing by the *edgeminer* module: - • *Line* - • *Arc* - • *Ellipse* - • *Spline* - • *LWPolyline* - • *Polyline* - • create *LWPolyline* and *Polyline* entities from a sequence of *Edge* objects. - • create *Hatch* boundary paths from a sequence of *Edge* objects. - • create *ezdxf.path.Path* objects from a sequence of *Edge* objects. **SEE ALSO:** - • *Tutorial for Finding Chains and Loops* - • *ezdxf.edgeminer* module **IMPORTANT:** This is the reference documentation and not a tutorial how to use this module. ### Make Edges This functions convert open shapes into 2D edges, closed shapes as circles, closed arcs, closed ellipses, closed splines and closed polylines are ignored or return **None**. - **ezdxf.edgesmith.make\_edge\_2d(entity: *DXFEntity*, \*, gap\_tol=GAP\_TOL) -\> *ezdxf.edgeminer.Edge* \| None** Makes an *Edge* instance from the following DXF entity types: - • *Line* (length accurate) - • *Arc* (length accurate) - • *Ellipse* (length approximated) - • *Spline* (length approximated as straight lines between control points) - • *LWPolyline* (length of bulges as straight line from start- to end point) - • *Polyline* (length of bulges as straight line from start- to end point) The start- and end points of the edge is projected onto the xy-plane. Returns **None** if the entity has a closed shape or cannot be represented as an edge. - **ezdxf.edgesmith.edges\_from\_entities\_2d(entities: Iterable\[DXFEntity\], \*, gap\_tol=GAP\_TOL) -\> Iterator\[*Edge*\]** Yields all DXF entities as 2D edges in the xy-plane of the *WCS*. Skips all entities that have a closed shape or can not be represented as edge. ### Build From Edges ARC, LWPOLYLINE, POLYLINE and ELLIPSE entities must have an extrusion vector of (0, 0, 1) (WCS Z-Axis). Entities with an inverted extrusion vector (0, 0, -1) will be treated as a 3D curve and approximated by a polyline projected onto the xy-plane. The *ezdxf.upright* module can convert such inverted extrusion vectors to (0, 0, 1). ### Curve Approximation For some target entities curves have to be approximated by polylines. This process is also called flattening and is controlled by the parameter **max\_sagitta**. (*Wikipedia*) The **max\_sagitta** argument defines the maximum distance from the center of the curve segment to the center of the line segment between two approximation points to determine if a segment should be subdivided. The default value is -1 and uses a 1/100 of the approximated length of the curve as **max\_sagitta**. \[image\] The good choice for a **max\_sagitta** depends on the output resolution and is maybe not known at the time of processing the data. E.g. for a printer/plotter a **max\_sagitta** of around 1/300 inch (300 dpi) is maybe a good choice. The convertion from output units to drawing units depends on the scale and is the task of the package user. All flattened curves will be projected onto the xy-plane of the *WCS*. - **ezdxf.edgesmith.lwpolyline\_from\_chain(edges: Sequence\[*Edge*\], \*, dxfattribs: Any = None, max\_sagitta: float = -1) -\> LWPolyline** Returns a new virtual *LWPolyline* entity. This function assumes the building blocks as simple DXF entities attached as payload to the edges. The edges are processed in order of the input sequence and the start- and end points of the edges should be connected. The output polyline is projected onto the xy-plane of the *WCS*. - • *Line* as line segment - • *Arc* as bulge - • *Ellipse* as bulge or as flattened line segments - • *Spline* as flattened line segments - • *LWPolyline* and *Polyline* will be merged - • Everything else will be added as line segment from **Edge.start** to **Edge.end** - • Gaps between edges are connected by line segments. - **ezdxf.edgesmith.polyline2d\_from\_chain(edges: Sequence\[*Edge*\], \*, dxfattribs: Any = None, max\_sagitta: float = -1) -\> Polyline** Returns a new virtual **Polyline** entity. This function assumes the building blocks as simple DXF entities attached as payload to the edges. The edges are processed in order of the input sequence and the start- and end points of the edges should be connected. The output polyline is projected onto the xy-plane of the *WCS*. - • *Line* as line segment - • *Arc* as bulge - • *Ellipse* as bulge or as flattened line segments - • *Spline* as flattened line segments - • *LWPolyline* and *Polyline* will be merged - • Everything else will be added as line segment from **Edge.start** to **Edge.end** - • Gaps between edges are connected by line segments. - **ezdxf.edgesmith.edge\_path\_from\_chain(edges: Sequence\[*Edge*\], \*, max\_sagitta: float = -1, flags: int = 1) -\> EdgePath** Returns a new *EdgePath* for *Hatch* entities. This function assumes the building blocks as simple DXF entities attached as payload to the edges. The edges are processed in order of the input sequence and the start- and end points of the edges should be connected. The output path is projected onto the xy-plane of the *WCS*. - • *Line* as *LineEdge* - • *Arc* as *ArcEdge* - • *Ellipse* as *EllipseEdge* - • *Spline* as *SplineEdge* - • *LWPolyline* and *Polyline* will be exploded and added as *LineEdge* and *ArcEdge* - • Everything else will be added as line segment from **Edge.start** to **Edge.end** - • Gaps between edges are connected by line segments. - **Parameters** - • **edges** – Sequence of *Edge* instances with DXF primitives attached as payload - • **max\_sagitta** (*float*) – curve flattening parameter - • **flags** (*int*) – default(0), external(1), derived(4), textbox(8) or outermost(16) - **ezdxf.edgesmith.polyline\_path\_from\_chain(edges: Sequence\[*Edge*\], \*, max\_sagitta: float = -1, is\_closed=True, flags: int = 1) -\> PolylinePath** Returns a new *PolylinePath* for *Hatch* entities. This function assumes the building blocks as simple DXF entities attached as payload to the edges. The edges are processed in order of the input sequence and the start- and end points of the edges should be connected. The output path is projected onto the xy-plane of the *WCS*. - • *Line* as line segment - • *Arc* as bulge - • *Ellipse* as bulge or flattened line segments - • *Spline* as flattened line segments - • *LWPolyline* and *Polyline* are merged - • Everything else will be added as line segment from **Edge.start** to **Edge.end** - • Gaps between edges are connected by line segments. - **Parameters** - • **edges** – Sequence of *Edge* instances with DXF primitives attached as payload - • **max\_sagitta** (*float*) – curve flattening parameter - • **is\_closed** (*bool*) – **True** if path is implicit closed - • **flags** (*int*) – default(0), external(1), derived(4), textbox(8) or outermost(16) - **ezdxf.edgesmith.path2d\_from\_chain(edges: Sequence\[*Edge*\]) -\> Path** Returns a new *ezdxf.path.Path* entity. This function assumes the building blocks as simple DXF entities attached as payload to the edges. The edges are processed in order of the input sequence and the start- and end points of the edges should be connected. The output is a 2D path projected onto the xy-plane of the *WCS*. - • *Line* as line segment - • *Arc* as cubic Bézier curves - • *Ellipse* as cubic Bézier curves - • **Spine** cubic Bézier curves - • *LWPolyline* and *Polyline* as line segments and cubic Bézier curves - • Everything else will be added as line segment from **Edge.start** to **Edge.end** - • Gaps between edges are connected by line segments. ### Helper Functions - **ezdxf.edgesmith.is\_closed\_entity(entity: *DXFEntity*) -\> bool** Returns **True** if the given entity represents a closed loop. Tests the following DXF entities: - • CIRCLE - • ARC - • ELLIPSE - • SPLINE - • LWPOLYLINE - • POLYLINE - • HATCH - • SOLID - • TRACE Returns **False** for all other DXF entities. - **ezdxf.edgesmith.is\_pure\_2d\_entity(entity: *DXFEntity*) -\> bool** Returns **True** if the given entity represents a pure 2D entity in the xy-plane of the *WCS*. - • All vertices must be in the xy-plane of the *WCS*. - • Thickness must be 0. - • The extrusion vector must be (0, 0, 1). - • Entities with inverted extrusions vectors (0, 0, -1) are **not** pure 2D entities. The *ezdxf.upright* module can be used to revert inverted extrusion vectors back to (0, 0, 1). Tests the following DXF entities: - • LINE - • CIRCLE - • ARC - • ELLIPSE - • SPLINE - • LWPOLYLINE - • POLYLINE - • HATCH - • SOLID - • TRACE Returns **False** for all other DXF entities. - **ezdxf.edgesmith.filter\_edge\_entities(entities: Iterable\[DXFEntity\]) -\> Iterator\[DXFEntity\]** Returns all entities that can be used to build edges in the context of *ezdxf.edgeminer*. Returns the following DXF entities: - • LINE - • ARC - • ELLIPSE - • SPLINE - • LWPOLYLINE - • POLYLINE **NOTE:** - • CIRCLE, TRACE and SOLID are closed shapes by definition and cannot be used as edge in the context of *ezdxf.edgeminer* or *ezdxf.edgesmith*. - • This filter is not limited to pure 2D entities! - • Does not test if the entity is a closed loop! - **ezdxf.edgesmith.filter\_2d\_entities(entities: Iterable\[DXFEntity\]) -\> Iterator\[DXFEntity\]** Returns all pure 2D entities, ignores all entities placed outside or extending beyond the xy-plane of the *WCS*. See *is\_pure\_2d\_entity()* for more information. - **ezdxf.edgesmith.filter\_open\_edges(entities: Iterable\[DXFEntity\]) -\> Iterator\[DXFEntity\]** Returns all open linear entities usable as edges in the context of *ezdxf.edgeminer* or *ezdxf.edgesmith*. Ignores all entities that represent closed loops like circles, closed arcs, closed ellipses, closed splines and closed polylines. **NOTE:** This filter is not limited to pure 2D entities! - **ezdxf.edgesmith.bounding\_box\_2d(edges: Sequence\[*Edge*\]) -\> *BoundingBox2d*** Returns the *BoundingBox2d* of all start- and end vertices. - **ezdxf.edgesmith.loop\_area(edges: Sequence\[*Edge*\], \*, gap\_tol=GAP\_TOL) -\> float** Returns the area of a closed loop. - **Raises** **ValueError** – edges are not a closed loop - **ezdxf.edgesmith.is\_inside\_polygon\_2d(edges: Sequence\[*Edge*\], point: *UVec*, \*, gap\_tol=GAP\_TOL) -\> bool** Returns **True** when *point* is inside the polygon. The edges must be a closed loop. The polygon is build from edges as straight lines from start- to end vertex, independently whatever the edges really represent. A point at a boundary line is inside the polygon. - **Parameters** - • **edges** – sequence of *Edge* representing a closed loop - • **point** – point to test - • **gap\_tol** – maximum vertex distance to consider two edges as connected - **Raises** **ValueError** – edges are not a closed loop - **ezdxf.edgesmith.intersecting\_edges\_2d(edges: Sequence\[em.Edge\], p1: *UVec*, p2: *UVec* \| None = None) -\> list\[*IntersectingEdge*\]** Returns all edges that intersect a line from point *p1* to point *p2*. If *p2* is **None** an arbitrary point outside the bounding box of all start- and end vertices beyond extmax.x will be chosen. The edges are handled as straight lines from start- to end vertex, projected onto the xy-plane of the *WCS*. The result is sorted by the distance from intersection point to point *p1*. - **class ezdxf.edgesmith.IntersectingEdge** NamedTuple as return type of *intersecting\_edges\_2d()*. - **edge** Intersecting edge as *Edge*; alias for field 0. - **distance** Distance from intersection point to point *p1* as float; alias for field 1. ### Global Constants ``` GAP_TOL = 1e-9 LEN_TOL = 1e-9 # length and distance DEG_TOL = 1e-9 # angles in degree RAD_TOL = 1e-7 # angles in radians ``` ### Math Construction Tools These are links to tools in the *ezdxf.math* core module: | | | | --- | --- | | *ezdxf.math.ConstructionRay* | Construction tool for infinite 2D rays. | | *ezdxf.math.ConstructionLine* | Construction tool for 2D lines. | | *ezdxf.math.ConstructionCircle* | Construction tool for 2D circles. | | *ezdxf.math.ConstructionArc* | Construction tool for 2D arcs. | | *ezdxf.math.ConstructionEllipse* | Construction tool for 3D ellipsis. | | *ezdxf.math.ConstructionBox* | Construction tool for 2D rectangles. | | *ezdxf.math.ConstructionPolyline* | Construction tool for 3D polylines. | | *ezdxf.math.Shape2d* | Construction tools for 2D shapes. | | *ezdxf.math.BSpline* | B-spline construction tool. | | *ezdxf.math.Bezier4P* | Implements an optimized cubic *Bézier curve* for exact 4 control points. | | *ezdxf.math.Bezier3P* | Implements an optimized quadratic *Bézier curve* for exact 3 control points. | | *ezdxf.math.Bezier* | Generic *Bézier curve* of any degree. | | *ezdxf.math.EulerSpiral* | This class represents an euler spiral (clothoid) for *curvature* (Radius of curvature). | ### Path This module implements a geometric *Path*, supported by several render backends, with the goal to create such paths from DXF entities like LWPOLYLINE, POLYLINE or HATCH and send them to the render backend, see *ezdxf.addons.drawing*. Minimum common interface: - • - **matplotlib: *PathPatch*** - • matplotlib.path.Path() codes: - • MOVETO - • LINETO - • CURVE3 - quadratic Bèzier-curve - • CURVE4 - cubic Bèzier-curve - • - **PyQt: *QPainterPath*** - • moveTo() - • lineTo() - • quadTo() - quadratic Bèzier-curve (converted to a cubic Bèzier-curve) - • cubicTo() - cubic Bèzier-curve - • - **PyCairo: *Context*** - • move\_to() - • line\_to() - • no support for quadratic Bèzier-curve - • curve\_to() - cubic Bèzier-curve - • - **SVG: *SVG-Path*** - • “M” - absolute move to - • “L” - absolute line to - • “Q” - absolute quadratic Bèzier-curve - • “C” - absolute cubic Bèzier-curve ARC and ELLIPSE entities are approximated by multiple cubic Bézier-curves, which are close enough for display rendering. Non-rational SPLINES of 3rd degree can be represented exact as multiple cubic Bézier-curves, other B-splines will be approximated. The XLINE and the RAY entities are not supported, because of their infinite nature. This *Path* class is a full featured 3D object, although the backends only support 2D paths. **HINT:** A *Path* can not represent a point. A *Path* with only a start point yields no vertices! The usability of the *Path* class expanded by the introduction of the reverse conversion from *Path* to DXF entities (LWPOLYLINE, POLYLINE, LINE), and many other tools in *ezdxf* v0.16. To emphasize this new usability, the *Path* class has got its own subpackage *ezdxf.path*. - **Empty-Path** Contains only a start point, the length of the path is 0 and the methods *Path.approximate()*, *Path.flattening()* and *Path.control\_vertices()* do not yield any vertices. - **Single-Path** The *Path* object contains only one path without gaps, the property *Path.has\_sub\_paths* is **False** and the method *Path.sub\_paths()* yields only this one path. - **Multi-Path** The *Path* object contains more than one path, the property *Path.has\_sub\_paths* is **True** and the method *Path.sub\_paths()* yields all paths within this object as single-path objects. It is not possible to detect the orientation of a multi-path object, therefore the methods *Path.has\_clockwise\_orientation()*, *Path.clockwise()* and *Path.counter\_clockwise()* raise a **TypeError** exception. **WARNING:** Always import from the top level *ezdxf.path*, never from the sub-modules ### Factory Functions Functions to create *Path* objects from other objects. - **ezdxf.path.make\_path(entity: *DXFEntity*) -\> *Path*** Factory function to create a single *Path* object from a DXF entity. Supported DXF types: - • LINE - • CIRCLE - • ARC - • ELLIPSE - • SPLINE and HELIX - • LWPOLYLINE - • 2D and 3D POLYLINE - • SOLID, TRACE, 3DFACE - • IMAGE, WIPEOUT clipping path - • VIEWPORT clipping path - • HATCH as *Multi-Path* object - **Parameters** - • **entity** – DXF entity - • **segments** – minimal count of cubic Bézier-curves for elliptical arcs like CIRCLE, ARC, ELLIPSE, BULGE see **Path.add\_ellipse()** - • **level** – subdivide level for SPLINE approximation, see **Path.add\_spline()** - **Raises** **TypeError** – for unsupported DXF types - **ezdxf.path.from\_hatch(hatch: DXFPolygon, offset: *Vec3* = NULLVEC) -\> Iterator\[Path\]** Yield all HATCH/MPOLYGON boundary paths as separated *Path* objects in WCS coordinates. - **ezdxf.path.from\_vertices(vertices: Iterable\[*UVec*\], close=False) -\> Path** Returns a *Path* object from the given *vertices*. ### Render Functions Functions to create DXF entities from paths and add them to the modelspace, a paperspace layout or a block definition. - **ezdxf.path.render\_hatches(layout: GenericLayoutType, paths: Iterable\[*Path*\], \*, edge\_path: bool = True, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, g1\_tol: float = G1\_TOL, extrusion: *UVec* = Z\_AXIS, dxfattribs=None) -\> *EntityQuery*** Render the given *paths* into *layout* as *Hatch* entities. The *extrusion* vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path. - **Parameters** - • **layout** – the modelspace, a paperspace layout or a block definition - • **paths** – iterable of *Path* or **Path2d** objects - • **edge\_path** – **True** for edge paths build of LINE and SPLINE edges, **False** for only LWPOLYLINE paths as boundary paths - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve to flatten polyline paths - • **g1\_tol** – tolerance for G1 continuity check to separate SPLINE edges - • **extrusion** – extrusion vector for all paths - • **dxfattribs** – additional DXF attribs - **Returns** created entities in an *EntityQuery* object - **ezdxf.path.render\_lines(layout: GenericLayoutType, paths: Iterable\[*Path*\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, dxfattribs=None) -\> *EntityQuery*** Render the given *paths* into *layout* as *Line* entities. - **Parameters** - • **layout** – the modelspace, a paperspace layout or a block definition - • **paths** – iterable of **Path\`or :class:\`Path2d** objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve - • **dxfattribs** – additional DXF attribs - **Returns** created entities in an *EntityQuery* object - **ezdxf.path.render\_lwpolylines(layout: GenericLayoutType, paths: Iterable\[*Path*\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, extrusion: *UVec* = Z\_AXIS, dxfattribs=None) -\> *EntityQuery*** Render the given *paths* into *layout* as *LWPolyline* entities. The *extrusion* vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path. - **Parameters** - • **layout** – the modelspace, a paperspace layout or a block definition - • **paths** – iterable of *Path* or **Path2d** objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve - • **extrusion** – extrusion vector for all paths - • **dxfattribs** – additional DXF attribs - **Returns** created entities in an *EntityQuery* object - **ezdxf.path.render\_mpolygons(layout: GenericLayoutType, paths: Iterable\[*Path*\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, extrusion: *UVec* = Z\_AXIS, dxfattribs=None) -\> *EntityQuery*** Render the given *paths* into *layout* as *MPolygon* entities. The MPOLYGON entity supports only polyline boundary paths. All curves will be approximated. The *extrusion* vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path. - **Parameters** - • **layout** – the modelspace, a paperspace layout or a block definition - • **paths** – iterable of *Path* or **Path2d** objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve to flatten polyline paths - • **extrusion** – extrusion vector for all paths - • **dxfattribs** – additional DXF attribs - **Returns** created entities in an *EntityQuery* object - **ezdxf.path.render\_polylines2d(layout: GenericLayoutType, paths: Iterable\[*Path*\], \*, distance: float = 0.01, segments: int = 4, extrusion: *UVec* = Z\_AXIS, dxfattribs=None) -\> *EntityQuery*** Render the given *paths* into *layout* as 2D *Polyline* entities. The *extrusion* vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector.The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path. - **Parameters** - • **layout** – the modelspace, a paperspace layout or a block definition - • **paths** – iterable of *Path* or **Path2d** objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve - • **extrusion** – extrusion vector for all paths - • **dxfattribs** – additional DXF attribs - **Returns** created entities in an *EntityQuery* object - **ezdxf.path.render\_polylines3d(layout: GenericLayoutType, paths: Iterable\[*Path*\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, dxfattribs=None) -\> *EntityQuery*** Render the given *paths* into *layout* as 3D *Polyline* entities. - **Parameters** - • **layout** – the modelspace, a paperspace layout or a block definition - • **paths** – iterable of **Path\`or :class:\`Path2d** objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve - • **dxfattribs** – additional DXF attribs - **Returns** created entities in an *EntityQuery* object - **ezdxf.path.render\_splines\_and\_polylines(layout: GenericLayoutType, paths: Iterable\[*Path*\], \*, g1\_tol: float = G1\_TOL, dxfattribs=None) -\> *EntityQuery*** Render the given *paths* into *layout* as *Spline* and 3D *Polyline* entities. - **Parameters** - • **layout** – the modelspace, a paperspace layout or a block definition - • **paths** – iterable of **Path\`or :class:\`Path2d** objects - • **g1\_tol** – tolerance for G1 continuity check - • **dxfattribs** – additional DXF attribs - **Returns** created entities in an *EntityQuery* object ### Entity Maker Functions to create DXF entities from paths. - **ezdxf.path.to\_hatches(paths: Iterable\[Path\], \*, edge\_path: bool = True, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, g1\_tol: float = G1\_TOL, extrusion: *UVec* = Z\_AXIS, dxfattribs=None) -\> Iterator\[Hatch\]** Convert the given *paths* into *Hatch* entities. Uses LWPOLYLINE paths for boundaries without curves and edge paths, build of LINE and SPLINE edges, as boundary paths for boundaries including curves. The *extrusion* vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path. - **Parameters** - • **paths** – iterable of *Path* objects - • **edge\_path** – **True** for edge paths build of LINE and SPLINE edges, **False** for only LWPOLYLINE paths as boundary paths - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve to flatten LWPOLYLINE paths - • **g1\_tol** – tolerance for G1 continuity check to separate SPLINE edges - • **extrusion** – extrusion vector to all paths - • **dxfattribs** – additional DXF attribs - **Returns** iterable of *Hatch* objects - **ezdxf.path.to\_lines(paths: Iterable\[Path\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, dxfattribs=None) -\> Iterator\[Line\]** Convert the given *paths* into *Line* entities. - **Parameters** - • **paths** – iterable of *Path* objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve - • **dxfattribs** – additional DXF attribs - **Returns** iterable of *Line* objects - **ezdxf.path.to\_lwpolylines(paths: Iterable\[Path\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, extrusion: *UVec* = Z\_AXIS, dxfattribs=None) -\> Iterator\[LWPolyline\]** Convert the given *paths* into *LWPolyline* entities. The *extrusion* vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path. - **Parameters** - • **paths** – iterable of *Path* objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve - • **extrusion** – extrusion vector for all paths - • **dxfattribs** – additional DXF attribs - **Returns** iterable of *LWPolyline* objects - **ezdxf.path.to\_mpolygons(paths: Iterable\[Path\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, extrusion: *UVec* = Z\_AXIS, dxfattribs=None) -\> Iterator\[MPolygon\]** Convert the given *paths* into *MPolygon* entities. In contrast to HATCH, MPOLYGON supports only polyline boundary paths. All curves will be approximated. The *extrusion* vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path. - **Parameters** - • **paths** – iterable of *Path* objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve to flatten LWPOLYLINE paths - • **extrusion** – extrusion vector to all paths - • **dxfattribs** – additional DXF attribs - **Returns** iterable of *MPolygon* objects - **ezdxf.path.to\_polylines2d(paths: Iterable\[Path\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, extrusion: *UVec* = Z\_AXIS, dxfattribs=None) -\> Iterator\[Polyline\]** Convert the given *paths* into 2D *Polyline* entities. The *extrusion* vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path. - **Parameters** - • **paths** – iterable of *Path* objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve - • **extrusion** – extrusion vector for all paths - • **dxfattribs** – additional DXF attribs - **Returns** iterable of 2D *Polyline* objects - **ezdxf.path.to\_polylines3d(paths: Iterable\[Path\], \*, distance: float = MAX\_DISTANCE, segments: int = MIN\_SEGMENTS, dxfattribs=None) -\> Iterator\[Polyline\]** Convert the given *paths* into 3D *Polyline* entities. - **Parameters** - • **paths** – iterable of *Path* objects - • **distance** – maximum distance, see *Path.flattening()* - • **segments** – minimum segment count per Bézier curve - • **dxfattribs** – additional DXF attribs - **Returns** iterable of 3D *Polyline* objects - **ezdxf.path.to\_splines\_and\_polylines(paths: Iterable\[Path\], \*, g1\_tol: float = G1\_TOL, dxfattribs=None) -\> Iterator\[Spline \| Polyline\]** Convert the given *paths* into *Spline* and 3D *Polyline* entities. - **Parameters** - • **paths** – iterable of *Path* objects - • **g1\_tol** – tolerance for G1 continuity check - • **dxfattribs** – additional DXF attribs - **Returns** iterable of *Line* objects ### Tool Maker Functions to create construction tools. - **ezdxf.path.to\_bsplines\_and\_vertices(path: Path, g1\_tol: float = G1\_TOL) -\> Iterator\[*BSpline* \| List\[*Vec3*\]\]** Convert a *Path* object into multiple cubic B-splines and polylines as lists of vertices. Breaks adjacent Bèzier without G1 continuity into separated B-splines. - **Parameters** - • **path** – *Path* objects - • **g1\_tol** – tolerance for G1 continuity check - **Returns** *BSpline* and lists of *Vec3* ### Utility Functions - **ezdxf.path.add\_bezier3p(path: Path, curves: Iterable\[*Bezier3P*\]) -\> None** Add multiple quadratic Bèzier-curves to the given *path*. Auto-detect the connection point to the given *path*, if neither the start- nor the end point of the curves is close to the path end point, a line from the path end point to the start point of the first curve will be added automatically. - **ezdxf.path.add\_bezier4p(path: Path, curves: Iterable\[*Bezier4P*\]) -\> None** Add multiple cubic Bèzier-curves to the given *path*. Auto-detect the connection point to the given *path*, if neither the start- nor the end point of the curves is close to the path end point, a line from the path end point to the start point of the first curve will be added automatically. - **ezdxf.path.add\_ellipse(path: Path, ellipse: *ConstructionEllipse*, segments=1, reset=True) -\> None** Add an elliptical arc as multiple cubic Bèzier-curves to the given *path*, use *from\_arc()* constructor of class *ConstructionEllipse* to add circular arcs. Auto-detect the connection point to the given *path*, if neither the start- nor the end point of the ellipse is close to the path end point, a line from the path end point to the ellipse start point will be added automatically (see *add\_bezier4p()*). By default, the start of an **empty** path is set to the start point of the ellipse, setting argument *reset* to **False** prevents this behavior. - **Parameters** - • **path** – *Path* object - • **ellipse** – ellipse parameters as *ConstructionEllipse* object - • **segments** – count of Bèzier-curve segments, at least one segment for each quarter (pi/2), **1** for as few as possible. - • **reset** – set start point to start of ellipse if path is empty - **ezdxf.path.add\_spline(path: Path, spline: *BSpline*, level=4, reset=True) -\> None** Add a B-spline as multiple cubic Bèzier-curves. Non-rational B-splines of 3rd degree gets a perfect conversion to cubic Bézier curves with a minimal count of curve segments, all other B-spline require much more curve segments for approximation. Auto-detect the connection point to the given *path*, if neither the start- nor the end point of the B-spline is close to the path end point, a line from the path end point to the start point of the B-spline will be added automatically. (see *add\_bezier4p()*). By default, the start of an **empty** path is set to the start point of the spline, setting argument *reset* to **False** prevents this behavior. - **Parameters** - • **path** – *Path* object - • **spline** – B-spline parameters as *BSpline* object - • **level** – subdivision level of approximation segments - • **reset** – set start point to start of spline if path is empty - **ezdxf.path.bbox(paths: Iterable\[Path\], \*, fast=False) -\> *BoundingBox*** Returns the *BoundingBox* for the given paths. - **Parameters** - • **paths** – iterable of *Path* or **Path2d** objects - • **fast** – calculates the precise bounding box of Bèzier curves if **False**, otherwise uses the control points of Bézier curves to determine their bounding box. - **ezdxf.path.chamfer(points: Sequence\[*Vec3*\], length: float) -\> Path** Returns a *Path* with chamfers of given *length* between straight line segments. - **Parameters** - • **points** – coordinates of the line segments - • **length** – chamfer length - **ezdxf.path.chamfer2(points: Sequence\[*Vec3*\], a: float, b: float) -\> Path** Returns a *Path* with chamfers at the given distances *a* and *b* from the segment points between straight line segments. - **Parameters** - • **points** – coordinates of the line segments - • **a** – distance of the chamfer start point to the segment point - • **b** – distance of the chamfer end point to the segment point - **ezdxf.path.fillet(points: Sequence\[*Vec3*\], radius: float) -\> Path** Returns a *Path* with circular fillets of given *radius* between straight line segments. - **Parameters** - • **points** – coordinates of the line segments - • **radius** – fillet radius - **ezdxf.path.fit\_paths\_into\_box(paths: Iterable\[Path\], size: tuple\[float, float, float\], uniform: bool = True, source\_box: *BoundingBox* \| None = None) -\> list\[Path\]** Scale the given *paths* to fit into a box of the given *size*, so that all path vertices are inside these borders. If *source\_box* is **None** the default source bounding box is calculated from the control points of the *paths*. *Note:* if the target size has a z-size of 0, the *paths* are projected into the xy-plane, same is true for the x-size, projects into the yz-plane and the y-size, projects into and xz-plane. - **Parameters** - • **paths** – iterable of *Path* objects - • **size** – target box size as tuple of x-, y- and z-size values - • **uniform** – **True** for uniform scaling - • **source\_box** – pass precalculated source bounding box, or **None** to calculate the default source bounding box from the control vertices - **ezdxf.path.have\_close\_control\_vertices(a: Path, b: Path, \*, rel\_tol=1e-9, abs\_tol=1e-12) -\> bool** Returns **True** if the control vertices of given paths are close. - **ezdxf.path.lines\_to\_curve3(path: Path) -\> Path** Replaces all lines by quadratic Bézier curves. Returns a new *Path* instance. - **ezdxf.path.lines\_to\_curve4(path: Path) -\> Path** Replaces all lines by cubic Bézier curves. Returns a new *Path* instance. - **ezdxf.path.polygonal\_fillet(points: Sequence\[*Vec3*\], radius: float, count: int = 32) -\> Path** Returns a *Path* with polygonal fillets of given *radius* between straight line segments. The *count* argument defines the vertex count of the fillet for a full circle. - **Parameters** - • **points** – coordinates of the line segments - • **radius** – fillet radius - • **count** – polygon vertex count for a full circle, minimum is 4 - **ezdxf.path.single\_paths(paths: Iterable\[Path\]) -\> Iterable\[Path\]** Yields all given paths and their sub-paths as single path objects. - **ezdxf.path.to\_multi\_path(paths: Iterable\[Path\]) -\> Path** Returns a multi-path object from all given paths and their sub-paths. Ignores paths without any commands (empty paths). - **ezdxf.path.transform\_paths(paths: Iterable\[Path\], m: *Matrix44*) -\> list\[Path\]** Transform multiple path objects at once by transformation matrix *m*. Returns a list of the transformed path objects. - **Parameters** - • **paths** – iterable of *Path* or **Path2d** objects - • **m** – transformation matrix of type *Matrix44* - **ezdxf.path.transform\_paths\_to\_ocs(paths: Iterable\[Path\], ocs: *OCS*) -\> list\[Path\]** Transform multiple *Path* objects at once from WCS to OCS. Returns a list of the transformed *Path* objects. - **Parameters** - • **paths** – iterable of *Path* or **Path2d** objects - • **ocs** – OCS transformation of type *OCS* - **ezdxf.path.triangulate(paths: Iterable\[Path\], max\_sagitta: float = 0.01, min\_segments: int = 16) -\> Iterator\[Sequence\[*Vec2*\]\]** Tessellate nested 2D paths into triangle-faces. For 3D paths the projection onto the xy-plane will be triangulated. - **Parameters** - • **paths** – iterable of nested Path instances - • **max\_sagitta** – maximum distance from the center of the curve to the center of the line segment between two approximation points to determine if a segment should be subdivided. - • **min\_segments** – minimum segment count per Bézier curve ### Basic Shapes - **ezdxf.path.elliptic\_transformation(center: *UVec* = (0, 0, 0), radius: float = 1, ratio: float = 1, rotation: float = 0) -\> *Matrix44*** Returns the transformation matrix to transform a unit circle into an arbitrary circular- or elliptic arc. Example how to create an ellipse with a major axis length of 3, a minor axis length 1.5 and rotated about 90°: ``` m = elliptic_transformation(radius=3, ratio=0.5, rotation=math.pi / 2) ellipse = shapes.unit_circle(transform=m) ``` - **Parameters** - • **center** – curve center in WCS - • **radius** – radius of the major axis in drawing units - • **ratio** – ratio of minor axis to major axis - • **rotation** – rotation angle about the z-axis in radians - **ezdxf.path.gear(count: int, top\_width: float, bottom\_width: float, height: float, outside\_radius: float, transform: *Matrix44* \| None = None) -\> Path** Returns a *gear* (cogwheel) shape as a *Path* object, with the center at (0, 0, 0). The base geometry is created by function *ezdxf.render.forms.gear()*. **WARNING:** This function does not create correct gears for mechanical engineering! - **Parameters** - • **count** – teeth count \>= 3 - • **top\_width** – teeth width at outside radius - • **bottom\_width** – teeth width at base radius - • **height** – teeth height; base radius = outside radius - height - • **outside\_radius** – outside radius - • **transform** – transformation Matrix applied to the gear shape - **ezdxf.path.helix(radius: float, pitch: float, turns: float, ccw=True, segments: int = 4) -\> Path** Returns a *helix* as a *Path* object. The center of the helix is always (0, 0, 0), a positive *pitch* value creates a helix along the +z-axis, a negative value along the -z-axis. - **Parameters** - • **radius** – helix radius - • **pitch** – the height of one complete helix turn - • **turns** – count of turns - • **ccw** – creates a counter-clockwise turning (right-handed) helix if **True** - • **segments** – cubic Bezier segments per turn - **ezdxf.path.ngon(count: int, length: float \| None = None, radius: float = 1.0, transform: *Matrix44* \| None = None) -\> Path** Returns a *regular polygon* a *Path* object, with the center at (0, 0, 0). The polygon size is determined by the edge *length* or the circum *radius* argument. If both are given *length* has higher priority. Default size is a *radius* of 1. The ngon starts with the first vertex is on the x-axis! The base geometry is created by function *ezdxf.render.forms.ngon()*. - **Parameters** - • **count** – count of polygon corners \>= 3 - • **length** – length of polygon side - • **radius** – circum radius, default is 1 - • **transform** – transformation Matrix applied to the ngon - **ezdxf.path.rect(width: float = 1, height: float = 1, transform: *Matrix44* \| None = None) -\> Path** Returns a closed rectangle as a *Path* object, with the center at (0, 0, 0) and the given *width* and *height* in drawing units. - **Parameters** - • **width** – width of the rectangle in drawing units, width \> 0 - • **height** – height of the rectangle in drawing units, height \> 0 - • **transform** – transformation Matrix applied to the rectangle - **ezdxf.path.star(count: int, r1: float, r2: float, transform: *Matrix44* \| None = None) -\> Path** Returns a *star shape* as a *Path* object, with the center at (0, 0, 0). Argument *count* defines the count of star spikes, *r1* defines the radius of the “outer” vertices and *r2* defines the radius of the “inner” vertices, but this does not mean that *r1* has to be greater than *r2*. The star shape starts with the first vertex is on the x-axis! The base geometry is created by function *ezdxf.render.forms.star()*. - **Parameters** - • **count** – spike count \>= 3 - • **r1** – radius 1 - • **r2** – radius 2 - • **transform** – transformation Matrix applied to the star - **ezdxf.path.unit\_circle(start\_angle: float = 0, end\_angle: float = math.tau, segments: int = 1, transform: *Matrix44* \| None = None) -\> Path** Returns a unit circle as a *Path* object, with the center at (0, 0, 0) and the radius of 1 drawing unit. The arc spans from the start- to the end angle in counter-clockwise orientation. The end angle has to be greater than the start angle and the angle span has to be greater than 0. - **Parameters** - • **start\_angle** – start angle in radians - • **end\_angle** – end angle in radians (end\_angle \> start\_angle!) - • **segments** – count of Bèzier-curve segments, default is one segment for each arc quarter (π/2) - • **transform** – transformation Matrix applied to the unit circle - **ezdxf.path.wedge(start\_angle: float, end\_angle: float, segments: int = 1, transform: *Matrix44* \| None = None) -\> Path** Returns a wedge as a *Path* object, with the center at (0, 0, 0) and the radius of 1 drawing unit. The arc spans from the start- to the end angle in counter-clockwise orientation. The end angle has to be greater than the start angle and the angle span has to be greater than 0. - **Parameters** - • **start\_angle** – start angle in radians - • **end\_angle** – end angle in radians (end\_angle \> start\_angle!) - • **segments** – count of Bèzier-curve segments, default is one segment for each arc quarter (π/2) - • **transform** – transformation Matrix applied to the wedge The *text2path* add-on provides additional functions to create paths from text strings and DXF text entities. ### The Path Class - **class ezdxf.path.Path** - **property end: *Vec3*** *Path* end point. - **property has\_curves: bool** Returns **True** if the path has any curve segments. - **property has\_lines: bool** Returns **True** if the path has any line segments. - **property has\_sub\_paths: bool** Returns **True** if the path is a *Multi-Path* object that contains multiple sub-paths. - **property is\_closed: bool** Returns **True** if the start point is close to the end point. - **property start: *Vec3*** *Path* start point, resetting the start point of an empty path is possible. - **property user\_data: Any** Attach arbitrary user data to a *Path* object. The user data is copied by reference, no deep copy is applied therefore a mutable state is shared between copies. - **append\_path(path: Path) -\> None** Append another path to this path. Adds a **self.line\_to(path.start)** if the end of this path != the start of appended path. - **approximate(segments: int = 20) -\> Iterator\[*Vec3*\]** Approximate path by vertices, *segments* is the count of approximation segments for each Bézier curve. Does not yield any vertices for empty paths, where only a start point is present! Approximation of *Multi-Path* objects is possible, but gaps are indistinguishable from line segments. - **bbox() -\> *BoundingBox*** Returns the bounding box of all control vertices as *BoundingBox* instance. - **clockwise() -\> Self** Returns new *Path* in clockwise orientation. - **Raises** **TypeError** – can’t detect orientation of a *Multi-Path* object - **clone() -\> Self** Returns a new copy of *Path* with shared immutable data. - **close() -\> None** Close path by adding a line segment from the end point to the start point. - **close\_sub\_path() -\> None** Close last sub-path by adding a line segment from the end point to the start point of the last sub-path. Behaves like *close()* for *Single-Path* instances. - **control\_vertices() -\> list\[*Vec3*\]** Yields all path control vertices in consecutive order. - **counter\_clockwise() -\> Self** Returns new *Path* in counter-clockwise orientation. - **Raises** **TypeError** – can’t detect orientation of a *Multi-Path* object - **curve3\_to(location: *UVec*, ctrl: *UVec*) -\> None** Add a quadratic Bèzier-curve from actual path end point to *location*, *ctrl* is the control point for the quadratic Bèzier-curve. - **curve4\_to(location: *UVec*, ctrl1: *UVec*, ctrl2: *UVec*) -\> None** Add a cubic Bèzier-curve from actual path end point to *location*, *ctrl1* and *ctrl2* are the control points for the cubic Bèzier-curve. - **extend\_multi\_path(path: Path) -\> None** Extend the path by another path. The source path is automatically a *Multi-Path* object, even if the previous end point matches the start point of the appended path. Ignores paths without any commands (empty paths). - **flattening(distance: float, segments: int = 4) -\> Iterator\[*Vec3*\]** Approximate path by vertices and use adaptive recursive flattening to approximate Bèzier curves. The argument *segments* is the minimum count of approximation segments for each curve, if the distance from the center of the approximation segment to the curve is bigger than *distance* the segment will be subdivided. Does not yield any vertices for empty paths, where only a start point is present! Flattening of *Multi-Path* objects is possible, but gaps are indistinguishable from line segments. - **Parameters** - • **distance** – maximum distance from the center of the curve to the center of the line segment between two approximation points to determine if a segment should be subdivided. - • **segments** – minimum segment count per Bézier curve - **has\_clockwise\_orientation() -\> bool** Returns **True** if 2D path has clockwise orientation, ignores z-axis of all control vertices. - **Raises** **TypeError** – can’t detect orientation of a *Multi-Path* object - **line\_to(location: *UVec*) -\> None** Add a line from actual path end point to *location*. - **move\_to(location: *UVec*) -\> None** Start a new sub-path at *location*. This creates a gap between the current end-point and the start-point of the new sub-path. This converts the instance into a *Multi-Path* object. If the *move\_to()* command is the first command, the start point of the path will be reset to *location*. - **reversed() -\> Self** Returns a new *Path* with reversed commands and control vertices. - **sub\_paths() -\> Iterator\[Self\]** Yield all sub-paths as *Single-Path* objects. It’s safe to call *sub\_paths()* on any path-type: *Single-Path*, *Multi-Path* and *Empty-Path*. - **transform(m: *Matrix44*) -\> Self** Returns a new transformed path. - **Parameters** **m** – transformation matrix of type *Matrix44* ### Reorder Tools to reorder DXF entities by handle or a special sort handle mapping. Such reorder mappings are stored only in layouts as *Modelspace*, *Paperspace* or *BlockLayout*, and can be retrieved by the method **get\_redraw\_order()**. Each entry in the handle mapping replaces the actual entity handle, where the “0” handle has a special meaning, this handle always shows up at last in ascending ordering. - **ezdxf.reorder.ascending(entities: Iterable\[*DXFGraphic*\], mapping: dict \| Iterable\[tuple\[str, str\]\] \| None = None) -\> Iterable\[*DXFGraphic*\]** Yields entities in ascending handle order. The sort-handle doesn’t have to be the entity handle, every entity handle in *mapping* will be replaced by the given sort-handle, *mapping* is an iterable of 2-tuples (entity\_handle, sort\_handle) or a dict (entity\_handle, sort\_handle). Entities with equal sort-handles show up in source entities order. - **Parameters** - • **entities** – iterable of **DXFGraphic** objects - • **mapping** – iterable of 2-tuples (entity\_handle, sort\_handle) or a handle mapping as dict. - **ezdxf.reorder.descending(entities: Iterable\[*DXFGraphic*\], mapping: dict \| Iterable\[tuple\[str, str\]\] \| None = None) -\> Iterable\[*DXFGraphic*\]** Yields entities in descending handle order. The sort-handle doesn’t have to be the entity handle, every entity handle in *mapping* will be replaced by the given sort-handle, *mapping* is an iterable of 2-tuples (entity\_handle, sort\_handle) or a dict (entity\_handle, sort\_handle). Entities with equal sort-handles show up in reversed source entities order. - **Parameters** - • **entities** – iterable of **DXFGraphic** objects - • **mapping** – iterable of 2-tuples (entity\_handle, sort\_handle) or a handle mapping as dict. ### Transform Added in version 1.1. This module provides functions to apply transformations to multiple DXF entities inplace or to virtual copies of that entities in a convenient and safe way: ``` import math import ezdxf from ezdxf import transform doc = ezdxf.readfile("my.dxf") msp = doc.modelspace() log = transform.inplace(msp, m=transform.Matrix44.rotate_z(math.pi/2)) # or more simple log = transform.z_rotate(msp, math.pi/2) ``` All functions handle errors by collecting them in an logging object without raising an error. The input *entities* are an iterable of *DXFEntity*, which can be any layout, *EntityQuery* or just a list/sequence of entities and virtual entities are supported as well. | | | | --- | --- | | *inplace* | Transforms the given *entities* inplace by the transformation matrix *m*, non-uniform scaling is supported. | | *copies* | Copy entities and transform them by matrix *m*. | | *translate* | Translates (moves) *entities* inplace by the *offset* vector. | | *scale\_uniform* | Scales *entities* inplace by a *factor* in all axis. | | *scale* | Scales *entities* inplace by the factors *sx* in x-axis, *sy* in y-axis and *sz* in z-axis. | | *x\_rotate* | Rotates *entities* inplace by *angle* in radians about the x-axis. | | *y\_rotate* | Rotates *entities* inplace by *angle* in radians about the y-axis. | | *z\_rotate* | Rotates *entities* inplace by *angle* in radians about the x-axis. | | *axis\_rotate* | Rotates *entities* inplace by *angle* in radians about the rotation axis starting at the origin pointing in *axis* direction. | - **ezdxf.transform.inplace(entities: Iterable\[DXFEntity\], m: *Matrix44*) -\> *Logger*** Transforms the given *entities* inplace by the transformation matrix *m*, non-uniform scaling is supported. The function converts circular arcs into ellipses to perform non-uniform scaling. The function logs errors and does not raise errors for unsupported entities or transformation errors, see enum *Error*. **IMPORTANT:** The *inplace()* function does not support type conversion for virtual entities e.g. non-uniform scaling for CIRCLE, ARC or POLYLINE with bulges, see also function *copies()*. - **ezdxf.transform.copies(entities: Iterable\[DXFEntity\], m: *Matrix44* \| None = None) -\> Tuple\[*Logger*, List\[DXFEntity\]\]** Copy entities and transform them by matrix *m*. Does not raise any exception and ignores all entities that cannot be copied or transformed. Just copies the input entities if matrix *m* is **None**. Returns a tuple of *Logger* and a list of transformed virtual copies. The function supports virtual entities as input and converts circular arcs into ellipses to perform non-uniform scaling. - **ezdxf.transform.translate(entities: Iterable\[DXFEntity\], offset: *UVec*) -\> *Logger*** Translates (moves) *entities* inplace by the *offset* vector. - **ezdxf.transform.scale\_uniform(entities: Iterable\[DXFEntity\], factor: float) -\> *Logger*** Scales *entities* inplace by a *factor* in all axis. Scaling factors smaller than *MIN\_SCALING\_FACTOR* are ignored. - **ezdxf.transform.scale(entities: Iterable\[DXFEntity\], sx: float, sy: float, sz: float) -\> *Logger*** Scales *entities* inplace by the factors *sx* in x-axis, *sy* in y-axis and *sz* in z-axis. Scaling factors smaller than *MIN\_SCALING\_FACTOR* are ignored. **IMPORTANT:** same limitations for virtual entities as the *inplace()* function - **ezdxf.transform.x\_rotate(entities: Iterable\[DXFEntity\], angle: float) -\> *Logger*** Rotates *entities* inplace by *angle* in radians about the x-axis. - **ezdxf.transform.y\_rotate(entities: Iterable\[DXFEntity\], angle: float) -\> *Logger*** Rotates *entities* inplace by *angle* in radians about the y-axis. - **ezdxf.transform.z\_rotate(entities: Iterable\[DXFEntity\], angle: float) -\> *Logger*** Rotates *entities* inplace by *angle* in radians about the x-axis. - **ezdxf.transform.axis\_rotate(entities: Iterable\[DXFEntity\], axis: *UVec*, angle: float) -\> *Logger*** Rotates *entities* inplace by *angle* in radians about the rotation axis starting at the origin pointing in *axis* direction. - **ezdxf.transform.MIN\_SCALING\_FACTOR** Minimal scaling factor: 1e-12 - **class ezdxf.transform.Error** - **NONE** No error, same as a boolean **False**, this allows check **if error: ...** - **COPY\_NOT\_SUPPORTED** Entity without copy support. - **TRANSFORMATION\_NOT\_SUPPORTED** Entity without transformation support. - **NON\_UNIFORM\_SCALING\_ERROR** Circular arcs (CIRCLE, ARC, bulges in POLYLINE and LWPOLYLINE entities) cannot be scaled non-uniformly. - **INSERT\_TRANSFORMATION\_ERROR** INSERT entities cannot represent a non-orthogonal target coordinate system. Maybe exploding the INSERT entities (recursively) beforehand can solve this issue, see function *ezdxf.disassemble.recursive\_decompose()*. - **VIRTUAL\_ENTITY\_NOT\_SUPPORTED** Transformation not supported for virtual entities e.g. non-uniform scaling for CIRCLE, ARC or POLYLINE with bulges - **class ezdxf.transform.Logger** A **Sequence** of errors as *Logger.Entry* instances. - **class Entry** Named tuple representing a logger entry. - **error** *Error* enum - **msg** error message as string - **entity** DXF entity which causes the error - **\_\_len\_\_() -\> int** Returns the count of error entries. - **\_\_getitem\_\_(index: int) -\> *Entry*** Returns the error entry at *index*. - **\_\_iter\_\_() -\> Iterator\[*Entry*\]** Iterates over all error entries. - **messages() -\> list\[str\]** Returns all error messages as list of strings. ### Upright The functions in this module can help to convert an inverted *OCS* defined by an extrusion vector (0, 0, -1) into a *WCS* aligned OCS defined by an extrusion vector (0, 0, 1). This simplifies 2D entity processing for *ezdxf* users and creates DXF output for 3rd party DXF libraries which ignore the existence of the *OCS*. Supported DXF entities: - • CIRCLE - • ARC - • ELLIPSE (WCS entity, flips only the extrusion vector) - • SOLID - • TRACE - • LWPOLYLINE - • POLYLINE (only 2D entities) - • HATCH - • MPOLYGON - • INSERT (block references) **WARNING:** The WCS representation of OCS entities with flipped extrusion vector is not 100% identical to the source entity, curve orientation and vertex order may change, see *additional explanation* below. A mirrored text represented by an extrusion vector (0, 0, -1) cannot represented by an extrusion vector (0, 0, 1), therefore this CANNOT work for text entities or entities including text: TEXT, ATTRIB, ATTDEF, MTEXT, DIMENSION, LEADER, MLEADER ### Usage The functions can be applied to any DXF entity without expecting errors or exceptions if the DXF entity is not supported or the extrusion vector differs from (0, 0, -1). This also means you can apply the functions multiple times to the same entities without any problems. A common case would be to upright all entities of the model space: ``` import ezdxf from ezdxf.upright import upright_all doc = ezdxf.readfile("your.dxf") msp = doc.modelspace() upright_all(msp) # doing it again is no problem but also has no further effects upright_all(msp) ``` Another use case is exploding block references (INSERT) which may include reflections (= scaling by negative factors) that can lead to inverted extrusion vectors. ``` for block_ref in msp.query("INSERT"): entities = block_ref.explode() # -> EntityQuery object upright_all(entities) ``` ### Functions - **ezdxf.upright.upright(entity: DXFGraphic) -\> None** Flips an inverted *OCS* defined by extrusion vector (0, 0, -1) into a *WCS* aligned *OCS* defined by extrusion vector (0, 0, 1). DXF entities with other extrusion vectors and unsupported DXF entities will be silently ignored. For more information about the limitations read the documentation of the *ezdxf.upright* module. - **ezdxf.upright.upright\_all(entities: Iterable\[DXFGraphic\]) -\> None** Call function *upright()* for all DXF entities in iterable *entities*: ``` upright_all(doc.modelspace()) ``` ### Additional Explanation This example shows why the entities with an inverted OCS, extrusion vector is (0, 0, -1), are not exact the same as with an WCS aligned OCS, extrusion vector is (0, 0, 1). **NOTE:** The ARC entity represents the curve **always** in counter-clockwise orientation around the extrusion vector. ``` import ezdxf from ezdxf.upright import upright from ezdxf.math import Matrix44 doc = ezdxf.new() msp = doc.modelspace() arc = msp.add_arc( (5, 0), radius=5, start_angle=-90, end_angle=90, dxfattribs={"color": ezdxf.const.RED}, ) # draw lines to the start- and end point of the ARC msp.add_line((0, 0), arc.start_point, dxfattribs={"color": ezdxf.const.GREEN}) msp.add_line((0, 0), arc.end_point, dxfattribs={"color": ezdxf.const.BLUE}) # copy arc mirrored_arc = arc.copy() msp.add_entity(mirrored_arc) # mirror copy mirrored_arc.transform(Matrix44.scale(-1, 1, 1)) # This creates an inverted extrusion vector: assert mirrored_arc.dxf.extrusion.isclose((0, 0, -1)) # draw lines to the start- and end point of the mirrored ARC msp.add_line((0, 0), mirrored_arc.start_point, dxfattribs={"color": ezdxf.const.GREEN}) msp.add_line((0, 0), mirrored_arc.end_point, dxfattribs={"color": ezdxf.const.BLUE}) ``` Result without applying the *upright()* function - true mirroring: \[image\] ``` ... # This creates an inverted extrusion vector: assert mirrored_arc.dxf.extrusion.isclose((0, 0, -1)) start_point_inv = mirrored_arc.start_point end_point_inv = mirrored_arc.end_point upright(mirrored_arc) # OCS is aligned with WCS: assert mirrored_arc.dxf.extrusion.isclose((0, 0, 1)) # start- and end points are swapped after applying upright() assert mirrored_arc.start_point.isclose(end_point_inv) assert mirrored_arc.end_point.isclose(start_point_inv) # draw lines to the start- and end point of the mirrored ARC msp.add_line((0, 0), mirrored_arc.start_point, dxfattribs={"color": ezdxf.const.GREEN}) msp.add_line((0, 0), mirrored_arc.end_point, dxfattribs={"color": ezdxf.const.BLUE}) ``` Result after applying the *upright()* function - false mirroring: \[image\] To avoid this issue the ARC entity would have to represent the curve in clockwise orientation around the extrusion vector (0, 0, 1), which is not possible! **NOTE:** The shape of the mirrored arcs is the same for both extrusion vectors, but the start- and the end points are swapped (reversed vertex order)! ### Custom Data ### Custom XDATA The classes *XDataUserList* and *XDataUserDict* manage custom user data stored in the XDATA section of a DXF entity. For more information about XDATA see reference section: *Extended Data (XDATA)* These classes store only a limited set of data types with fixed group codes and the types are checked by **isinstance()** so a **Vec3** object can not be replaced by a (x, y, z)-tuple: | | | | --- | --- | | Group Code | Data Type | | 1000 | str, limited to 255 characters, line breaks **"\\n"** and **"\\r"** are not allowed | | 1010 | Vec3 | | 1040 | float | | 1071 | 32-bit int, restricted by the DXF standard not by Python! | Strings are limited to 255 characters, line breaks **"\\n"** and **"\\r"** are not allowed. This classes assume a certain XDATA structure and therefore can not manage arbitrary XDATA! This classes do not create the required AppID table entry, only the default AppID “EZDXF” exist by default. Setup a new AppID in the AppID table: **doc.appids.add("MYAPP")**. For usage look at this *example* at github or go to the tutorial: *Storing Custom Data in DXF Files*. **SEE ALSO:** - • Tutorial: *Storing Custom Data in DXF Files* - • *Example* at github - • XDATA reference: *Extended Data (XDATA)* - • XDATA management class: *XData* ### XDataUserList - **class ezdxf.entities.xdata.XDataUserList** Manage user data as a named list-like object in XDATA. Multiple user lists with different names can be stored in a single *XData* instance for a single AppID. Recommended usage by context manager *entity()*: ``` with XDataUserList.entity(entity, name="MyList", appid="MYAPP") as ul: ul.append("The value of PI") # str "\n" and "\r" are not allowed ul.append(3.141592) # float ul.append(1) # int ul.append(Vec3(1, 2, 3)) # Vec3 # invalid data type raises DXFTypeError ul.append((1, 2, 3)) # tuple instead of Vec3 # retrieve a single value s = ul[0] # store whole content into a Python list data = list(ul) ``` Implements the **MutableSequence** interface. - **xdata** The underlying *XData* instance. - **\_\_init\_\_(xdata: *XData* \| None = None, name='DefaultList', appid='EZDXF')** Setup a XDATA user list *name* for the given *appid*. The data is stored in the given *xdata* object, or in a new created *XData* instance if **None**. Changes of the content has to be committed at the end to be stored in the underlying *xdata* object. - **Parameters** - • **xdata** (*XData*) – underlying *XData* instance, if **None** a new one will be created - • **name** (*str*) – name of the user list - • **appid** (*str*) – application specific AppID - **\_\_str\_\_()** Return str(self). - **\_\_len\_\_() -\> int** Returns len(self). - **\_\_getitem\_\_(item)** Get self\[item\]. - **\_\_setitem\_\_(item, value)** Set self\[item\] to value. - **\_\_delitem\_\_(item)** Delete self\[item\]. - **classmethod entity(entity: *DXFEntity*, name='DefaultList', appid='EZDXF') -\> Iterator\[*XDataUserList*\]** Context manager to manage a XDATA list *name* for a given DXF *entity*. Appends the user list to the existing *XData* instance or creates new *XData* instance. - **Parameters** - • **entity** (*DXFEntity*) – target DXF entity for the XDATA - • **name** (*str*) – name of the user list - • **appid** (*str*) – application specific AppID - **commit() -\> None** Store all changes to the underlying *XData* instance. This call is not required if using the *entity()* context manager. - **Raises** - • *DXFValueError* – invalid chars **"\\n"** or **"\\r"** in a string - • *DXFTypeError* – invalid data type ### XDataUserDict - **class ezdxf.entities.xdata.XDataUserDict** Manage user data as a named dict-like object in XDATA. Multiple user dicts with different names can be stored in a single *XData* instance for a single AppID. The keys have to be strings. Recommended usage by context manager *entity()*: ``` with XDataUserDict.entity(entity, name="MyDict", appid="MYAPP") as ud: ud["comment"] = "The value of PI" # str "\n" and "\r" are not allowed ud["pi"] = 3.141592 # float ud["number"] = 1 # int ud["vertex"] = Vec3(1, 2, 3) # Vec3 # invalid data type raises DXFTypeError ud["vertex"] = (1, 2, 3) # tuple instead of Vec3 # retrieve single values s = ud["comment"] pi = ud.get("pi", 3.141592) # store whole content into a Python dict data = dict(ud) ``` Implements the **MutableMapping** interface. The data is stored in XDATA like a *XDataUserList* by (key, value) pairs, therefore a *XDataUserDict* can also be loaded as *XDataUserList*. It is not possible to distinguish a *XDataUserDict* from a *XDataUserList* except by the name of the data structure. - **xdata** The underlying *XData* instance. - **\_\_init\_\_(xdata: *XData* \| None = None, name='DefaultDict', appid='EZDXF')** Setup a XDATA user dict *name* for the given *appid*. The data is stored in the given *xdata* object, or in a new created *XData* instance if **None**. Changes of the content has to be committed at the end to be stored in the underlying *xdata* object. - **Parameters** - • **xdata** (*XData*) – underlying *XData* instance, if **None** a new one will be created - • **name** (*str*) – name of the user list - • **appid** (*str*) – application specific AppID - **\_\_str\_\_()** Return str(self). - **\_\_len\_\_()** Returns len(self). - **\_\_getitem\_\_(key)** Get self\[key\]. - **\_\_setitem\_\_(key, item)** Set self\[key\] to value, key has to be a string. - **Raises** *DXFTypeError* – key is not a string - **\_\_delitem\_\_(key)** Delete self\[key\]. - **discard(key)** Delete self\[key\], without raising a **KeyError** if *key* does not exist. - **\_\_iter\_\_()** Implement iter(self). - **classmethod entity(entity: *DXFEntity*, name='DefaultDict', appid='EZDXF') -\> Iterator\[*XDataUserDict*\]** Context manager to manage a XDATA dict *name* for a given DXF *entity*. Appends the user dict to the existing *XData* instance or creates new *XData* instance. - **Parameters** - • **entity** (*DXFEntity*) – target DXF entity for the XDATA - • **name** (*str*) – name of the user list - • **appid** (*str*) – application specific AppID - **commit() -\> None** Store all changes to the underlying *XData* instance. This call is not required if using the *entity()* context manager. - **Raises** - • *DXFValueError* – invalid chars **"\\n"** or **"\\r"** in a string - • *DXFTypeError* – invalid data type ### Custom XRecord The *UserRecord* and *BinaryRecord* classes help to store custom data in DXF files in *XRecord* objects a simple and safe way. This way requires DXF version R2000 or later, for DXF version R12 the only way to store custom data is *Extended Data (XDATA)*. The *UserRecord* stores Python types and nested container types: **int**, **float**, **str**, *Vec2*, *Vec3*, **list** and **dict**. Requirements for Python structures: - • The top level structure has to be a **list**. - • Strings has to have max. 2049 characters and can not contain line breaks **"\\\\n"** or **"\\\\r"**. - • Dict keys have to be simple Python types: **int**, **float**, **str**. DXF Tag layout for Python types and structures stored in the *XRecord* object: Only for the *UserRecord* the first tag is (2, user record name). | | | | --- | --- | | Type | DXF Tag(s) | | str | (1, value) string with less than 2050 chars and including no line breaks | | int | (90, value) int 32-bit, restricted by the DXF standard not by Python! | | float | (40, value) “C” double | | Vec2 | (10, x), (20, y) | | Vec3 | (10, x) (20, y) (30, z) | | list | starts with (2, “\[”) and ends with (2, “\]”) | | dict | starts with (2, “{”) and ends with (2, “}”) | The *BinaryRecord* stores arbitrary binary data as *BLOB*. Storage size limits of XRECORD according the DXF reference: “This object is similar in concept to XDATA but is not limited by size or order.” For usage look at this *example* at github or go to the tutorial: *Storing Custom Data in DXF Files*. **SEE ALSO:** - • Tutorial: *Storing Custom Data in DXF Files* - • *Example* at github - • *ezdxf.entities.XRecord* ### UserRecord - **class ezdxf.urecord.UserRecord** - **xrecord** The underlying *XRecord* instance - **name** The name of the *UserRecord*, an arbitrary string with less than 2050 chars and including no line breaks. - **data** The Python data. The top level structure has to be a list (**MutableSequence**). Inside this container the following Python types are supported: str, int, float, Vec2, Vec3, list, dict Nested data structures are supported list or/and dict in list or dict. Dict keys have to be simple Python types: int, float, str. - **property handle: str \| None** DXF handle of the underlying *XRecord* instance. - **\_\_init\_\_(xrecord: *XRecord* \| None = None, \*, name: str = DEFAULT\_NAME, doc: *Drawing* \| None = None)** Setup a *UserRecord* with the given *name*. The data is stored in the given *xrecord* object, or in a new created *XRecord* instance if **None**. If *doc* is not **None** the new xrecord is added to the OBJECTS section of the DXF document. Changes of the content has to be committed at the end to be stored in the underlying *xrecord* object. - **Parameters** - • **xrecord** (*XRecord*) – underlying *XRecord* instance, if **None** a new one will be created - • **name** (*str*) – name of the user list - • **doc** (*Drawing*) – DXF document or **None** - **\_\_str\_\_()** Return str(self). - **commit() -\> XRecord** Store *data* in the underlying *XRecord* instance. This call is not required if using the class by the **with** statement. - **Raises** - • *DXFValueError* – invalid chars **"\\n"** or **"\\r"** in a string - • *DXFTypeError* – invalid data type ### BinaryRecord - **class ezdxf.urecord.BinaryRecord** - **xrecord** The underlying *XRecord* instance - **data** The binary data as bytes, bytearray or memoryview. - **property handle: str \| None** DXF handle of the underlying *XRecord* instance. - **\_\_init\_\_(xrecord: *XRecord* \| None = None, \*, doc: *Drawing* \| None = None)** Setup a *BinaryRecord*. The data is stored in the given *xrecord* object, or in a new created *XRecord* instance if **None**. If *doc* is not **None** the new xrecord is added to the OBJECTS section of the DXF document. Changes of the content has to be committed at the end to be stored in the underlying *xrecord* object. - **Parameters** - • **xrecord** (*XRecord*) – underlying *XRecord* instance, if **None** a new one will be created - • **doc** (*Drawing*) – DXF document or **None** - **\_\_str\_\_() -\> str** Return str(self). - **commit() -\> XRecord** Store binary *data* in the underlying *XRecord* instance. This call is not required if using the class by the **with** statement. ### Fonts ### Fonts The module *ezdxf.fonts.fonts* manages the internal usage of fonts and has no relation how the DXF formats manages text styles. **SEE ALSO:** The *Textstyle* entity, the DXF way to define fonts. Added in version 1.1. Since *ezdxf* v1.1 text rendering is done by the *fontTools* package. Support for stroke fonts, these are the basic vector fonts included in CAD applications, like .shx, .shp or .lff fonts was also added. None of the required font files (.ttf, .ttc, .otf, .shx, .shp or .lff) are included in *ezdxf* as they are copyrighted or, in the case of the LibreCAD font format (.lff), licensed under the “GPL v2 and later”. ### Font Locations ### TrueType Fonts The font manager searches the following directories recursively for .ttf, .ttc and .otf font files. - • - **Windows:** - • \~/AppData/Local/Microsoft/Windows/Fonts - • \/Fonts - • - **Linux and other \*nix like systems:** - • /usr/share/fonts - • /usr/local/share/fonts - • \~/.fonts - • \~/.local/share/fonts - • \~/.local/share/texmf/fonts - • - **macOS:** - • /Library/Fonts - • /System/Library/Fonts The *fc-list* command on Linux shows all available fonts and their location. The default font is selected in the following order, if none of them is available on your system - install one of them, the open source fonts can be found in the github repository in the folder *ezdxf/fonts*. - • Arial.ttf - • DejaVuSansCondensed.ttf - • DejaVuSans.ttf - • LiberationSans-Regular.ttf - • OpenSans-Regular.ttf ### Basic Stroke Fonts There is no universal way to find the basic stroke fonts of CAD applications on a system, beside scanning all drives. Set the paths to the stroke fonts in your config file manually to tell *ezdxf* where to search for them, all paths are search recursively, see also option *ezdxf.options.support\_dirs*: ``` [core] support_dirs = "C:\Program Files\Bricsys\BricsCAD V23 en_US\Fonts", ~/shx_fonts, ~/shp_fonts, ~/lff_fonts, ``` The .shx fonts can be found on the internet but be aware that they are not free as all websites claim. The LibreCAD font files (.llf) can be downloaded from their github repository: *https://github.com/LibreCAD/LibreCAD/tree/master/librecad/support/fonts* **IMPORTANT:** When you add new font directories to **support\_dirs** or new fonts to one of the support directories, you have to rebuild the font cache to use these fonts, see section *Rebuilding the Font Cache* for more information. ### Font Caching The fonts available on a system are cached automatically, the cache has to be rebuild by the *build\_system\_font\_cache()* function to recognize new installed fonts or when you add new font directories to the config file. The cache is stored in the users home directory “~/.cache/ezdxf” or the directory specified by the environment variable “XDG\_CACHE\_HOME”. ### Rebuilding the Font Cache When you add new fonts to your system or add a font directory to the support directories in the config file you have to rebuild the font-cache of *ezdxf* to recognize these new fonts: ``` import ezdxf from ezdxf.fonts import fonts fonts.build_system_font_cache() ``` or call the *ezdxf* launcher to do that: ``` ezdxf --fonts ``` ### Functions - **ezdxf.fonts.fonts.make\_font(font\_name: str, cap\_height: float, width\_factor: float = 1.0) -\> *AbstractFont*** Returns a font abstraction based on class *AbstractFont*. Supported font types: - • .ttf, .ttc and .otf - TrueType fonts - • .shx, .shp - Autodesk® shapefile fonts - • .lff - LibreCAD font format The special name “\*monospace” returns the fallback font *MonospaceFont* for testing and basic measurements. **NOTE:** The font definition files are not included in *ezdxf*. - **Parameters** - • **font\_name** – font file name as stored in the *Textstyle* entity e.g. “OpenSans-Regular.ttf” - • **cap\_height** – desired cap height in drawing units. - • **width\_factor** – horizontal text stretch factor - **ezdxf.fonts.fonts.get\_font\_face(font\_name: str, map\_shx=True) -\> *FontFace*** Returns the *FontFace* definition for the given font filename e.g. “LiberationSans-Regular.ttf”. This function translates a DXF font definition by the TTF font file name into a *FontFace* object. Returns the *FontFace* of the default font when a font is not available on the current system. - **Parameters** - • **font\_name** – raw font file name as stored in the *Textstyle* entity - • **map\_shx** – maps SHX font names to TTF replacement fonts, e.g. “TXT” -\> “txt\_\_\_\_\_.ttf” - **ezdxf.fonts.fonts.find\_font\_face(font\_name: str) -\> *FontFace*** Returns the *FontFace* definition for the given font filename e.g. “LiberationSans-Regular.ttf”. - **ezdxf.fonts.fonts.find\_font\_file\_name(font\_face: *FontFace*) -\> str** Returns the true type font file name without parent directories e.g. “Arial.ttf”. - **ezdxf.fonts.fonts.find\_best\_match(\*, family: str = 'sans-serif', style: str = 'Regular', weight: int = 400, width: int = 5, italic: bool \| None = False) -\> *FontFace* \| None** Returns a *FontFace* that matches the given properties best. The search is based the descriptive properties and not on comparing glyph shapes. Returns **None** if no font was found. - **Parameters** - • **family** – font family name e.g. “sans-serif”, “Liberation Sans” - • **style** – font style e.g. “Regular”, “Italic”, “Bold” - • **weight** – weight in the range from 1-1000 (usWeightClass) - • **width** – width in the range from 1-9 (usWidthClass) - • **italic** – **True**, **False** or **None** to ignore this flag - **ezdxf.fonts.fonts.get\_entity\_font\_face(entity: *DXFEntity*, doc: *Drawing* \| None = None) -\> *FontFace*** Returns the *FontFace* defined by the associated text style. Returns the default font face if the *entity* does not have or support the DXF attribute “style”. Supports the extended font information stored in *Textstyle* table entries. Pass a DXF document as argument *doc* to resolve text styles for virtual entities which are not assigned to a DXF document. The argument *doc* always overrides the DXF document to which the *entity* is assigned to. - **ezdxf.fonts.fonts.get\_font\_measurements(font\_name: str, map\_shx=True) -\> FontMeasurements** Get *FontMeasurements* for the given font filename e.g. “LiberationSans-Regular.ttf”. - **Parameters** - • **font\_name** – raw font file name as stored in the *Textstyle* entity - • **map\_shx** – maps SHX font names to TTF replacement fonts, e.g. “TXT” -\> “txt\_\_\_\_\_.ttf” - **ezdxf.fonts.fonts.build\_system\_font\_cache()** Builds or rebuilds the font manager cache. The font manager cache has a fixed location in the cache directory of the users home directory “~/.cache/ezdxf” or the directory specified by the environment variable “XDG\_CACHE\_HOME”. - **ezdxf.fonts.fonts.load()** Reload all cache files. The cache files are loaded automatically at the import of *ezdxf*. - **ezdxf.fonts.fonts.sideload\_ttf(font\_path: str \| PathLike, cap\_height) -\> *AbstractFont*** This function bypasses the FontManager and loads the TrueType font straight from the file system, requires the absolute font file path e.g. “C:/Windows/Fonts/Arial.ttf”. **WARNING:** Expert feature, use with care: no fallback font and no error handling. ### Classes - **class ezdxf.fonts.fonts.AbstractFont(measurements: FontMeasurements)** The *ezdxf* font abstraction for text measurement and text path rendering. - **name** The font filename e.g. “LiberationSans-Regular.ttf” - **font\_render\_type** The font type, see enum *FontRenderType* - **measurement** The *FontMeasurements* data. - **abstract text\_width(text: str) -\> float** Returns the text width in drawing units for the given *text* string. - **abstract text\_width\_ex(text: str, cap\_height: float, width\_factor: float = 1.0) -\> float** Returns the text width in drawing units, bypasses the stored *cap\_height* and *width\_factor*. - **abstract text\_path(text: str) -\> NumpyPath2d** Returns the 2D text path for the given text. - **abstract text\_path\_ex(text: str, cap\_height: float, width\_factor: float = 1.0) -\> NumpyPath2d** Returns the 2D text path for the given text, bypasses the stored *cap\_height* and *width\_factor*. - **abstract space\_width() -\> float** Returns the width of a “space” character a.k.a. word spacing. - **class ezdxf.fonts.fonts.MonospaceFont(cap\_height: float, width\_factor: float = 1.0, baseline: float = 0, descender\_factor: float = DESCENDER\_FACTOR, x\_height\_factor: float = X\_HEIGHT\_FACTOR)** Represents a monospaced font where each letter has the same cap- and descender height and the same width. The given cap height and width factor are the default values for measurements and rendering. The extended methods can override these default values. This font exists only for generic text measurement in tests and does not render any glyphs! - **class ezdxf.fonts.fonts.TrueTypeFont(font\_name: str, cap\_height: float, width\_factor: float = 1.0)** Represents a TrueType font. Font measurement and glyph rendering is done by the *fontTools* package. The given cap height and width factor are the default values for measurements and glyph rendering. The extended methods can override these default values. - **class ezdxf.fonts.fonts.ShapeFileFont(font\_name: str, cap\_height: float, width\_factor: float = 1.0)** Represents a shapefile font (.shx, .shp). Font measurement and glyph rendering is done by the ezdxf.fonts.shapefile module. The given cap height and width factor are the default values for measurements and glyph rendering. The extended methods can override these default values. - **class ezdxf.fonts.fonts.LibreCadFont(font\_name: str, cap\_height: float, width\_factor: float = 1.0)** Represents a LibreCAD font (.shx, .shp). Font measurement and glyph rendering is done by the ezdxf.fonts.lff module. The given cap height and width factor are the default values for measurements and glyph rendering. The extended methods can override these default values. ### Font Anatomy - • A Visual Guide to the Anatomy of Typography: *https://visme.co/blog/type-anatomy/* - • Anatomy of a Character: *https://www.fonts.com/content/learning/fontology/level-1/type-anatomy/anatomy* ### Font Properties DXF to store fonts in the *Textstyle* entity as TTF file name e.g. “LiberationSans-Regular.ttf”. The *FontFace* class can be used to specify a font in a more generic way: - **family** font name e.g. “Liberation Sans” or “Arial”, may a generic font family name, either “serif”, “sans-serif” or “monospace” - **style** “Regular”, “Italic”, “Oblique”, “Bold”, “BoldOblique”, … - **width** (usWidthClass) A numeric value in the range 0-9 | | | | --- | --- | | 1 | UltraCondensed | | 2 | ExtraCondensed | | 3 | Condensed | | 4 | SemiCondensed | | 5 | Normal or Medium | | 6 | SemiExpanded | | 7 | Expanded | | 8 | ExtraExpanded | | 9 | UltraExpanded | - **weight** (usWeightClass) A numeric value in the range 0-1000 | | | | --- | --- | | 100 | Thin | | 200 | ExtraLight | | 300 | Light | | 400 | Normal | | 500 | Medium | | 600 | SemiBold | | 700 | Bold | | 800 | ExtraBold | | 900 | Black | **SEE ALSO:** - • W3C: *https://www.w3.org/TR/2018/REC-css-fonts-3-20180920/* - **class ezdxf.fonts.fonts.FontRenderType** Enumeration of font render type. - **STROKE** Basic stroke font, can only be rendered as linear paths. - **OUTLINE** TrueType or similar font, can be rendered as filled paths or as outline strokes. - **class ezdxf.fonts.fonts.FontFace(filename, family, style, weight, width)** - **filename** font file name without parent directories as string, e.g. “arial.ttf” - **family** Family name as string, the default value is “sans-serif” - **style** Font style as string, the default value is “Regular” - **weight** Font weight as int in the renge from 0-1000, the default value is 400 (Normal) - **property weight\_str: str** Returns the *weight* as string e.g. “Thin”, “Normal”, “Bold”, … - **width** Font width (stretch) as int in the range from 1-9, the default value is 5 (Normal) - **property width\_str: str** Returns the *width* as string e.g. “Condensed”, “Expanded”, … - **property is\_italic: bool** Returns **True** if font face is italic. - **property is\_oblique: bool** Returns **True** if font face is oblique. - **property is\_bold: bool** Returns **True** if font face weight \> 400. - **class ezdxf.fonts.fonts.FontMeasurements** See *Font Anatomy* for more information. - **baseline** - **cap\_height** - **x\_height** - **descender\_height** - **scale(factor: float = 1.0) -\> FontMeasurements** - **scale\_from\_baseline(desired\_cap\_height: float) -\> FontMeasurements** - **shift(distance: float = 0.0) -\> FontMeasurements** - **property cap\_top: float** - **property x\_top: float** - **property bottom: float** - **property total\_height: float** ### Tools ### Application Settings This is a high-level module for working with CAD application settings and behaviors. None of these settings have any influence on the behavior of *ezdxf*, since *ezdxf* only takes care of the content of the DXF file and not of the way it is presented to the user. **IMPORTANT:** You need to understand that these settings work at the application level, *ezdxf* cannot force an application to do something in a certain way! The functionality of this module has been tested with Autodesk TrueView and BricsCAD, other applications may show different results or ignore the settings. ### Set Current Properties The current properties are used by the CAD application to create new entities, these settings do not affect how *ezdxf* creates new entities. The module *ezdxf.gfxattribs* provides the class *GfxAttribs()*, which can load the current graphical entity settings from the HEADER section for creating new entities by *ezdxf*: *load\_from\_header()* - **ezdxf.appsettings.set\_current\_layer(doc: *Drawing*, name: str)** Set current layer. - **ezdxf.appsettings.set\_current\_color(doc: *Drawing*, color: int)** Set current *AutoCAD Color Index (ACI)*. - **ezdxf.appsettings.set\_current\_linetype(doc: *Drawing*, name: str)** Set current linetype. - **ezdxf.appsettings.set\_current\_lineweight(doc: *Drawing*, lineweight: int)** Set current lineweight, see *Lineweights* reference for valid values. - **ezdxf.appsettings.set\_current\_linetype\_scale(doc: *Drawing*, scale: float)** Set current linetype scale. - **ezdxf.appsettings.set\_current\_textstyle(doc: *Drawing*, name: str)** Set current text style. - **ezdxf.appsettings.set\_current\_dimstyle(doc: *Drawing*, name: str)** Set current dimstyle. - **ezdxf.appsettings.set\_current\_dimstyle\_attribs(doc: *Drawing*, name: str)** Set current dimstyle and copy all dimstyle attributes to the HEADER section. - **ezdxf.appsettings.set\_lineweight\_display\_style(doc: *Drawing*, end\_caps: *EndCaps*, join\_style: *JoinStyle*) -\> None** Set the style of end caps and joints for linear entities when displaying line weights. These settings only affect objects created afterwards. ### Restore the WCS - **ezdxf.appsettings.restore\_wcs(doc: *Drawing*)** Restore the UCS settings in the HEADER section to the *WCS* and reset all active viewports to the WCS. ### Update Extents - **ezdxf.appsettings.update\_extents(doc: *Drawing*) -\> *BoundingBox*** Calculate the extents of the model space, update the HEADER variables $EXTMIN and $EXTMAX and returns the result as *ezdxf.math.BoundingBox*. Note that this function uses the *ezdxf.bbox* module to calculate the extent of the model space. This module is not very fast and not very accurate for text and ignores all *ACIS* based entities. The function updates only the values in the HEADER section, to zoom the active viewport to this extents, use this recipe: ``` import ezdxf from ezdxf import zoom, appsettings doc = ezdxf.readfile("your.dxf") extents = appsettings.update_extents(doc) zoom.center(doc.modelspace(), extents.center, extents.size) ``` **SEE ALSO:** - • the *ezdxf.bbox* module to understand the limitations of the extent calculation - • the *ezdxf.zoom* module ### Show Lineweight - **ezdxf.appsettings.show\_lineweight(doc: *Drawing*, state=True) -\> None** The CAD application or DXF viewer should show lines and curves with “thickness” (lineweight) if *state* is **True**. ### Load DXF Comments - **ezdxf.comments.from\_stream(stream: TextIO, codes: set\[int\] \| None = None) -\> Iterable\[*DXFTag*\]** Yields comment tags from text *stream* as *DXFTag* objects. - **Parameters** - • **stream** – input text stream - • **codes** – set of group codes to yield additional DXF tags e.g. {5, 0} to also yield handle and structure tags - **ezdxf.comments.from\_file(filename: str, codes: set\[int\] \| None = None) -\> Iterable\[*DXFTag*\]** Yields comment tags from file *filename* as *DXFTag* objects. - **Parameters** - • **filename** – filename as string - • **codes** – yields also additional tags with specified group codes e.g. {5, 0} to also yield handle and structure tags ### GfxAttribs The *ezdxf.gfxattribs* module provides the *GfxAttribs* class to create valid attribute dictionaries for the most often used DXF attributes supported by all graphical DXF entities. The advantage of using this class is auto-completion support by IDEs and an instant validation of the attribute values. ``` import ezdxf from ezdxf.gfxattribs import GfxAttribs doc = ezdxf.new() msp = doc.modelspace() attribs = GfxAttribs(layer="MyLayer", color=ezdxf.colors.RED) line = msp.add_line((0, 0), (1, 0), dxfattribs=attribs) circle = msp.add_circle((0, 0), radius=1.0, dxfattribs=attribs) # Update DXF attributes of existing entities: attribs = GfxAttribs(layer="MyLayer2", color=ezdxf.colors.BLUE) # Convert GfxAttribs() to dict(), but this method cannot reset # attributes to the default values like setting layer to "0". line.update_dxf_attribs(dict(attribs)) # Using GfxAttribs.asdict(default_values=True), can reset attributes to the # default values like setting layer to "0", except for true_color and # transparency, which do not have default values, their absence is the # default value. circle.update_dxf_attribs(attribs.asdict(default_values=True)) # Remove true_color and transparency by assigning None attribs.transparency = None # reset to transparency by layer! attribs.rgb = None ``` Validation features: - • **layer** - string which can not contain certain characters: **\<\>/\\":;?\*=\`** - • **color** - *AutoCAD Color Index (ACI)* value as integer in the range from 0 to 257 - • **rgb** - true color value as (red, green, blue) tuple, all channel values as integer values in the range from 0 to 255 - • **linetype** - string which can not contain certain characters: **\<\>/\\":;?\*=\`**, does not check if the linetype exists - • **lineweight** - integer value in the range from 0 to 211, see *Lineweights* for valid values - • **transparency** - float value in the range from 0.0 to 1.0 and -1.0 for transparency by block - • **ltscale** - float value \> 0.0 - **class ezdxf.gfxattribs.GfxAttribs(\*, layer: str = DEFAULT\_LAYER, color: int = DEFAULT\_ACI\_COLOR, rgb: *RGB* \| None = None, linetype: str = DEFAULT\_LINETYPE, lineweight: int = DEFAULT\_LINEWEIGHT, transparency: float \| None = None, ltscale: float = DEFAULT\_LTSCALE)** Represents often used DXF attributes of graphical entities. - **Parameters** - • **layer** (*str*) – layer name as string - • **color** (*int*) – *AutoCAD Color Index (ACI)* color value as integer - • **rgb** – RGB true color (red, green, blue) tuple, each channel value in the range from 0 to 255, **None** for not set - • **linetype** (*str*) – linetype name, does not check if the linetype exist! - • **lineweight** (*int*) – see *Lineweights* documentation for valid values - • **transparency** (*float*) – transparency value in the range from 0.0 to 1.0, where 0.0 is opaque and 1.0 if fully transparent, -1.0 for transparency by block, **None** for transparency by layer - • **ltscale** (*float*) – linetype scaling factor \> 0.0, default factor is 1.0 - **Raises** *DXFValueError* – invalid attribute value - **property layer: str** layer name - **property color: int** *AutoCAD Color Index (ACI)* color value - **property rgb: *RGB* \| None** true color value as (red, green, blue) tuple, **None** for not set - **property linetype: str** linetype name - **property lineweight: int** - **property transparency: float \| None** transparency value from 0.0 for opaque to 1.0 is fully transparent, -1.0 is for transparency by block and **None** if for transparency by layer - **property ltscale: float** linetype scaling factor - **\_\_str\_\_() -\> str** Return str(self). - **\_\_repr\_\_() -\> str** Return repr(self). - **\_\_iter\_\_() -\> Iterator\[tuple\[str, Any\]\]** Returns iter(self). - **asdict(default\_values=False) -\> dict\[str, Any\]** Returns the DXF attributes as **dict**, returns also the default values if argument *default\_values* is **True**. The true\_color and transparency attributes do not have default values, the absence of these attributes is the default value. - **items(default\_values=False) -\> list\[tuple\[str, Any\]\]** Returns the DXF attributes as list of name, value pairs, returns also the default values if argument *default\_values* is **True**. The true\_color and transparency attributes do not have default values, the absence of these attributes is the default value. - **classmethod load\_from\_header(doc: *Drawing*) -\> *GfxAttribs*** Load default DXF attributes from the HEADER section. There is no default true color value and the default transparency is not stored in the HEADER section. Loads following header variables: - • **$CLAYER** - current layer name - • **$CECOLOR** - current ACI color - • **$CELTYPE** - current linetype name - • **$CELWEIGHT** - current lineweight - • **$CELTSCALE** - current linetype scaling factor - **write\_to\_header(doc: *Drawing*) -\> None** Write DXF attributes as default values to the HEADER section. Writes following header variables: - • **$CLAYER** - current layer name, if a layer table entry exist in *doc* - • **$CECOLOR** - current ACI color - • **$CELTYPE** - current linetype name, if a linetype table entry exist in *doc* - • **$CELWEIGHT** - current lineweight - • **$CELTSCALE** - current linetype scaling factor - **classmethod from\_entity(entity: *DXFEntity*) -\> *GfxAttribs*** Get the graphical attributes of an *entity* as *GfxAttribs* object. - **classmethod from\_dict(d: dict\[str, Any\]) -\> *GfxAttribs*** Construct *GfxAttribs* from a dictionary of raw DXF values. Supported attributes are: - • layer: layer name as string - • color: *AutoCAD Color Index (ACI)* value as int - • true\_color: raw DXF integer value for RGB colors - • rgb: RGB tuple of int or **None** - • linetype: linetype name as string - • lineweight: lineweight as int, see basic concept of *Lineweights* - • transparency: raw DXF integer value of transparency or a float in the range from 0.0 to 1.0 - • ltscale: linetype scaling factor as float ### Query Module **SEE ALSO:** - • *Tutorial for Getting Data from DXF Files* - • Usage of extended query features: *Query Entities* ### The new() Function - **ezdxf.query.new(entities: Iterable\[DXFEntity\] \| None = None, query: str = '\*') -\> *EntityQuery*** Start a new query based on sequence *entities*. The *entities* argument has to be an iterable of *DXFEntity* or inherited objects and returns an *EntityQuery* object. ### Entity Query String ``` QueryString := EntityQuery ("[" AttribQuery "]" "i"?)* ``` The query string is the combination of two queries, first the required entity query and second the optional attribute query, enclosed in square brackets, append **'i'** after the closing square bracket to ignore case for strings. ### Entity Query The entity query is a whitespace separated list of DXF entity names or the special name **'\*'**. Where **'\*'** means all DXF entities, exclude some entity types by appending their names with a preceding **!** (e.g. all entities except LINE = **'\* !LINE'**). All DXF names have to be uppercase. ### Attribute Query The *optional* attribute query is a boolean expression, supported operators are: - • not (!): !term is true, if term is false - • and (&): term & term is true, if both terms are true - • or (\|): term \| term is true, if one term is true - • and arbitrary nested round brackets - • append (i) after the closing square bracket to ignore case for strings Attribute selection is a term: “name comparator value”, where name is a DXF entity attribute in lowercase, value is a integer, float or double quoted string, valid comparators are: - • **==** equal “value” - • **!=** not equal “value” - • **\<** lower than “value” - • **\<=** lower or equal than “value” - • **\>** greater than “value” - • **\>=** greater or equal than “value” - • **?** match regular expression “value” - • **!?** does not match regular expression “value” ### EntityQuery Class - **class ezdxf.query.EntityQuery** The *EntityQuery* class is a result container, which is filled with DXF entities matching the query string. It is possible to add entities to the container (extend), remove entities from the container and to filter the container. Supports the standard Python Sequence methods and protocols. Does not remove automatically destroyed entities (entities deleted by calling method **destroy()**), the method *purge()* has to be called explicitly to remove the destroyed entities. - **first** First entity or **None**. - **last** Last entity or **None**. - **\_\_len\_\_() -\> int** Returns count of DXF entities. - **\_\_getitem\_\_(item)** Returns DXFEntity at index *item*, supports negative indices and slicing. Returns all entities which support a specific DXF attribute, if *item* is a DXF attribute name as string. - **\_\_setitem\_\_(key, value)** Set the DXF attribute *key* for all supported DXF entities to *value*. - **\_\_delitem\_\_(key)** Discard the DXF attribute *key* from all supported DXF entities. - **\_\_eq\_\_(other)** Equal selector (self == other). Returns all entities where the selected DXF attribute is equal to *other*. - **\_\_ne\_\_(other)** Not equal selector (self != other). Returns all entities where the selected DXF attribute is not equal to *other*. - **\_\_lt\_\_(other)** Less than selector (self \< other). Returns all entities where the selected DXF attribute is less than *other*. - **Raises** **TypeError** – for vector based attributes like *center* or *insert* - **\_\_le\_\_(other)** Less equal selector (self \<= other). Returns all entities where the selected DXF attribute is less or equal *other*. - **Raises** **TypeError** – for vector based attributes like *center* or *insert* - **\_\_gt\_\_(other)** Greater than selector (self \> other). Returns all entities where the selected DXF attribute is greater than *other*. - **Raises** **TypeError** – for vector based attributes like *center* or *insert* - **\_\_ge\_\_(other)** Greater equal selector (self \>= other). Returns all entities where the selected DXF attribute is greater or equal *other*. - **Raises** **TypeError** – for vector based attributes like *center* or *insert* - **match(pattern: str) -\> *EntityQuery*** Returns all entities where the selected DXF attribute matches the regular expression *pattern*. - **Raises** **TypeError** – for non-string based attributes - **\_\_or\_\_(other)** Union operator, see *union()*. - **\_\_and\_\_(other)** Intersection operator, see *intersection()*. - **\_\_sub\_\_(other)** Difference operator, see *difference()*. - **\_\_xor\_\_(other)** Symmetric difference operator, see *symmetric\_difference()*. - **\_\_iter\_\_() -\> Iterator\[DXFEntity\]** Returns iterable of DXFEntity objects. - **purge() -\> *EntityQuery*** Remove destroyed entities. - **extend(entities: Iterable\[DXFEntity\], query: str = '\*') -\> *EntityQuery*** Extent the *EntityQuery* container by entities matching an additional query. - **remove(query: str = '\*') -\> *EntityQuery*** Remove all entities from *EntityQuery* container matching this additional query. - **query(query: str = '\*') -\> *EntityQuery*** Returns a new *EntityQuery* container with all entities matching this additional query. - **Raises** **pyparsing.ParseException** – query string parsing error - **groupby(dxfattrib: str = '', key: Callable\[\[DXFEntity\], Hashable\] \| None = None) -\> dict\[Hashable, list\[DXFEntity\]\]** Returns a dict of entity lists, where entities are grouped by a DXF attribute or a key function. - **Parameters** - • **dxfattrib** – grouping DXF attribute as string like **'layer'** - • **key** – key function, which accepts a DXFEntity as argument, returns grouping key of this entity or **None** for ignore this object. Reason for ignoring: a queried DXF attribute is not supported by this entity - **filter(func: Callable\[\[DXFEntity\], bool\]) -\> *EntityQuery*** Returns a new *EntityQuery* with all entities from this container for which the callable *func* returns **True**. Build your own operator to filter by attributes which are not DXF attributes or to build complex queries: ``` result = msp.query().filter( lambda e: hasattr(e, "rgb") and e.rbg == (0, 0, 0) ) ``` - **union(other: *EntityQuery*) -\> *EntityQuery*** Returns a new *EntityQuery* with entities from *self* and *other*. All entities are unique - no duplicates. - **intersection(other: *EntityQuery*) -\> *EntityQuery*** Returns a new *EntityQuery* with entities common to *self* and *other*. - **difference(other: *EntityQuery*) -\> *EntityQuery*** Returns a new *EntityQuery* with all entities from *self* that are not in *other*. - **symmetric\_difference(other: *EntityQuery*) -\> *EntityQuery*** Returns a new *EntityQuery* with entities in either *self* or *other* but not both. ### Revision Cloud The module *ezdxf.revcloud* provides functions to render revision clouds similar to the REVCLOUD command in CAD applications. Added in version 1.3.0. - **ezdxf.revcloud.points(vertices: Iterable\[*UVec*\], segment\_length: float, \*, bulge: float = REQUIRED\_BULGE, start\_width: float = 0.0, end\_width: float = 0.0) -\> list\[Sequence\[float\]\]** Returns the points for a *LWPolyline* entity to render a revision cloud, similar to the REVCLOUD command in CAD applications. - **Parameters** - • **vertices** – corner points of a polygon - • **segment\_length** – approximate segment length - • **bulge** – LWPOLYLINE bulge value - • **start\_width** – start width of the segment arc - • **end\_width** – end width of the segment arc, CAD applications use 0.1 \* segment\_length for a calligraphy effect - **ezdxf.revcloud.add\_entity(layout: *BaseLayout*, vertices: Iterable\[*UVec*\], segment\_length: float, \*, calligraphy=True, dxfattribs: Any = None) -\> *LWPolyline*** Adds a revision cloud as *LWPolyline* entity to *layout*, similar to the REVCLOUD command in CAD applications. - **Parameters** - • **layout** – target layout - • **vertices** – corner points of a polygon - • **segment\_length** – approximate segment length - • **calligraphy** – **True** for a calligraphy effect - • **dxfattribs** – additional DXF attributes - **ezdxf.revcloud.is\_revcloud(entity: DXFEntity) -\> bool** Returns **True** when the given entity represents a revision cloud. Usage: ``` import ezdxf from ezdxf.render import revcloud doc = ezdxf.new() msp = doc.modelspace() revcloud.add_entity(msp, [(0, 0), (1, 0), (1, 1), (0, 1)], segment_length=0.1) doc.saveas("revcloud.dxf") ``` \[image\] ### Text Tools ### MTextEditor - **class ezdxf.tools.text.MTextEditor(text: str = '')** The *MTextEditor* is a helper class to build MTEXT content strings with support for inline codes to change color, font or paragraph properties. The result is always accessible by the *text* attribute or the magic *\_\_str\_\_()* function as **str(MTextEditor("text"))**. All text building methods return *self* to implement a floating interface: ``` e = MTextEditor("This example ").color("red").append("switches color to red.") mtext = msp.add_mtext(str(e)) ``` The initial text height, color, text style and so on is determined by the DXF attributes of the *MText* entity. **WARNING:** The *MTextEditor* assembles just the inline code, which has to be parsed and rendered by the target CAD application, *ezdxf* has no influence to that result. Keep inline formatting as simple as possible, don’t test the limits of its capabilities, this will not work across different CAD applications and keep the formatting in a logic manner like, do not change paragraph properties in the middle of a paragraph. **There is no official documentation for the inline codes!** - **Parameters** **text** – init value of the MTEXT content string. - **text** The MTEXT content as a simple string. - **append(text: str) -\> *MTextEditor*** Append *text*. - **\_\_iadd\_\_(text: str) -\> *MTextEditor*** Append *text*: ``` e = MTextEditor("First paragraph.\P") e += "Second paragraph.\P") ``` - **\_\_str\_\_() -\> str** Returns the MTEXT content attribute *text*. - **clear()** Reset the content to an empty string. - **font(name: str, bold: bool = False, italic: bool = False) -\> *MTextEditor*** Set the text font by the font family name. Changing the font height should be done by the *height()* or the *scale\_height()* method. The font family name is the name shown in font selection widgets in desktop applications: “Arial”, “Times New Roman”, “Comic Sans MS”. Switching the codepage is not supported. - **Parameters** - • **name** – font family name - • **bold** – flag - • **italic** – flag - **height(height: float) -\> *MTextEditor*** Set the absolute text height in drawing units. - **scale\_height(factor: float) -\> *MTextEditor*** Scale the text height by a *factor*. This scaling will accumulate, which means starting at height 2.5 and scaling by 2 and again by 3 will set the text height to 2.5 x 2 x 3 = 15. The current text height is not stored in the *MTextEditor*, you have to track the text height by yourself! The initial text height is stored in the *MText* entity as DXF attribute *char\_height*. - **width\_factor(factor: float) -\> *MTextEditor*** Set the absolute text width factor. - **char\_tracking\_factor(factor: float) -\> *MTextEditor*** Set the absolute character tracking factor. - **oblique(angle: int) -\> *MTextEditor*** Set the text oblique angle in degrees, vertical is 0, a value of 15 will lean the text 15 degree to the right. - **color(name: str) -\> *MTextEditor*** Set the text color by color name: “red”, “yellow”, “green”, “cyan”, “blue”, “magenta” or “white”. - **aci(aci: int) -\> *MTextEditor*** Set the text color by *AutoCAD Color Index (ACI)* in range \[0, 256\]. - **rgb(rgb: *RGB*) -\> *MTextEditor*** Set the text color as RGB value. - **underline(text: str) -\> *MTextEditor*** Append *text* with a line below the text. - **overline(text: str) -\> *MTextEditor*** Append *text* with a line above the text. - **strike\_through(text: str) -\> *MTextEditor*** Append *text* with a line through the text. - **group(text: str) -\> *MTextEditor*** Group *text*, all properties changed inside a group are reverted at the end of the group. AutoCAD supports grouping up to 8 levels. - **stack(upr: str, lwr: str, t: str = '^') -\> *MTextEditor*** Append stacked text *upr* over *lwr*, argument *t* defines the kind of stacking, the space “ “ after the “^” will be added automatically to avoid caret decoding: ``` "^": vertical stacked without divider line, e.g. \SA^ B: A B "/": vertical stacked with divider line, e.g. \SX/Y: X - Y "#": diagonal stacked, with slanting divider line, e.g. \S1#4: 1/4 ``` - **paragraph(props: *ParagraphProperties*) -\> *MTextEditor*** Set paragraph properties by a *ParagraphProperties* object. - **bullet\_list(indent: float, bullets: Iterable\[str\], content: Iterable\[str\]) -\> *MTextEditor*** Build bulleted lists by utilizing paragraph indentation and a tabulator stop. Any string can be used as bullet. Indentation is a multiple of the initial MTEXT char height (see also docs about *ParagraphProperties*), which means indentation in drawing units is **MText.dxf.char\_height** x *indent*. Useful UTF bullets: - • “bull” U+2022 = • (Alt Numpad 7) - • “circle” U+25CB = ○ (Alt Numpad 9) For numbered lists just use numbers as bullets: ``` MTextEditor.bullet_list( indent=2, bullets=["1.", "2."], content=["first", "second"], ) ``` - **Parameters** - • **indent** – content indentation as multiple of the initial MTEXT char height - • **bullets** – iterable of bullet strings, e.g. **\["-"\] \* 3**, for 3 dashes as bullet strings - • **content** – iterable of list item strings, one string per list item, list items should not contain new line or new paragraph commands. Constants stored in the *MTextEditor* class: | | | | --- | --- | | NEW\_LINE | **'\\P'** | | NEW\_PARAGRAPH | **'\\P'** | | NEW\_COLUMN | **'\\N** | | UNDERLINE\_START | **'\\L'** | | UNDERLINE\_STOP | **'\\l'** | | OVERSTRIKE\_START | **'\\O'** | | OVERSTRIKE\_STOP | **'\\o'** | | STRIKE\_START | **'\\K'** | | STRIKE\_STOP | **'\\k'** | | ALIGN\_BOTTOM | **'\\A0;'** | | ALIGN\_MIDDLE | **'\\A1;'** | | ALIGN\_TOP | **'\\A2;'** | | NBSP | **'\\~'** | | TAB | **'^I'** | - **class ezdxf.tools.text.ParagraphProperties(indent=0, left=0, right=0, align=DEFAULT, tab\_stops=\[\])** Stores all known MTEXT paragraph properties in a **NamedTuple**. Indentations and tab stops are multiples of the default text height **MText.dxf.char\_height**. E.g. **char\_height** is 0.25 and **indent** is 4, the real indentation is 4 x 0.25 = 1 drawing unit. The default tabulator stops are 4, 8, 12, … if no tabulator stops are explicit defined. - **Parameters** - • **indent** (*float*) – left indentation of the first line, relative to **left**, which means an **indent** of 0 has always the same indentation as **left** - • **left** (*float*) – left indentation of the paragraph except for the first line - • **right** (*float*) – left indentation of the paragraph - • **align** – *MTextParagraphAlignment* enum - • **tab\_stops** – tuple of tabulator stops, as **float** or as **str**, **float** values are left aligned tab stops, strings with prefix **"c"** are center aligned tab stops and strings with prefix **"r"** are right aligned tab stops - **tostring() -\> str** Returns the MTEXT paragraph properties as MTEXT inline code e.g. **"\\pxi-2,l2;"**. - **class ezdxf.lldxf.const.MTextParagraphAlignment** - **DEFAULT** - **LEFT** - **RIGHT** - **CENTER** - **JUSTIFIED** - **DISTRIBUTED** ### Single Line Text - **class ezdxf.tools.text.TextLine(text: str, font: *fonts.AbstractFont*)** Helper class which represents a single line text entity (e.g. *Text*). - **Parameters** - • **text** – content string - • **font** – ezdxf font definition like *MonospaceFont* or *TrueTypeFont* - **property width: float** Returns the final (stretched) text width. - **property height: float** Returns the final (stretched) text height. - **stretch(alignment: *TextEntityAlignment*, p1: *Vec3*, p2: *Vec3*) -\> None** Set stretch factors for FIT and ALIGNED alignments to fit the text between *p1* and *p2*, only the distance between these points is important. Other given *alignment* values are ignore. - **font\_measurements() -\> *fonts.FontMeasurements*** Returns the scaled font measurements. - **baseline\_vertices(insert: *UVec*, halign: int = 0, valign: int = 0, angle: float = 0, scale: tuple\[float, float\] = (1, 1)) -\> list\[*Vec3*\]** Returns the left and the right baseline vertex of the text line. - **Parameters** - • **insert** – insertion location - • **halign** – horizontal alignment left=0, center=1, right=2 - • **valign** – vertical alignment baseline=0, bottom=1, middle=2, top=3 - • **angle** – text rotation in radians - • **scale** – scale in x- and y-axis as 2-tuple of float - **corner\_vertices(insert: *UVec*, halign: int = 0, valign: int = 0, angle: float = 0, scale: tuple\[float, float\] = (1, 1), oblique: float = 0) -\> list\[*Vec3*\]** Returns the corner vertices of the text line in the order bottom left, bottom right, top right, top left. - **Parameters** - • **insert** – insertion location - • **halign** – horizontal alignment left=0, center=1, right=2 - • **valign** – vertical alignment baseline=0, bottom=1, middle=2, top=3 - • **angle** – text rotation in radians - • **scale** – scale in x- and y-axis as 2-tuple of float - • **oblique** – shear angle (slanting) in x-direction in radians - **static transform\_2d(vertices: Iterable\[*UVec*\], insert: *UVec* = Vec3(0, 0, 0), shift: tuple\[float, float\] = (0, 0), rotation: float = 0, scale: tuple\[float, float\] = (1, 1), oblique: float = 0) -\> list\[*Vec3*\]** Transform any vertices from the text line located at the base location at (0, 0) and alignment LEFT. - **Parameters** - • **vertices** – iterable of vertices - • **insert** – insertion location - • **shift** – (shift-x, shift-y) as 2-tuple of float - • **rotation** – text rotation in radians - • **scale** – (scale-x, scale-y) as 2-tuple of float - • **oblique** – shear angle (slanting) in x-direction in radians ### Functions - **ezdxf.tools.text.caret\_decode(text: str) -\> str** DXF stores some special characters using caret notation. This function decodes this notation to normalize the representation of special characters in the string. see: *https://en.wikipedia.org/wiki/Caret\_notation* - **ezdxf.tools.text.estimate\_mtext\_content\_extents(content: str, font: *fonts.AbstractFont*, column\_width: float = 0.0, line\_spacing\_factor: float = 1.0) -\> tuple\[float, float\]** Estimate the width and height of the *MText* content string. The result is very inaccurate if inline codes are used or line wrapping at the column border is involved! Column breaks **\\N** will be ignored. - **Parameters** - • **content** – the *MText* content string - • **font** – font abstraction based on **ezdxf.tools.fonts.AbstractFont** - • **column\_width** – **MText.dxf.width** or 0.0 for an unrestricted column width - • **line\_spacing\_factor** – **MText.dxf.line\_spacing\_factor** - **Returns** tuple\[width, height\] - **ezdxf.tools.text.estimate\_mtext\_extents(mtext: *MText*) -\> tuple\[float, float\]** Estimate the width and height of a single column *MText* entity. This function is faster than the *mtext\_size()* function, but the result is very inaccurate if inline codes are used or line wrapping at the column border is involved! - **Returns** Tuple\[width, height\] - **ezdxf.tools.text.fast\_plain\_mtext(text: str, split=False) -\> list\[str\] \| str** Returns the plain MTEXT content as a single string or a list of strings if *split* is **True**. Replaces **\\P** by **\\n** and removes other controls chars and inline codes. This function is more than 4x faster than *plain\_mtext()*, but does not remove single letter inline commands with arguments without a terminating semicolon like this **"\\C1red text"**. **NOTE:** Well behaved CAD applications and libraries always create inline codes for commands with arguments with a terminating semicolon like this **"\\C1;red text"**! - **Parameters** - • **text** – MTEXT content string - • **split** – split content at line endings **\\P** - **ezdxf.tools.text.is\_text\_vertical\_stacked(text: *DXFEntity*) -\> bool** Returns **True** if the associated text *Textstyle* is vertical stacked. - **ezdxf.tools.text.is\_upside\_down\_text\_angle(angle: float, tol: float = 3.0) -\> bool** Returns **True** if the given text *angle* in degrees causes an upside down text in the *WCS*. The strict flip range is 90° \< *angle* \< 270°, the tolerance angle *tol* extends this range to: 90+tol \< *angle* \< 270-tol. The angle is normalized to \[0, 360). - **Parameters** - • **angle** – text angle in degrees - • **tol** – tolerance range in which text flipping will be avoided - **ezdxf.tools.text.leading(cap\_height: float, line\_spacing: float = 1.0) -\> float** Returns the distance from baseline to baseline. - **Parameters** - • **cap\_height** – cap height of the line - • **line\_spacing** – line spacing factor as percentage of 3-on-5 spacing - **ezdxf.tools.text.plain\_mtext(text: str, split=False, tabsize: int = 4) -\> list\[str\] \| str** Returns the plain MTEXT content as a single string or a list of strings if *split* is **True**. Replaces **\\P** by **\\n** and removes other controls chars and inline codes. This function is much slower than *fast\_plain\_mtext()*, but removes all inline codes. - **Parameters** - • **text** – MTEXT content string - • **split** – split content at line endings **\\P** - • **tabsize** – count of replacement spaces for tabulators **^I** - **ezdxf.tools.text.plain\_text(text: str) -\> str** Returns the plain text for *Text*, *Attrib* and **Attdef** content. - **ezdxf.tools.text.safe\_string(s: str \| None, max\_len: int = MAX\_STR\_LEN) -\> str** Returns a string with line breaks **\\n** replaced by **\\P** and the length limited to *max\_len*. - **ezdxf.tools.text.text\_wrap(text: str, box\_width: float \| None, get\_text\_width: Callable\[\[str\], float\]) -\> list\[str\]** Wrap text at **\\n** and given *box\_width*. This tool was developed for usage with the MTEXT entity. This isn’t the most straightforward word wrapping algorithm, but it aims to match the behavior of AutoCAD. - **Parameters** - • **text** – text to wrap, included **\\n** are handled as manual line breaks - • **box\_width** – wrapping length, **None** to just wrap at **\\n** - • **get\_text\_width** – callable which returns the width of the given string - **ezdxf.tools.text.upright\_text\_angle(angle: float, tol: float = 3.0) -\> float** Returns a readable (upright) text angle in the range *angle* \<= 90+tol or *angle* \>= 270-tol. The angle is normalized to \[0, 360). - **Parameters** - • **angle** – text angle in degrees - • **tol** – tolerance range in which text flipping will be avoided ### Text Size Tools - **class ezdxf.tools.text\_size.TextSize** A frozen dataclass as return type for the *text\_size()* function. - **width** The text width in drawing units (float). - **cap\_height** The font cap-height in drawing units (float). - **total\_height** The font total-height = cap-height + descender-height in drawing units (float). - **ezdxf.tools.text\_size.text\_size(text: Text) -\> *TextSize*** Returns the measured text width, the font cap-height and the font total-height for a *Text* entity. This function uses the optional *Matplotlib* package if available to measure the final rendering width and font-height for the **Text** entity as close as possible. This function does not measure the real char height! Without access to the *Matplotlib* package the **MonospaceFont** is used and the measurements are very inaccurate. See the *text2path* add-on for more tools to work with the text path objects created by the *Matplotlib* package. - **class ezdxf.tools.text\_size.MTextSize** A frozen dataclass as return type for the *mtext\_size()* function. - **total\_width** The total width in drawing units (float) - **total\_height** The total height in drawing units (float), same as **max(column\_heights)**. - **column\_width** The width of a single column in drawing units (float) - **gutter\_width** The space between columns in drawing units (float) - **column\_heights** A tuple of columns heights (float) in drawing units. Contains at least one column height and the column height is 0 for an empty column. - **column\_count** The count of columns (int). - **ezdxf.tools.text\_size.mtext\_size(mtext: MText, tool: MTextSizeDetector \| None = None) -\> *MTextSize*** Returns the total-width, -height and columns information for a *MText* entity. This function uses the optional *Matplotlib* package if available to do font measurements and the internal text layout engine to determine the final rendering size for the **MText** entity as close as possible. Without access to the *Matplotlib* package the **MonospaceFont** is used and the measurements are very inaccurate. Attention: The required full layout calculation is slow! The first call to this function with *Matplotlib* support is very slow, because *Matplotlib* lookup all available fonts on the system. To speedup the calculation and accepting inaccurate results you can disable the *Matplotlib* support manually: ``` ezdxf.option.use_matplotlib = False ``` - **ezdxf.tools.text\_size.estimate\_mtext\_extents(mtext: *MText*) -\> tuple\[float, float\]** Estimate the width and height of a single column *MText* entity. This function is faster than the *mtext\_size()* function, but the result is very inaccurate if inline codes are used or line wrapping at the column border is involved! - **Returns** Tuple\[width, height\] ### XClip Module Added in version 1.2. The *XClip* class can set or remove the clipping path of external references or block references. The clipping boundary determines the portion of an XREF or block instance that is hidden, either outside or inside the boundary (inside = inverted clipping path). The visibility of the clipping boundary is controlled by the $XCLIPFRAME header variable. The *XClip* class supports only 2D clippings path and cannot create inverted clipping paths. \[image\] There exist two coordinate systems for the clipping path polygon: - • BLOCK coordinate system: the BLOCK coordinates are relative to the BLOCK origin - • WCS coordinate system: the WCS coordinates are relative to the origin of the of the coodintate system where the block reference (INSERT entity) is inserted The *XClip* class provides methods to set and get the clipping path for both variants and returns a *ClippingPath* object. The clipping polygon can be set visible/invisible when the header variable $XCLIPFRAME is not 0, otherwise the clipping polygon is always invisible. Remove the clipping path by the *XClip.discard\_clipping\_path()* method, does not raise an exception when no clipping path exist. **SEE ALSO:** example script: *clipping\_insert.py* in the **/examples/blocks** folder - **class ezdxf.xclip.XClip(insert: Insert)** Helper class to manage the clipping path of INSERT entities. Provides a similar functionality as the XCLIP command in CAD applications. **IMPORTANT:** This class handles only 2D clipping paths. The visibility of the clipping path can be set individually for each block reference, but the HEADER variable $XCLIPFRAME ultimately determines whether the clipping path is displayed or plotted by the application: | | | | | --- | --- | --- | | 0 | not displayed | not plotted | | 1 | displayed | not plotted | | 2 | displayed | plotted | The default setting is 2. - **property has\_clipping\_path: bool** Returns if the INSERT entity has a clipping path. - **property is\_clipping\_enabled: bool** Returns **True** if block reference clipping is enabled. - **property is\_inverted\_clip: bool** Returns **True** if clipping path is inverted. - **disable\_clipping() -\> None** Disable block reference clipping. - **enable\_clipping() -\> None** Enable block reference clipping. - **get\_spatial\_filter() -\> SpatialFilter \| None** Returns the underlaying SPATIAL\_FILTER entity if the INSERT entity has a clipping path and returns **None** otherwise. - **get\_xclip\_frame\_policy() -\> int** - **get\_block\_clipping\_path() -\> *ClippingPath*** Returns the clipping path in block coordinates (relative to the block origin). - **get\_wcs\_clipping\_path() -\> *ClippingPath*** Returns the clipping path in WCS coordinates (relative to the WCS origin) as 2D path projected onto the xy-plane. - **set\_block\_clipping\_path(vertices: Iterable\[*UVec*\]) -\> None** Set clipping path in block coordinates (relative to block origin). The clipping path is located in the xy-plane, the z-axis of all vertices will be ignored. The clipping path doesn’t have to be closed (first vertex != last vertex). Two vertices define a rectangle where the sides are parallel to x- and y-axis. - **Raises** *DXFValueError* – clipping path has less than two vertrices - **set\_wcs\_clipping\_path(vertices: Iterable\[*UVec*\]) -\> None** Set clipping path in WCS coordinates (relative to WCS origin). The clipping path is located in the xy-plane, the z-axis of all vertices will be ignored. The clipping path doesn’t have to be closed (first vertex != last vertex). Two vertices define a rectangle where the sides are parallel to x- and y-axis. - **Raises** - • *DXFValueError* – clipping path has less than two vertrices - • **ZeroDivisionError** – Block reference transformation matrix is not invertible - **discard\_clipping\_path() -\> None** Delete the clipping path. The clipping path doesn’t have to exist. This method does not discard the extension dictionary of the base entity, even when its empty. - **class ezdxf.xclip.ClippingPath(vertices: Sequence\[*Vec2*\] = (), inverted\_clip: Sequence\[*Vec2*\] = (), inverted\_clip\_compare: Sequence\[*Vec2*\] = (), is\_inverted\_clip: bool = False)** Stores the SPATIAL\_FILTER clipping paths in original form that I still don’t fully understand for *inverted* clipping paths. All boundary paths are simple polygons as a sequence of *Vec2*. - **vertices** Contains the boundary polygon for regular clipping paths. Contains the outer boundary path for inverted clippings paths - but not always! - **Type** Sequence\[*ezdxf.math.\_vector.Vec2*\] - **inverted\_clip** Contains the inner boundary for inverted clipping paths - but not always! - **Type** Sequence\[*ezdxf.math.\_vector.Vec2*\] - **inverted\_clip\_compare** Contains the combined inner- and the outer boundaries for inverted clipping paths - but not always! - **Type** Sequence\[*ezdxf.math.\_vector.Vec2*\] - **is\_inverted\_clip** **True** for inverted clipping paths - **Type** bool ### Zoom Layouts These functions mimic the ZOOM commands in CAD applications. Zooming means resetting the current viewport limits to new values. The coordinates for the functions *center()* and *window()* are drawing units for the model space and paper space units for paper space layouts. The modelspace units in **Drawing.units** are ignored. The extents detection for the functions **entities()** and *extents()* is done by the *ezdxf.bbox* module. Read the associated documentation to understand the limitations of the *ezdxf.bbox* module. Tl;dr The extents detection is **slow** and **not accurate**. Because the ZOOM operations in CAD applications are not that precise, then zoom functions of this module uses the fast bounding box calculation mode of the **bbox** module, which means the argument *flatten* is always **False** for *extents()* function calls. The region displayed by CAD applications also depends on the aspect ratio of the application window, which is not available to *ezdxf*, therefore the viewport size is just an educated guess of an aspect ratio of 2:1 (16:9 minus top toolbars and the bottom status bar). **WARNING:** All zoom functions replace the current viewport configuration by a single window configuration. Example to reset the main CAD viewport of the model space to the extents of its entities: ``` import ezdxf from ezdxf import zoom doc = ezdxf.new() msp = doc.modelspace() ... # add your DXF entities zoom.extents(msp) doc.saveas("your.dxf") ``` - **ezdxf.zoom.center(layout: Layout, point: Sequence\[float\] \| *Vec2* \| *Vec3*, size: Sequence\[float\] \| *Vec2* \| *Vec3*)** Resets the active viewport center of *layout* to the given *point*, argument *size* defines the width and height of the viewport. Replaces the current viewport configuration by a single window configuration. - **ezdxf.zoom.objects(layout: Layout, entities: Iterable\[DXFEntity\], factor: float = 1)** Resets the active viewport limits of *layout* to the extents of the given *entities*. Only entities in the given *layout* are taken into account. The argument *factor* scales the viewport limits. Replaces the current viewport configuration by a single window configuration. - **ezdxf.zoom.extents(layout: Layout, factor: float = 1)** Resets the active viewport limits of *layout* to the extents of all entities in this *layout*. The argument *factor* scales the viewport limits. Replaces the current viewport configuration by a single window configuration. - **ezdxf.zoom.window(layout: Layout, p1: Sequence\[float\] \| *Vec2* \| *Vec3*, p2: Sequence\[float\] \| *Vec2* \| *Vec3*)** Resets the active viewport limits of *layout* to the lower left corner *p1* and the upper right corner *p2*. Replaces the current viewport configuration by a single window configuration. ### Render Tools The *ezdxf.render* subpackage provides helpful utilities to create complex forms. - • create complex meshes as *Mesh* entity. - • render complex curves like bezier curves, euler spirals or splines as *Polyline* entity - • vertex generators for simple and complex forms like circle, ellipse or euler spiral Content ### Spline - **class ezdxf.render.Spline(points: Iterable\[*UVec*\] \| None = None, segments: int = 100)** This class can be used to render B-splines into DXF R12 files as approximated *Polyline* entities. The advantage of this class over the *R12Spline* class is, that this is a real 3D curve, which means that the B-spline vertices do have to be located in a flat plane, and no *UCS* class is needed to place the curve in 3D space. **SEE ALSO:** The newer *BSpline* class provides the advanced vertex interpolation method *flattening()*. - **\_\_init\_\_(points: Iterable\[*UVec*\] \| None = None, segments: int = 100)** - **Parameters** - • **points** – spline definition points - • **segments** – count of line segments for approximation, vertex count is *segments* + 1 - **subdivide(segments: int = 4) -\> None** Calculate overall segment count, where segments is the sub-segment count, *segments* = 4, means 4 line segments between two definition points e.g. 4 definition points and 4 segments = 12 overall segments, useful for fit point rendering. - **Parameters** **segments** – sub-segments count between two definition points - **render\_as\_fit\_points(layout: *BaseLayout*, degree: int = 3, method: str = 'chord', dxfattribs: dict \| None = None) -\> None** Render a B-spline as 2D/3D *Polyline*, where the definition points are fit points. - • 2D spline vertices uses: *add\_polyline2d()* - • 3D spline vertices uses: *add\_polyline3d()* - **Parameters** - • **layout** – *BaseLayout* object - • **degree** – degree of B-spline (order = *degree* + 1) - • **method** – “uniform”, “distance”/”chord”, “centripetal”/”sqrt\_chord” or “arc” calculation method for parameter t - • **dxfattribs** – DXF attributes for *Polyline* - **render\_open\_bspline(layout: *BaseLayout*, degree: int = 3, dxfattribs=None) -\> None** Render an open uniform B-spline as 3D *Polyline*. Definition points are control points. - **Parameters** - • **layout** – *BaseLayout* object - • **degree** – degree of B-spline (order = *degree* + 1) - • **dxfattribs** – DXF attributes for *Polyline* - **render\_uniform\_bspline(layout: *BaseLayout*, degree: int = 3, dxfattribs=None) -\> None** Render a uniform B-spline as 3D *Polyline*. Definition points are control points. - **Parameters** - • **layout** – *BaseLayout* object - • **degree** – degree of B-spline (order = *degree* + 1) - • **dxfattribs** – DXF attributes for *Polyline* - **render\_closed\_bspline(layout: *BaseLayout*, degree: int = 3, dxfattribs=None) -\> None** Render a closed uniform B-spline as 3D *Polyline*. Definition points are control points. - **Parameters** - • **layout** – *BaseLayout* object - • **degree** – degree of B-spline (order = *degree* + 1) - • **dxfattribs** – DXF attributes for *Polyline* - **render\_open\_rbspline(layout: *BaseLayout*, weights: Iterable\[float\], degree: int = 3, dxfattribs=None) -\> None** Render a rational open uniform BSpline as 3D *Polyline*. Definition points are control points. - **Parameters** - • **layout** – *BaseLayout* object - • **weights** – list of weights, requires a weight value (float) for each definition point. - • **degree** – degree of B-spline (order = *degree* + 1) - • **dxfattribs** – DXF attributes for *Polyline* - **render\_uniform\_rbspline(layout: *BaseLayout*, weights: Iterable\[float\], degree: int = 3, dxfattribs=None) -\> None** Render a rational uniform B-spline as 3D *Polyline*. Definition points are control points. - **Parameters** - • **layout** – *BaseLayout* object - • **weights** – list of weights, requires a weight value (float) for each definition point. - • **degree** – degree of B-spline (order = *degree* + 1) - • **dxfattribs** – DXF attributes for *Polyline* - **render\_closed\_rbspline(layout: *BaseLayout*, weights: Iterable\[float\], degree: int = 3, dxfattribs=None) -\> None** Render a rational B-spline as 3D *Polyline*. Definition points are control points. - **Parameters** - • **layout** – *BaseLayout* object - • **weights** – list of weights, requires a weight value (float) for each definition point. - • **degree** – degree of B-spline (order = *degree* + 1) - • **dxfattribs** – DXF attributes for *Polyline* ### R12Spline - **class ezdxf.render.R12Spline(control\_points: Iterable\[*UVec*\], degree: int = 2, closed: bool = True)** DXF R12 supports 2D B-splines, but Autodesk do not document the usage in the DXF Reference. The base entity for splines in DXF R12 is the POLYLINE entity. The spline itself is always in a plane, but as any 2D entity, the spline can be transformed into the 3D object by elevation and extrusion (*OCS*, *UCS*). This way it was possible to store the spline parameters in the DXF R12 file, to allow CAD applications to modify the spline parameters and rerender the B-spline afterward again as polyline approximation. Therefore, the result is not better than an approximation by the *Spline* class, it is also just a POLYLINE entity, but maybe someone need exact this tool in the future. - **\_\_init\_\_(control\_points: Iterable\[*UVec*\], degree: int = 2, closed: bool = True)** - **Parameters** - • **control\_points** – B-spline control frame vertices - • **degree** – degree of B-spline, only 2 and 3 is supported - • **closed** – **True** for closed curve - **render(layout: *BaseLayout*, segments: int = 40, ucs: *UCS* \| None = None, dxfattribs=None) -\> *Polyline*** Renders the B-spline into *layout* as 2D *Polyline* entity. Use an *UCS* to place the 2D spline in the 3D space, see *approximate()* for more information. - **Parameters** - • **layout** – *BaseLayout* object - • **segments** – count of line segments for approximation, vertex count is *segments* + 1 - • **ucs** – *UCS* definition, control points in ucs coordinates. - • **dxfattribs** – DXF attributes for *Polyline* - **approximate(segments: int = 40, ucs: *UCS* \| None = None) -\> list\[*UVec*\]** Approximate the B-spline by a polyline with *segments* line segments. If *ucs* is not **None**, ucs defines an *UCS*, to transform the curve into *OCS*. The control points are placed xy-plane of the UCS, don’t use z-axis coordinates, if so make sure all control points are in a plane parallel to the OCS base plane (UCS xy-plane), else the result is unpredictable and depends on the CAD application used to open the DXF file - it may crash. - **Parameters** - • **segments** – count of line segments for approximation, vertex count is *segments* + 1 - • **ucs** – *UCS* definition, control points in ucs coordinates - **Returns** list of vertices in *OCS* as *Vec3* objects ### Bezier - **class ezdxf.render.Bezier** Render a bezier curve as 2D/3D *Polyline*. The *Bezier* class is implemented with multiple segments, each segment is an optimized 4 point bezier curve, the 4 control points of the curve are: the start point (1) and the end point (4), point (2) is start point + start vector and point (3) is end point + end vector. Each segment has its own approximation count. **SEE ALSO:** The new *ezdxf.path* package provides many advanced construction tools based on the *Path* class. - **start(point: *UVec*, tangent: *UVec*) -\> None** Set start point and start tangent. - **Parameters** - • **point** – start point - • **tangent** – start tangent as vector, example: (5, 0, 0) means a horizontal tangent with a length of 5 drawing units - **append(point: *UVec*, tangent1: *UVec*, tangent2: *UVec* \| None = None, segments: int = 20)** Append a control point with two control tangents. - **Parameters** - • **point** – control point - • **tangent1** – first tangent as vector “left” of the control point - • **tangent2** – second tangent as vector “right” of the control point, if omitted *tangent2* = *-tangent1* - • **segments** – count of line segments for the polyline approximation, count of line segments from the previous control point to the appended control point. - **render(layout: *BaseLayout*, force3d: bool = False, dxfattribs=None) -\> None** Render Bezier curve as 2D/3D *Polyline*. - **Parameters** - • **layout** – *BaseLayout* object - • **force3d** – force 3D polyline rendering - • **dxfattribs** – DXF attributes for *Polyline* ### EulerSpiral - **class ezdxf.render.EulerSpiral(curvature: float = 1)** Render an *euler spiral* as a 3D *Polyline* or a *Spline* entity. This is a parametric curve, which always starts at the origin (0, 0). - **\_\_init\_\_(curvature: float = 1)** - **Parameters** **curvature** – Radius of curvature - **render\_polyline(layout: *BaseLayout*, length: float = 1, segments: int = 100, matrix: *Matrix44* \| None = None, dxfattribs=None)** Render curve as *Polyline*. - **Parameters** - • **layout** – *BaseLayout* object - • **length** – length measured along the spiral curve from its initial position - • **segments** – count of line segments to use, vertex count is *segments* + 1 - • **matrix** – transformation matrix as *Matrix44* - • **dxfattribs** – DXF attributes for *Polyline* - **Returns** *Polyline* - **render\_spline(layout: *BaseLayout*, length: float = 1, fit\_points: int = 10, degree: int = 3, matrix: *Matrix44* \| None = None, dxfattribs=None)** Render curve as *Spline*. - **Parameters** - • **layout** – *BaseLayout* object - • **length** – length measured along the spiral curve from its initial position - • **fit\_points** – count of spline fit points to use - • **degree** – degree of B-spline - • **matrix** – transformation matrix as *Matrix44* - • **dxfattribs** – DXF attributes for *Spline* - **Returns** *Spline* ### Random Paths Random path generators for testing purpose. - **ezdxf.render.random\_2d\_path(steps: int = 100, max\_step\_size: float = 1.0, max\_heading: float = math.pi / 2, retarget: int = 20) -\> Iterable\[*Vec2*\]** Returns a random 2D path as iterable of *Vec2* objects. - **Parameters** - • **steps** – count of vertices to generate - • **max\_step\_size** – max step size - • **max\_heading** – limit heading angle change per step to ± max\_heading/2 in radians - • **retarget** – specifies steps before changing global walking target - **ezdxf.render.random\_3d\_path(steps: int = 100, max\_step\_size: float = 1.0, max\_heading: float = math.pi / 2.0, max\_pitch: float = math.pi / 8.0, retarget: int = 20) -\> Iterable\[*Vec3*\]** Returns a random 3D path as iterable of *Vec3* objects. - **Parameters** - • **steps** – count of vertices to generate - • **max\_step\_size** – max step size - • **max\_heading** – limit heading angle change per step to ± max\_heading/2, rotation about the z-axis in radians - • **max\_pitch** – limit pitch angle change per step to ± max\_pitch/2, rotation about the x-axis in radians - • **retarget** – specifies steps before changing global walking target ### Forms This module provides functions to create 2D and 3D forms as vertices or mesh objects. 2D Forms - • *box()* - • *circle()* - • *ellipse()* - • *euler\_spiral()* - • *gear()* - • *ngon()* - • *square()* - • *star()* - • *turtle()* 3D Forms - • *cone\_2p()* - • *cone()* - • *cube()* - • *cylinder()* - • *cylinder\_2p()* - • *helix()* - • *sphere()* - • *torus()* 3D Form Builder - • *extrude()* - • *extrude\_twist\_scale()* - • *from\_profiles\_linear()* - • *from\_profiles\_spline()* - • *rotation\_form()* - • *sweep()* - • *sweep\_profile()* ### 2D Forms Basic 2D shapes as iterable of *Vec3*. - **ezdxf.render.forms.box(sx: float = 1.0, sy: float = 1.0, center=False) -\> tuple\[*Vec3*, *Vec3*, *Vec3*, *Vec3*\]** Returns 4 vertices for a box with a width of *sx* by and a height of *sy*. The center of the box in (0, 0) if *center* is **True** otherwise the lower left corner is (0, 0), upper right corner is (*sx*, *sy*). - **ezdxf.render.forms.circle(count: int, radius: float = 1, elevation: float = 0, close: bool = False) -\> Iterable\[*Vec3*\]** Create polygon vertices for a *circle* with the given *radius* and approximated by *count* vertices, *elevation* is the z-axis for all vertices. - **Parameters** - • **count** – count of polygon vertices - • **radius** – circle radius - • **elevation** – z-axis for all vertices - • **close** – yields first vertex also as last vertex if **True**. - **Returns** vertices in counter-clockwise orientation as *Vec3* objects - **ezdxf.render.forms.ellipse(count: int, rx: float = 1, ry: float = 1, start\_param: float = 0, end\_param: float = math.tau, elevation: float = 0) -\> Iterable\[*Vec3*\]** Create polygon vertices for an *ellipse* with given *rx* as x-axis radius and *ry* as y-axis radius approximated by *count* vertices, *elevation* is the z-axis for all vertices. The ellipse goes from *start\_param* to *end\_param* in counter clockwise orientation. - **Parameters** - • **count** – count of polygon vertices - • **rx** – ellipse x-axis radius - • **ry** – ellipse y-axis radius - • **start\_param** – start of ellipse in range \[0, 2π\] - • **end\_param** – end of ellipse in range \[0, 2π\] - • **elevation** – z-axis for all vertices - **Returns** vertices in counter clockwise orientation as *Vec3* objects - **ezdxf.render.forms.euler\_spiral(count: int, length: float = 1, curvature: float = 1, elevation: float = 0) -\> Iterable\[*Vec3*\]** Create polygon vertices for an *euler spiral* of a given *length* and radius of curvature. This is a parametric curve, which always starts at the origin (0, 0). - **Parameters** - • **count** – count of polygon vertices - • **length** – length of curve in drawing units - • **curvature** – radius of curvature - • **elevation** – z-axis for all vertices - **Returns** vertices as *Vec3* objects - **ezdxf.render.forms.gear(count: int, top\_width: float, bottom\_width: float, height: float, outside\_radius: float, elevation: float = 0, close: bool = False) -\> Iterable\[*Vec3*\]** Returns the corner vertices of a *gear shape* (cogwheel). **WARNING:** This function does not create correct gears for mechanical engineering! - **Parameters** - • **count** – teeth count \>= 3 - • **top\_width** – teeth width at outside radius - • **bottom\_width** – teeth width at base radius - • **height** – teeth height; base radius = outside radius - height - • **outside\_radius** – outside radius - • **elevation** – z-axis for all vertices - • **close** – yields first vertex also as last vertex if True. - **Returns** vertices in counter clockwise orientation as *Vec3* objects - **ezdxf.render.forms.ngon(count: int, length: float \| None = None, radius: float \| None = None, rotation: float = 0.0, elevation: float = 0.0, close: bool = False) -\> Iterable\[*Vec3*\]** Returns the corner vertices of a *regular polygon*. The polygon size is determined by the edge *length* or the circum *radius* argument. If both are given *length* has the higher priority. - **Parameters** - • **count** – count of polygon corners \>= 3 - • **length** – length of polygon side - • **radius** – circum radius - • **rotation** – rotation angle in radians - • **elevation** – z-axis for all vertices - • **close** – yields first vertex also as last vertex if **True**. - **Returns** vertices as *Vec3* objects - **ezdxf.render.forms.square(size: float = 1.0, center=False) -\> tuple\[*Vec3*, *Vec3*, *Vec3*, *Vec3*\]** Returns 4 vertices for a square with a side length of the given *size*. The center of the square in (0, 0) if *center* is **True** otherwise the lower left corner is (0, 0), upper right corner is (*size*, *size*). - **ezdxf.render.forms.star(count: int, r1: float, r2: float, rotation: float = 0.0, elevation: float = 0.0, close: bool = False) -\> Iterable\[*Vec3*\]** Returns the corner vertices for a *star shape*. The shape has *count* spikes, *r1* defines the radius of the “outer” vertices and *r2* defines the radius of the “inner” vertices, but this does not mean that *r1* has to be greater than *r2*. - **Parameters** - • **count** – spike count \>= 3 - • **r1** – radius 1 - • **r2** – radius 2 - • **rotation** – rotation angle in radians - • **elevation** – z-axis for all vertices - • **close** – yields first vertex also as last vertex if **True**. - **Returns** vertices as *Vec3* objects - **ezdxf.render.forms.turtle(commands: str, start=Vec2(0, 0), angle: float = 0) -\> Iterator\[*Vec2*\]** Returns the 2D vertices of a polyline created by turtle-graphic like commands: - • **\** - go \ units forward in current direction and yield vertex - • **r\** - turn right \ in degrees, a missing angle is 90 deg - • **l\** - turn left \ in degrees, a missing angle is 90 deg - • **@\,\** - go relative \,\ and yield vertex The command string **"10 l 10 l 10"** returns the 4 corner vertices of a square with a side length of 10 drawing units. - **Parameters** - • **commands** – command string, commands are separated by spaces - • **start** – starting point, default is (0, 0) - • **angle** – starting direction, default is 0 deg ### 3D Forms Create 3D forms as *MeshTransformer* objects. - **ezdxf.render.forms.cube(center: bool = True) -\> MeshTransformer** Create a *cube* as *MeshTransformer* object. - **Parameters** **center** – ‘mass’ center of cube, **(0, 0, 0)** if **True**, else first corner at **(0, 0, 0)** Returns: *MeshTransformer* - **ezdxf.render.forms.cone(count: int = 16, radius: float = 1.0, apex: *UVec* = (0, 0, 1), \*, caps=True) -\> MeshTransformer** Create a *cone* as *MeshTransformer* object, the base center is fixed in the origin (0, 0, 0). - **Parameters** - • **count** – edge count of basis\_vector - • **radius** – radius of basis\_vector - • **apex** – tip of the cone - • **caps** – add a bottom face as ngon if **True** - **ezdxf.render.forms.cone\_2p(count: int = 16, radius: float = 1.0, base\_center: *UVec* = (0, 0, 0), apex: *UVec* = (0, 0, 1), \*, caps=True) -\> MeshTransformer** Create a *cone* as *MeshTransformer* object from two points, *base\_center* is the center of the base circle and *apex* as the tip of the cone. - **Parameters** - • **count** – edge count of basis\_vector - • **radius** – radius of basis\_vector - • **base\_center** – center point of base circle - • **apex** – tip of the cone - • **caps** – add a bottom face as ngon if **True** - **Raises** **ValueError** – the cone orientation cannot be detected (base center == apex) - **ezdxf.render.forms.cylinder(count: int = 16, radius: float = 1.0, top\_radius: float \| None = None, top\_center: *UVec* = (0, 0, 1), \*, caps=True) -\> MeshTransformer** Create a *cylinder* as *MeshTransformer* object, the base center is fixed in the origin (0, 0, 0). - **Parameters** - • **count** – profiles edge count - • **radius** – radius for bottom profile - • **top\_radius** – radius for top profile, if **None** top\_radius == radius - • **top\_center** – location vector for the center of the top profile - • **caps** – close hull with top- and bottom faces (ngons) - **ezdxf.render.forms.cylinder\_2p(count: int = 16, radius: float = 1, base\_center: *UVec* = (0, 0, 0), top\_center: *UVec* = (0, 0, 1), \*, caps=True) -\> MeshTransformer** Creates a *cylinder* as *MeshTransformer* object from two points, *base\_center* is the center of the base circle and, *top\_center* the center of the top circle. - **Parameters** - • **count** – cylinder profile edge count - • **radius** – radius for bottom profile - • **base\_center** – center of base circle - • **top\_center** – center of top circle - • **caps** – close hull with top- and bottom faces (ngons) - **Raises** **ValueError** – the cylinder orientation cannot be detected (base center == top center) - **ezdxf.render.forms.helix(radius: float, pitch: float, turns: float, resolution: int = 16, ccw=True) -\> Iterator\[*Vec3*\]** Yields the vertices of a *helix*. The center of the helix is always (0, 0), a positive *pitch* value creates a helix along the +z-axis, a negative value along the -z-axis. - **Parameters** - • **radius** – helix radius - • **pitch** – the height of one complete helix turn - • **turns** – count of turns - • **resolution** – vertices per turn - • **ccw** – creates a counter-clockwise turning (right-handed) helix if **True** - **ezdxf.render.forms.sphere(count: int = 16, stacks: int = 8, radius: float = 1, \*, quads=True) -\> MeshTransformer** Create a *sphere* as *MeshTransformer* object, the center of the sphere is always at (0, 0, 0). - **Parameters** - • **count** – longitudinal slices - • **stacks** – latitude slices - • **radius** – radius of sphere - • **quads** – use quadrilaterals as faces if **True** else triangles - **ezdxf.render.forms.torus(major\_count: int = 16, minor\_count: int = 8, major\_radius=1.0, minor\_radius=0.1, start\_angle: float = 0.0, end\_angle: float = math.tau, \*, caps=True) -\> MeshTransformer** Create a *torus* as *MeshTransformer* object, the center of the torus is always at (0, 0, 0). The *major\_radius* has to be bigger than the *minor\_radius*. - **Parameters** - • **major\_count** – count of circles - • **minor\_count** – count of circle vertices - • **major\_radius** – radius of the circle center - • **minor\_radius** – radius of circle - • **start\_angle** – start angle of torus in radians - • **end\_angle** – end angle of torus in radians - • **caps** – close hull with start- and end faces (ngons) if the torus is open ### 3D Form Builder - **ezdxf.render.forms.extrude(profile: Iterable\[*UVec*\], path: Iterable\[*UVec*\], close=True, caps=False) -\> MeshTransformer** Extrude a *profile* polygon along a *path* polyline, the vertices of *profile* should be in counter-clockwise order. The sweeping profile will not be rotated at extrusion! - **Parameters** - • **profile** – sweeping profile as list of (x, y, z) tuples in counter-clockwise order - • **path** – extrusion path as list of (x, y, z) tuples - • **close** – close profile polygon if **True** - • **caps** – close hull with top- and bottom faces (ngons) Returns: *MeshTransformer* - **ezdxf.render.forms.extrude\_twist\_scale(profile: Iterable\[*UVec*\], path: Iterable\[*UVec*\], \*, twist: float = 0.0, scale: float = 1.0, step\_size: float = 1.0, close=True, caps=False, quads=True) -\> MeshTransformer** Extrude a *profile* polygon along a *path* polyline, the vertices of *profile* should be in counter-clockwise order. This implementation can scale and twist the sweeping profile along the extrusion path. The *path* segment points are fix points, the *max\_step\_size* is used to create intermediate profiles between this fix points. The *max\_step\_size* is adapted for each segment to create equally spaced distances. The twist angle is the rotation angle in radians and the scale *argument* defines the scale factor of the final profile. The twist angle and scaling factor of the intermediate profiles will be linear interpolated between the start and end values. - **Parameters** - • **profile** – sweeping profile as list of (x, y, z) tuples in counter-clockwise order - • **path** – extrusion path as list of (x, y, z) tuples - • **twist** – rotate sweeping profile up to the given end rotation angle in radians - • **scale** – scale sweeping profile gradually from 1.0 to given value - • **step\_size** – rough distance between automatically created intermediate profiles, the step size is adapted to the distances between the path segment points, a value od 0.0 disables creating intermediate profiles - • **close** – close profile polygon if **True** - • **caps** – close hull with top- and bottom faces (ngons) - • **quads** – use quads for “sweeping” faces if **True** else triangles, the top and bottom faces are always ngons Returns: *MeshTransformer* - **ezdxf.render.forms.from\_profiles\_linear(profiles: Sequence\[Sequence\[*Vec3*\]\], \*, close=True, quads=True, caps=False) -\> MeshTransformer** Returns a *MeshTransformer* instance from linear connected *profiles*. - **Parameters** - • **profiles** – list of profiles - • **close** – close profile polygon if **True** - • **quads** – use quadrilaterals as connection faces if **True** else triangles - • **caps** – close hull with top- and bottom faces (ngons) - **ezdxf.render.forms.from\_profiles\_spline(profiles: Sequence\[Sequence\[*Vec3*\]\], subdivide: int = 4, \*, close=True, quads=True, caps=False) -\> MeshTransformer** Returns a *MeshTransformer* instance by spline interpolation between given *profiles*. Requires at least 4 profiles. A *subdivide* value of 4, means, create 4 face loops between two profiles, without interpolation two profiles create one face loop. - **Parameters** - • **profiles** – list of profiles - • **subdivide** – count of face loops - • **close** – close profile polygon if **True** - • **quads** – use quadrilaterals as connection faces if **True** else triangles - • **caps** – close hull with top- and bottom faces (ngons) - **ezdxf.render.forms.rotation\_form(count: int, profile: Iterable\[*UVec*\], angle: float = math.tau, axis: *UVec* = (1, 0, 0), \*, caps=False) -\> MeshTransformer** Returns a *MeshTransformer* instance created by rotating a *profile* around an *axis*. - **Parameters** - • **count** – count of rotated profiles - • **profile** – profile to rotate as list of vertices - • **angle** – rotation angle in radians - • **axis** – rotation axis - • **caps** – close hull with start- and end faces (ngons) - **ezdxf.render.forms.sweep(profile: Iterable\[*UVec*\], sweeping\_path: Iterable\[*UVec*\], \*, close=True, quads=True, caps=True) -\> MeshTransformer** Returns the mesh from sweeping a profile along a 3D path, where the sweeping path defines the final location in the *WCS*. The profile is defined in a reference system. The origin of this reference system will be moved along the sweeping path where the z-axis of the reference system is pointing into the moving direction. Returns the mesh as *ezdxf.render.MeshTransformer* object. - **Parameters** - • **profile** – sweeping profile defined in the reference system as iterable of (x, y, z) coordinates in counter-clockwise order - • **sweeping\_path** – the sweeping path defined in the WCS as iterable of (x, y, z) coordinates - • **close** – close sweeping profile if **True** - • **quads** – use quadrilaterals as connection faces if **True** else triangles - • **caps** – close hull with top- and bottom faces (ngons) - **ezdxf.render.forms.sweep\_profile(profile: Iterable\[*UVec*\], sweeping\_path: Iterable\[*UVec*\]) -\> list\[Sequence\[*Vec3*\]\]** Returns the intermediate profiles of sweeping a profile along a 3D path where the sweeping path defines the final location in the *WCS*. The profile is defined in a reference system. The origin of this reference system will be moved along the sweeping path where the z-axis of the reference system is pointing into the moving direction. Returns the start-, end- and all intermediate profiles along the sweeping path. ### MeshBuilder The *MeshBuilder* classes are helper tools to manage meshes buildup by vertices and faces. The vertices are stored in a vertices list as **Vec3** instances. The faces are stored as a sequence of vertex indices which is the location of the vertex in the vertex list. A single *MeshBuilder* class can contain multiple separated meshes at the same time. The method *MeshBuilder.render\_mesh()* renders the content as a single DXF *Mesh* entity, which supports ngons, ngons are polygons with more than 4 vertices. This entity requires at least DXF R2000. The method *MeshBuilder.render\_polyface()* renders the content as a single DXF *Polyface* entity, which supports only triangles and quadrilaterals. This entity is supported by DXF R12. The method *MeshBuilder.render\_3dfaces()* renders each face of the mesh as a single DXF *Face3d* entity, which supports only triangles and quadrilaterals. This entity is supported by DXF R12. The *MeshTransformer* class is often used as an interface object to transfer mesh data between functions and moduls, like for the mesh exchange add-on *meshex*. The basic *MeshBuilder* class does not support transformations. - **class ezdxf.render.MeshBuilder** - **vertices** List of vertices as *Vec3* or **(x, y, z)** tuple - **faces** List of faces as list of vertex indices, where a vertex index is the index of the vertex in the *vertices* list. A face requires at least three vertices, *Mesh* supports ngons, so the count of vertices is not limited. - **add\_face(vertices: Iterable\[*UVec*\]) -\> None** Add a face as vertices list to the mesh. A face requires at least 3 vertices, each vertex is a **(x, y, z)** tuple or *Vec3* object. The new vertex indices are stored as face in the *faces* list. - **Parameters** **vertices** – list of at least 3 vertices **\[(x1, y1, z1), (x2, y2, z2),** **(x3, y3, y3), ...\]** - **add\_mesh(vertices: list\[*Vec3*\] \| None = None, faces: list\[Sequence\[int\]\] \| None = None, mesh=None) -\> None** Add another mesh to this mesh. A *mesh* can be a *MeshBuilder*, *MeshVertexMerger* or *Mesh* object or requires the attributes *vertices* and *faces*. - **Parameters** - • **vertices** – list of vertices, a vertex is a **(x, y, z)** tuple or *Vec3* object - • **faces** – list of faces, a face is a list of vertex indices - • **mesh** – another mesh entity - **add\_vertices(vertices: Iterable\[*UVec*\]) -\> Sequence\[int\]** Add new vertices to the mesh, each vertex is a **(x, y, z)** tuple or a *Vec3* object, returns the indices of the *vertices* added to the *vertices* list. e.g. adding 4 vertices to an empty mesh, returns the indices **(0, 1, 2, 3)**, adding additional 4 vertices returns the indices **(4, 5, 6, 7)**. - **Parameters** **vertices** – list of vertices, vertex as **(x, y, z)** tuple or *Vec3* objects - **Returns** indices of the *vertices* added to the *vertices* list - **Return type** tuple - **bbox() -\> *BoundingBox*** Returns the *BoundingBox* of the mesh. - **copy()** Returns a copy of mesh. - **diagnose() -\> MeshDiagnose** Returns the *MeshDiagnose* object for this mesh. - **face\_normals() -\> Iterator\[*Vec3*\]** Yields all face normals, yields the **NULLVEC** instance for degenerated faces. - **face\_orientation\_detector(reference: int = 0) -\> *FaceOrientationDetector*** Returns a *FaceOrientationDetector* or short *fod* instance. The forward orientation is defined by the *reference* face which is 0 by default. The *fod* can check if all faces are reachable from the reference face and if all faces have the same orientation. The *fod* can be reused to unify the face orientation of the mesh. - **faces\_as\_vertices() -\> Iterator\[list\[*Vec3*\]\]** Yields all faces as list of vertices. - **flip\_normals() -\> None** Flips the normals of all faces by reversing the vertex order inplace. - **classmethod from\_builder(other: *MeshBuilder*)** Create new mesh from other mesh builder, faster than *from\_mesh()* but supports only *MeshBuilder* and inherited classes. - **classmethod from\_mesh(other: *MeshBuilder* \| *Mesh*) -\> T** Create new mesh from other mesh as class method. - **Parameters** **other** – *mesh* of type *MeshBuilder* and inherited or DXF *Mesh* entity or any object providing attributes *vertices*, **edges** and *faces*. - **classmethod from\_polyface(other: *Polymesh* \| *Polyface*) -\> T** Create new mesh from a *Polyface* or *Polymesh* object. - **get\_face\_vertices(index: int) -\> Sequence\[*Vec3*\]** Returns the face *index* as sequence of *Vec3* objects. - **get\_face\_normal(index: int) -\> *Vec3*** Returns the normal vector of the face *index* as *Vec3*, returns the **NULLVEC** instance for degenerated faces. - **merge\_coplanar\_faces(passes: int = 1) -\> MeshTransformer** Returns a new *MeshBuilder* object with merged adjacent coplanar faces. The faces have to share at least two vertices and have to have the same clockwise or counter-clockwise vertex order. The current implementation is not very capable! - **mesh\_tessellation(max\_vertex\_count: int = 4) -\> MeshTransformer** Returns a new *MeshTransformer* instance, where each face has no more vertices than the given *max\_vertex\_count*. The *fast* mode uses a shortcut for faces with less than 6 vertices which may not work for concave faces! - **normalize\_faces() -\> None** Removes duplicated vertex indices from faces and stores all faces as open faces, where the last vertex is not coincident with the first vertex. - **open\_faces() -\> Iterator\[Sequence\[int\]\]** Yields all faces as sequence of integers where the first vertex is not coincident with the last vertex. - **optimize\_vertices(precision: int = 6) -\> MeshTransformer** Returns a new mesh with optimized vertices. Coincident vertices are merged together and all faces are open faces (first vertex != last vertex). Uses internally the *MeshVertexMerger* class to merge vertices. - **render\_3dfaces(layout: GenericLayoutType, dxfattribs=None, matrix: *Matrix44* \| None = None, ucs: *UCS* \| None = None)** Render mesh as *Face3d* entities into *layout*. - **Parameters** - • **layout** – *BaseLayout* object - • **dxfattribs** – dict of DXF attributes e.g. **{'layer': 'mesh', 'color': 7}** - • **matrix** – transformation matrix of type *Matrix44* - • **ucs** – transform vertices by *UCS* to *WCS* - **render\_3dsolid(layout: GenericLayoutType, dxfattribs=None) -\> *Solid3d*** Render mesh as *Solid3d* entity into *layout*. This is an **experimental** feature to create simple 3DSOLID entities from polyhedrons. The method supports closed and open shells. A 3DSOLID entity can contain multiple shells. Separate the meshes beforehand by the method *separate\_meshes()* if required. The normals vectors of all faces should point outwards. Faces can have more than 3 vertices (ngons) but non-planar faces and concave faces will cause problems in some CAD applications. The method **mesh\_tesselation()** can help to break down the faces into triangles. Requires a valid DXF document for *layout* and DXF version R2000 or newer. - **Parameters** - • **layout** – *BaseLayout* object - • **dxfattribs** – dict of DXF attributes e.g. **{'layer': 'mesh', 'color': 7}** - **Raises** - • *DXFValueError* – valid DXF document required, if **layout.doc** is **None** - • *DXFVersionError* – invalid DXF version Added in version 1.2.0. - **render\_mesh(layout: GenericLayoutType, dxfattribs=None, matrix: *Matrix44* \| None = None, ucs: *UCS* \| None = None)** Render mesh as *Mesh* entity into *layout*. - **Parameters** - • **layout** – *BaseLayout* object - • **dxfattribs** – dict of DXF attributes e.g. **{'layer': 'mesh', 'color': 7}** - • **matrix** – transformation matrix of type *Matrix44* - • **ucs** – transform vertices by *UCS* to *WCS* - **render\_normals(layout: GenericLayoutType, length: float = 1, relative=True, dxfattribs=None)** Render face normals as *Line* entities into *layout*, useful to check orientation of mesh faces. - **Parameters** - • **layout** – *BaseLayout* object - • **length** – visual length of normal, use length \< 0 to point normals in opposite direction - • **relative** – scale length relative to face size if **True** - • **dxfattribs** – dict of DXF attributes e.g. **{'layer': 'normals', 'color': 6}** - **render\_polyface(layout: GenericLayoutType, dxfattribs=None, matrix: *Matrix44* \| None = None, ucs: *UCS* \| None = None)** Render mesh as *Polyface* entity into *layout*. - **Parameters** - • **layout** – *BaseLayout* object - • **dxfattribs** – dict of DXF attributes e.g. **{'layer': 'mesh', 'color': 7}** - • **matrix** – transformation matrix of type *Matrix44* - • **ucs** – transform vertices by *UCS* to *WCS* - **separate\_meshes() -\> list\[MeshTransformer\]** A single *MeshBuilder* instance can store multiple separated meshes. This function returns this separated meshes as multiple *MeshTransformer* instances. - **subdivide(level: int = 1, quads=True) -\> MeshTransformer** Returns a new *MeshTransformer* object with all faces subdivided. - **Parameters** - • **level** – subdivide levels from 1 to max of 5 - • **quads** – create quad faces if **True** else create triangles - **subdivide\_ngons(max\_vertex\_count=4) -\> Iterator\[Sequence\[*Vec3*\]\]** Yields all faces as sequence of *Vec3* instances, where all ngons which have more than *max\_vertex\_count* vertices gets subdivided. In contrast to the *tessellation()* method, creates this method a new vertex in the centroid of the face. This can create a more regular tessellation but only works reliable for convex faces! - **tessellation(max\_vertex\_count: int = 4) -\> Iterator\[Sequence\[*Vec3*\]\]** Yields all faces as sequence of *Vec3* instances, each face has no more vertices than the given *max\_vertex\_count*. This method uses the “ear clipping” algorithm which works with concave faces too and does not create any additional vertices. - **unify\_face\_normals(\*, fod: *FaceOrientationDetector* \| None = None) -\> MeshTransformer** Returns a new *MeshTransformer* object with unified face normal vectors of all faces. The forward direction (not necessarily outwards) is defined by the face-normals of the majority of the faces. This function can not process non-manifold meshes (more than two faces are connected by a single edge) or multiple disconnected meshes in a single *MeshBuilder* object. It is possible to pass in an existing *FaceOrientationDetector* instance as argument *fod*. - **Raises** - • **NonManifoldError** – non-manifold mesh - • **MultipleMeshesError** – the *MeshBuilder* object contains multiple disconnected meshes - **unify\_face\_normals\_by\_reference(reference: int = 0, \*, force\_outwards=False, fod: *FaceOrientationDetector* \| None = None) -\> MeshTransformer** Returns a new *MeshTransformer* object with unified face normal vectors of all faces. The forward direction (not necessarily outwards) is defined by the reference face, which is the first face of the *mesh* by default. This function can not process non-manifold meshes (more than two faces are connected by a single edge) or multiple disconnected meshes in a single *MeshBuilder* object. The outward direction of all face normals can be forced by stetting the argument *force\_outwards* to **True** but this works only for closed surfaces, and it’s time-consuming! It is not possible to check for a closed surface as long the face normal vectors are not unified. But it can be done afterward by the attribute *MeshDiagnose.is\_closed\_surface()* to see if the result is trustworthy. It is possible to pass in an existing *FaceOrientationDetector* instance as argument *fod*. - **Parameters** - • **reference** – index of the reference face - • **force\_outwards** – forces face-normals to point outwards, this works only for closed surfaces, and it’s time-consuming! - • **fod** – *FaceOrientationDetector* instance - **Raises** **ValueError** – non-manifold mesh or the *MeshBuilder* object\ contains multiple disconnected meshes ### MeshTransformer Same functionality as *MeshBuilder* but supports inplace transformation. - **class ezdxf.render.MeshTransformer** Subclass of *MeshBuilder* - **transform(matrix: *Matrix44*)** Transform mesh inplace by applying the transformation *matrix*. - **Parameters** **matrix** – 4x4 transformation matrix as *Matrix44* object - **translate(dx: float \| *UVec* = 0, dy: float = 0, dz: float = 0)** Translate mesh inplace. - **Parameters** - • **dx** – translation in x-axis or translation vector - • **dy** – translation in y-axis - • **dz** – translation in z-axis - **scale(sx: float = 1, sy: float = 1, sz: float = 1)** Scale mesh inplace. - **Parameters** - • **sx** – scale factor for x-axis - • **sy** – scale factor for y-axis - • **sz** – scale factor for z-axis - **scale\_uniform(s: float)** Scale mesh uniform inplace. - **Parameters** **s** – scale factor for x-, y- and z-axis - **rotate\_x(angle: float)** Rotate mesh around x-axis about *angle* inplace. - **Parameters** **angle** – rotation angle in radians - **rotate\_y(angle: float)** Rotate mesh around y-axis about *angle* inplace. - **Parameters** **angle** – rotation angle in radians - **rotate\_z(angle: float)** Rotate mesh around z-axis about *angle* inplace. - **Parameters** **angle** – rotation angle in radians - **rotate\_axis(axis: *UVec*, angle: float)** Rotate mesh around an arbitrary axis located in the origin (0, 0, 0) about *angle*. - **Parameters** - • **axis** – rotation axis as Vec3 - • **angle** – rotation angle in radians ### MeshVertexMerger Same functionality as *MeshBuilder*, but created meshes with unique vertices and no doublets, but *MeshVertexMerger* needs extra memory for bookkeeping and also does not support transformations. The location of the merged vertices is the location of the first vertex with the same key. This class is intended as intermediate object to create compact meshes and convert them to *MeshTransformer* objects to apply transformations: ``` mesh = MeshVertexMerger() # create your mesh mesh.add_face(...) # convert mesh to MeshTransformer object return MeshTransformer.from_builder(mesh) ``` - **class ezdxf.render.MeshVertexMerger(precision: int = 6)** Subclass of *MeshBuilder* Mesh with unique vertices and no doublets, but needs extra memory for bookkeeping. *MeshVertexMerger* creates a key for every vertex by rounding its components by the Python **round()** function and a given *precision* value. Each vertex with the same key gets the same vertex index, which is the index of first vertex with this key, so all vertices with the same key will be located at the location of this first vertex. If you want an average location of all vertices with the same key use the *MeshAverageVertexMerger* class. - **Parameters** **precision** – floating point precision for vertex rounding ### MeshAverageVertexMerger This is an extended version of *MeshVertexMerger*. The location of the merged vertices is the average location of all vertices with the same key, this needs extra memory and runtime in comparison to *MeshVertexMerger* and this class also does not support transformations. - **class ezdxf.render.MeshAverageVertexMerger(precision: int = 6)** Subclass of *MeshBuilder* Mesh with unique vertices and no doublets, but needs extra memory for bookkeeping and runtime for calculation of average vertex location. *MeshAverageVertexMerger* creates a key for every vertex by rounding its components by the Python **round()** function and a given *precision* value. Each vertex with the same key gets the same vertex index, which is the index of first vertex with this key, the difference to the *MeshVertexMerger* class is the calculation of the average location for all vertices with the same key, this needs extra memory to keep track of the count of vertices for each key and extra runtime for updating the vertex location each time a vertex with an existing key is added. - **Parameters** **precision** – floating point precision for vertex rounding - **class ezdxf.render.mesh.EdgeStat(count: int, balance: int)** Named tuple of edge statistics. - **count** how often the edge *(a, b)* is used in faces as *(a, b)* or *(b, a)* - **balance** count of edges *(a, b)* - count of edges *(b, a)* and should be 0 in “healthy” closed surfaces, if the balance is not 0, maybe doubled coincident faces exist or faces may have mixed clockwise and counter-clockwise vertex orders ### MeshBuilder Helper Classes - **class ezdxf.render.MeshDiagnose** Diagnose tool which can be used to analyze and detect errors of *MeshBuilder* objects like topology errors for closed surfaces. The object contains cached values, which do not get updated if the source mesh will be changed! **NOTE:** There exist no tools in *ezdxf* to repair broken surfaces, but you can use the *ezdxf.addons.meshex* addon to exchange meshes with the open source tool *MeshLab*. Create an instance of this tool by the *MeshBuilder.diagnose()* method. - **property bbox: *BoundingBox*** Returns the *BoundingBox* of the mesh. (cached data) - **property edge\_stats: Dict\[Tuple\[int, int\], *EdgeStat*\]** Returns the edge statistics as a **dict**. The dict-key is the edge as tuple of two vertex indices *(a, b)* where *a* is always smaller than *b*. The dict-value is an **EdgeStat** tuple of edge count and edge balance, see **EdgeStat** for the definition of edge count and edge balance. (cached data) - **property euler\_characteristic: int** Returns the Euler characteristic: *https://en.wikipedia.org/wiki/Euler\_characteristic* This number is always 2 for convex polyhedra. - **property face\_normals: Sequence\[*Vec3*\]** Returns all face normal vectors as sequence. The **NULLVEC** instance is used as normal vector for degenerated faces. (cached data) - **property faces: Sequence\[Sequence\[int\]\]** Sequence of faces as **Sequence\[int\]** - **property is\_closed\_surface: bool** Returns **True** if the mesh has a closed surface. This method does not require a unified face orientation. If multiple separated meshes are present the state is only **True** if **all** meshes have a closed surface. (cached data) Returns **False** for non-manifold meshes. - **property is\_edge\_balance\_broken: bool** Returns **True** if the edge balance is broken, this indicates a topology error for closed surfaces. A non-broken edge balance reflects that each edge connects two faces, where the edge is clockwise oriented in the first face and counter-clockwise oriented in the second face. A broken edge balance indicates possible topology errors like mixed face vertex orientations or a non-manifold mesh where an edge connects more than two faces. (cached data) - **property is\_manifold: bool** Returns **True** if all edges have an edge count \< 3. (cached data) A non-manifold mesh has edges with 3 or more connected faces. - **property n\_edges: int** Returns the unique edge count. (cached data) - **property n\_faces: int** Returns the face count. - **property n\_vertices: int** Returns the vertex count. - **property vertices: Sequence\[*Vec3*\]** Sequence of mesh vertices as *Vec3* instances - **centroid() -\> *Vec3*** Returns the centroid of all vertices. (center of mass) - **estimate\_face\_normals\_direction() -\> float** Returns the estimated face-normals direction as **float** value in the range \[-1.0, 1.0\] for a closed surface. This heuristic works well for simple convex hulls but struggles with more complex structures like a torus (doughnut). A counter-clockwise (ccw) vertex arrangement for outward pointing faces is assumed but a clockwise (cw) arrangement works too but the return values are reversed. The closer the value to 1.0 (-1.0 for cw) the more likely all normals pointing outwards from the surface. The closer the value to -1.0 (1.0 for cw) the more likely all normals pointing inwards from the surface. There are no exact confidence values if all faces pointing outwards, here some examples for surfaces created by *ezdxf.render.forms* functions: - • *cube()* returns 1.0 - • *cylinder()* returns 0.9992 - • *sphere()* returns 0.9994 - • *cone()* returns 0.9162 - • *cylinder()* with all hull faces pointing outwards but caps pointing inwards returns 0.7785 but the property *is\_edge\_balance\_broken* returns **True** which indicates the mixed vertex orientation - • and the estimation of 0.0469 for a *torus()* is barely usable - **has\_non\_planar\_faces() -\> bool** Returns **True** if any face is non-planar. - **surface\_area() -\> float** Returns the surface area. - **total\_edge\_count() -\> int** Returns the total edge count of all faces, shared edges are counted separately for each face. In closed surfaces this count should be 2x the unique edge count *n\_edges*. (cached data) - **unique\_edges() -\> Iterable\[Tuple\[int, int\]\]** Yields the unique edges of the mesh as int 2-tuples. (cached data) - **volume() -\> float** Returns the volume of a closed surface or 0 otherwise. **WARNING:** The face vertices have to be in counter-clockwise order, this requirement is not checked by this method. The result is not correct for multiple separated meshes in a single MeshBuilder object!!! - **class ezdxf.render.FaceOrientationDetector(mesh: MeshBuilder, reference: int = 0)** Helper class for face orientation and face normal vector detection. Use the method *MeshBuilder.face\_orientation\_detector()* to create an instance. The face orientation detector classifies the faces of a mesh by their forward or backward orientation. The forward orientation is defined by a reference face, which is the first face of the mesh by default and this orientation is not necessarily outwards. This class has some overlapping features with *MeshDiagnose* but it has a longer setup time and needs more memory than *MeshDiagnose*. - **Parameters** - • **mesh** – source mesh as *MeshBuilder* object - • **reference** – index of the reference face - **is\_manifold** **True** if all edges have an edge count \< 3. A non-manifold mesh has edges with 3 or more connected faces. - **property all\_reachable: bool** Returns **True** if all faces are reachable from the reference face same as property *is\_single\_mesh*. - **property count: tuple\[int, int\]** Returns the count of forward and backward oriented faces. - **property backward\_faces: Iterator\[Sequence\[int\]\]** Yields all backward oriented faces. - **property forward\_faces: Iterator\[Sequence\[int\]\]** Yields all forward oriented faces. - **property has\_uniform\_face\_normals: bool** Returns **True** if all reachable faces are forward oriented according to the reference face. - **property is\_closed\_surface: bool** Returns **True** if the mesh has a closed surface. This method does not require a unified face orientation. If multiple separated meshes are present the state is only **True** if **all** meshes have a closed surface. Returns **False** for non-manifold meshes. - **property is\_single\_mesh: bool** Returns **True** if only a single mesh is present same as property *all\_reachable*. - **classify\_faces(reference: int = 0) -\> None** Detect the forward and backward oriented faces. The forward and backward orientation has to be defined by a *reference* face. - **is\_reference\_face\_pointing\_outwards() -\> bool** Returns **True** if the normal vector of the reference face is pointing outwards. This works only for meshes with unified faces which represent a closed surfaces, and it’s a time-consuming calculation! ### Trace This module provides tools to create banded lines like LWPOLYLINE with width information. Path rendering as quadrilaterals: *Trace*, *Solid* or *Face3d*. - **class ezdxf.render.trace.TraceBuilder** Sequence of 2D banded lines like polylines with start- and end width or curves with start- and end width. **NOTE:** Accepts 3D input, but z-axis is ignored. The *TraceBuilder* is a 2D only object and uses only the *OCS* coordinates! - **abs\_tol** Absolute tolerance for floating point comparisons - **append(trace: AbstractTrace) -\> None** Append a new trace. - **close()** Close multi traces by merging first and last trace, if linear traces. - **faces() -\> Iterable\[Tuple\[*Vec2*, *Vec2*, *Vec2*, *Vec2*\]\]** Yields all faces as 4-tuples of *Vec2* objects in *OCS*. - **faces\_wcs(ocs: *OCS*, elevation: float) -\> Iterable\[Sequence\[*Vec3*\]\]** Yields all faces as 4-tuples of *Vec3* objects in *WCS*. - **virtual\_entities(dxftype='TRACE', dxfattribs=None, doc: *Drawing* \| None = None) -\> Iterable\[Quadrilateral\]** Yields faces as SOLID, TRACE or 3DFACE entities with DXF attributes given in *dxfattribs*. If a document is given, the doc attribute of the new entities will be set and the new entities will be automatically added to the entity database of that document. **NOTE:** The *TraceBuilder* is a 2D only object and uses only the *OCS* coordinates! - **Parameters** - • **dxftype** – DXF type as string, “SOLID”, “TRACE” or “3DFACE” - • **dxfattribs** – DXF attributes for SOLID, TRACE or 3DFACE entities - • **doc** – associated document - **classmethod from\_polyline(polyline: *DXFGraphic*, segments: int = 64) -\> *TraceBuilder*** Create a complete trace from a LWPOLYLINE or a 2D POLYLINE entity, the trace consist of multiple sub-traces if *bulge* values are present. Uses only the *OCS* coordinates! - **Parameters** - • **polyline** – *LWPolyline* or 2D *Polyline* - • **segments** – count of segments for bulge approximation, given count is for a full circle, partial arcs have proportional less segments, but at least 3 - **\_\_len\_\_()** - **\_\_getitem\_\_()** - **class ezdxf.render.trace.LinearTrace** Linear 2D banded lines like polylines with start- and end width. Accepts 3D input, but z-axis is ignored. - **abs\_tol** Absolute tolerance for floating point comparisons - **is\_started** *True* if at least one station exist. - **add\_station(point: *UVec*, start\_width: float, end\_width: float \| None = None) -\> None** Add a trace station (like a vertex) at location *point*, *start\_width* is the width of the next segment starting at this station, *end\_width* is the end width of the next segment. Adding the last location again, replaces the actual last location e.g. adding lines (a, b), (b, c), creates only 3 stations (a, b, c), this is very important to connect to/from splines. - **Parameters** - • **point** – 2D location (vertex), z-axis of 3D vertices is ignored. - • **start\_width** – start width of next segment - • **end\_width** – end width of next segment - **faces() -\> Iterable\[Tuple\[*Vec2*, *Vec2*, *Vec2*, *Vec2*\]\]** Yields all faces as 4-tuples of *Vec2* objects. First and last miter is 90 degrees if the path is not closed, otherwise the intersection of first and last segment is taken into account, a closed path has to have explicit the same last and first vertex. - **virtual\_entities(dxftype='TRACE', dxfattribs=None, doc: *Drawing* \| None = None) -\> Iterable\[Quadrilateral\]** Yields faces as SOLID, TRACE or 3DFACE entities with DXF attributes given in *dxfattribs*. If a document is given, the doc attribute of the new entities will be set and the new entities will be automatically added to the entity database of that document. - **Parameters** - • **dxftype** – DXF type as string, “SOLID”, “TRACE” or “3DFACE” - • **dxfattribs** – DXF attributes for SOLID, TRACE or 3DFACE entities - • **doc** – associated document - **class ezdxf.render.trace.CurvedTrace** 2D banded curves like arcs or splines with start- and end width. Represents always only one curved entity and all miter of curve segments are perpendicular to curve tangents. Accepts 3D input, but z-axis is ignored. - **faces() -\> Iterable\[Tuple\[*Vec2*, *Vec2*, *Vec2*, *Vec2*\]\]** Yields all faces as 4-tuples of *Vec2* objects. - **virtual\_entities(dxftype='TRACE', dxfattribs=None, doc: *Drawing* \| None = None) -\> Iterable\[Quadrilateral\]** Yields faces as SOLID, TRACE or 3DFACE entities with DXF attributes given in *dxfattribs*. If a document is given, the doc attribute of the new entities will be set and the new entities will be automatically added to the entity database of that document. - **Parameters** - • **dxftype** – DXF type as string, “SOLID”, “TRACE” or “3DFACE” - • **dxfattribs** – DXF attributes for SOLID, TRACE or 3DFACE entities - • **doc** – associated document - **classmethod from\_arc(arc: *ConstructionArc*, start\_width: float, end\_width: float, segments: int = 64) -\> *CurvedTrace*** Create curved trace from an arc. - **Parameters** - • **arc** – *ConstructionArc* object - • **start\_width** – start width - • **end\_width** – end width - • **segments** – count of segments for full circle (360 degree) approximation, partial arcs have proportional less segments, but at least 3 - **Raises** **ValueError** – if arc.radius \<= 0 - **classmethod from\_spline(spline: *BSpline*, start\_width: float, end\_width: float, segments: int) -\> *CurvedTrace*** Create curved trace from a B-spline. - **Parameters** - • **spline** – *BSpline* object - • **start\_width** – start width - • **end\_width** – end width - • **segments** – count of segments for approximation ### Point Rendering Helper function to render *Point* entities as DXF primitives. - **ezdxf.render.point.virtual\_entities(point: Point, pdsize: float = 1, pdmode: int = 0) -\> list\[DXFGraphic\]** Yields point graphic as DXF primitives LINE and CIRCLE entities. The dimensionless point is rendered as zero-length line! Check for this condition: ``` e.dxftype() == 'LINE' and e.dxf.start.isclose(e.dxf.end) ``` if the rendering engine can’t handle zero-length lines. - **Parameters** - • **point** – DXF POINT entity - • **pdsize** – point size in drawing units - • **pdmode** – point styling mode, see *Point* class **SEE ALSO:** Go to *ezdxf.entities.Point* class documentation for more information about POINT styling modes. ### MultiLeaderBuilder These are helper classes to build *MultiLeader* entities in an easy way. The **MultiLeader** entity supports two kinds of content, for each exist a specialized builder class: - • *MultiLeaderMTextBuilder* for *MText* content - • *MultiLeaderBlockBuilder* for *Block* content The usual steps of the building process are: - 1\. create entity by a factory method - • *add\_multileader\_mtext()* - • *add\_multileader\_block()* - 2\. set the content - • *MultiLeaderMTextBuilder.set\_content()* - • *MultiLeaderBlockBuilder.set\_content()* - • *MultiLeaderBlockBuilder.set\_attribute()* - 3\. set properties - • *MultiLeaderBuilder.set\_arrow\_properties()* - • *MultiLeaderBuilder.set\_connection\_properties()* - • *MultiLeaderBuilder.set\_connection\_types()* - • *MultiLeaderBuilder.set\_leader\_properties()* - • *MultiLeaderBuilder.set\_mleader\_style()* - • *MultiLeaderBuilder.set\_overall\_scaling()* - 4\. add one or more leader lines - • *MultiLeaderBuilder.add\_leader\_line()* - 5\. finalize building process - • *MultiLeaderBuilder.build()* The *Tutorial for MultiLeader* shows how to use these helper classes in more detail. - **class ezdxf.render.MultiLeaderBuilder** Abstract base class to build *MultiLeader* entities. - **property context: MLeaderContext** Returns the context entity *MLeaderContext*. - **property multileader: MultiLeader** Returns the *MultiLeader* entity. - **add\_leader\_line(side: *ConnectionSide*, vertices: Iterable\[*Vec2*\]) -\> None** Add leader as iterable of vertices in render UCS coordinates (*WCS* by default). **NOTE:** Vertical (top, bottom) and horizontal attachment sides (left, right) can not be mixed in a single entity - this is a limitation of the MULTILEADER entity. - **Parameters** - • **side** – connection side where to attach the leader line - • **vertices** – leader vertices - **build(insert: *Vec2*, rotation: float = 0.0, ucs: *UCS* \| None = None) -\> None** Compute the required geometry data. The construction plane is the xy-plane of the given render *UCS*. - **Parameters** - • **insert** – insert location for the content in render UCS coordinates - • **rotation** – content rotation angle around the render UCS z-axis in degrees - • **ucs** – the render *UCS*, default is the *WCS* - **set\_arrow\_properties(name: str = '', size: float = 0.0)** Set leader arrow properties all leader lines have the same arrow type. The MULTILEADER entity is able to support multiple arrows, but this seems to be unsupported by CAD applications and is therefore also not supported by the builder classes. - **set\_connection\_properties(landing\_gap: float = 0.0, dogleg\_length: float = 0.0)** Set the properties how to connect the leader line to the content. The landing gap is the space between the content and the start of the leader line. The “dogleg” is the first line segment of the leader in the “horizontal” direction of the content. - **set\_connection\_types(left=HorizontalConnection.by\_style, right=HorizontalConnection.by\_style, top=VerticalConnection.by\_style, bottom=VerticalConnection.by\_style)** Set the connection type for each connection side. - **set\_leader\_properties(color: int \| *RGB* = colors.BYBLOCK, linetype: str = 'BYBLOCK', lineweight: int = const.LINEWEIGHT\_BYBLOCK, leader\_type=LeaderType.straight\_lines)** Set leader line properties. - **Parameters** - • **color** – line color as *AutoCAD Color Index (ACI)* or RGB tuple - • **linetype** – as name string, e.g. “BYLAYER” - • **lineweight** – as integer value, see: *Lineweights* - • **leader\_type** – straight lines of spline type - **set\_mleader\_style(style: MLeaderStyle)** Reset base properties by *MLeaderStyle* properties. This also resets the content! - **set\_overall\_scaling(scale: float)** Set the overall scaling factor for the whole entity, except for the leader line vertices! - **Parameters** **scale** – scaling factor \> 0.0 ### MultiLeaderMTextBuilder Specialization of *MultiLeaderBuilder* to build *MultiLeader* with MTEXT content. - **class ezdxf.render.MultiLeaderMTextBuilder** - **set\_content(content: str, color: int \| *RGB* \| None = None, char\_height: float = 0.0, alignment: *TextAlignment* = TextAlignment.left, style: str = '')** Set MTEXT content. - **Parameters** - • **content** – MTEXT content as string - • **color** – block color as *AutoCAD Color Index (ACI)* or RGB tuple - • **char\_height** – initial char height in drawing units - • **alignment** – *TextAlignment* - left, center, right - • **style** – name of *Textstyle* as string - **quick\_leader(content: str, target: *Vec2*, segment1: *Vec2*, segment2: *Vec2* \| None = None, connection\_type: *HorizontalConnection* \| *VerticalConnection* = HorizontalConnection.middle\_of\_top\_line, ucs: *UCS* \| None = None) -\> None** Creates a quick MTEXT leader. The *target* point defines where the leader points to. The *segment1* is the first segment of the leader line relative to the *target* point, *segment2* is an optional second line segment relative to the first line segment. The *connection\_type* defines the type of connection (horizontal or vertical) and the MTEXT alignment (left, center or right). Horizontal connections are always left or right aligned, vertical connections are always center aligned. - **Parameters** - • **content** – MTEXT content string - • **target** – leader target point as **Vec2** - • **segment1** – first leader line segment as relative distance to *insert* - • **segment2** – optional second leader line segment as relative distance to first line segment - • **connection\_type** – one of *HorizontalConnection* or *VerticalConnection* - • **ucs** – the rendering *UCS*, default is the *WCS* ### MultiLeaderBlockBuilder Specialization of *MultiLeaderBuilder* to build *MultiLeader* with BLOCK content. - **class ezdxf.render.MultiLeaderBlockBuilder** - **property block\_layout: *BlockLayout*** Returns the block layout. - **property extents: *BoundingBox*** Returns the bounding box of the block. - **set\_content(name: str, color: int \| *RGB* = colors.BYBLOCK, scale: float = 1.0, alignment=BlockAlignment.center\_extents)** Set BLOCK content. - **Parameters** - • **name** – the block name as string - • **color** – block color as *AutoCAD Color Index (ACI)* or RGB tuple - • **scale** – the block scaling, not to be confused with overall scaling - • **alignment** – the block insertion point or the center of extents - **set\_attribute(tag: str, text: str, width: float = 1.0)** Add BLOCK attributes based on an ATTDEF entity in the block definition. All properties of the new created ATTRIB entity are defined by the template ATTDEF entity including the location. - **Parameters** - • **tag** – attribute tag name - • **text** – attribute content string - • **width** – width factor ### Enums - **class ezdxf.render.LeaderType(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The leader type. - **none** - **straight\_lines** - **splines** - **class ezdxf.render.ConnectionSide(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The leader connection side. Vertical (top, bottom) and horizontal attachment sides (left, right) can not be mixed in a single entity - this is a limitation of the MULTILEADER entity. - **left** - **right** - **top** - **bottom** - **class ezdxf.render.HorizontalConnection(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The horizontal leader connection type. - **by\_style** - **top\_of\_top\_line** - **middle\_of\_top\_line** - **middle\_of\_text** - **middle\_of\_bottom\_line** - **bottom\_of\_bottom\_line** - **bottom\_of\_bottom\_line\_underline** - **bottom\_of\_top\_line\_underline** - **bottom\_of\_top\_line** - **bottom\_of\_top\_line\_underline\_all** - **class ezdxf.render.VerticalConnection(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The vertical leader connection type. - **by\_style** - **center** - **center\_overline** - **class ezdxf.render.TextAlignment(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The **MText** alignment type. - **left** - **center** - **right** - **class ezdxf.render.BlockAlignment(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** The **Block** alignment type. - **center\_extents** - **insertion\_point** ### Arrows This module provides support for the AutoCAD standard arrow heads used in DIMENSION, LEADER and MULTILEADER entities. Library user don’t have to use the *ARROWS* objects directly, but should know the arrow names stored in it as attributes. The arrow names should be accessed that way: ``` import ezdxf arrow = ezdxf.ARROWS.closed_filled ``` - **ezdxf.render.arrows.ARROWS** Single instance of *\_Arrows* to work with. - **class ezdxf.render.arrows.\_Arrows** Management object for standard arrows. - **\_\_acad\_\_** Set of AutoCAD standard arrow names. - **\_\_ezdxf\_\_** Set of arrow names special to *ezdxf*. - **architectural\_tick** \[image\] - **closed\_filled** \[image\] - **dot** \[image\] - **dot\_small** \[image\] - **dot\_blank** \[image\] - **origin\_indicator** \[image\] - **origin\_indicator\_2** \[image\] - **open** \[image\] - **right\_angle** \[image\] - **open\_30** \[image\] - **closed** \[image\] - **dot\_smallblank** \[image\] - **none** \[image\] - **oblique** \[image\] - **box\_filled** \[image\] - **box** \[image\] - **closed\_blank** \[image\] - **datum\_triangle\_filled** \[image\] - **datum\_triangle** \[image\] - **integral** \[image\] - **ez\_arrow** \[image\] - **ez\_arrow\_blank** \[image\] - **ez\_arrow\_filled** \[image\] - **is\_acad\_arrow(item: str) -\> bool** Returns **True** if *item* is a standard AutoCAD arrow. - **is\_ezdxf\_arrow(item: str) -\> bool** Returns **True** if *item* is a special *ezdxf* arrow. - **insert\_arrow(layout: GenericLayoutType, name: str, insert: *UVec* = NULLVEC, size: float = 1.0, rotation: float = 0, \*, dxfattribs=None) -\> *Vec2*** Insert arrow as block reference into *layout*. - **render\_arrow(layout: GenericLayoutType, name: str, insert: *UVec* = NULLVEC, size: float = 1.0, rotation: float = 0, \*, dxfattribs=None) -\> *Vec2*** Render arrow as basic DXF entities into *layout*. - **virtual\_entities(name: str, insert: *UVec* = NULLVEC, size: float = 0.625, rotation: float = 0, \*, dxfattribs=None) -\> Iterator\[*DXFGraphic*\]** Returns all arrow components as virtual DXF entities. ### Hatching This module provides rendering support for hatch patterns as used in *Hatch* and *MPolygon* entities. ### High Level Functions - **ezdxf.render.hatching.hatch\_entity(polygon: DXFPolygon, filter\_text\_boxes=True, jiggle\_origin: bool = True) -\> Iterator\[tuple\[*Vec3*, *Vec3*\]\]** Yields the hatch pattern of the given HATCH or MPOLYGON entity as 3D lines. Each line is a pair of *Vec3* instances as start- and end vertex, points are represented as lines of zero length, which means the start vertex is equal to the end vertex. The function yields nothing if *polygon* has a solid- or gradient filling or does not have a usable pattern assigned. - **Parameters** - • **polygon** – *Hatch* or *MPolygon* entity - • **filter\_text\_boxes** – ignore text boxes if **True** - • **jiggle\_origin** – move pattern line origins a small amount to avoid intersections in corner points which causes errors in patterns - **ezdxf.render.hatching.hatch\_polygons(baseline: *HatchBaseLine*, polygons: Sequence\[Sequence\[*Vec2*\]\], terminate: Callable\[\[\], bool\] \| None = None) -\> Iterator\[*Line*\]** Yields all pattern lines for all hatch lines generated by the given *HatchBaseLine*, intersecting the given 2D polygons as *Line* instances. The *polygons* should represent a single entity with or without holes, the order of the polygons and their winding orientation (cw or ccw) is not important. Entities which do not intersect or overlap should be handled separately! Each polygon is a sequence of *Vec2* instances, they are treated as closed polygons even if the last vertex is not equal to the first vertex. The hole detection is done by a simple inside/outside counting algorithm and far from perfect, but is able to handle ordinary polygons well. The terminate function WILL BE CALLED PERIODICALLY AND should return **True** to terminate execution. This can be used to implement a timeout, which can be required if using a very small hatching distance, especially if you get the data from untrusted sources. - **Parameters** - • **baseline** – *HatchBaseLine* - • **polygons** – multiple sequences of **Vec2** instances of a single entity, the order of exterior- and hole paths and the winding orientation (cw or ccw) of paths is not important - • **terminate** – callback function which is called periodically and should return **True** to terminate the hatching function - **ezdxf.render.hatching.hatch\_paths(baseline: *HatchBaseLine*, paths: Sequence\[Path\], terminate: Callable\[\[\], bool\] \| None = None) -\> Iterator\[*Line*\]** Yields all pattern lines for all hatch lines generated by the given *HatchBaseLine*, intersecting the given 2D *Path* instances as *Line* instances. The paths are handled as projected into the xy-plane the z-axis of path vertices will be ignored if present. Same as the *hatch\_polygons()* function, but for *Path* instances instead of polygons build of vertices. This function **does not** **flatten** the paths into vertices, instead the real intersections of the Bézier curves and the hatch lines are calculated. For more information see the docs of the *hatch\_polygons()* function. - **Parameters** - • **baseline** – *HatchBaseLine* - • **paths** – sequence of *Path* instances of a single entity, the order of exterior- and hole paths and the winding orientation (cw or ccw) of the paths is not important - • **terminate** – callback function which is called periodically and should return **True** to terminate the hatching function ### Classes - **class ezdxf.render.hatching.HatchBaseLine(origin: *Vec2*, direction: *Vec2*, offset: *Vec2*, line\_pattern: list\[float\] \| None = None, min\_hatch\_line\_distance=MIN\_HATCH\_LINE\_DISTANCE)** A hatch baseline defines the source line for hatching a geometry. A complete hatch pattern of a DXF entity can consist of one or more hatch baselines. - **Parameters** - • **origin** – the origin of the hatch line as *Vec2* instance - • **direction** – the hatch line direction as *Vec2* instance, must not (0, 0) - • **offset** – the offset of the hatch line origin to the next or to the previous hatch line - • **line\_pattern** – line pattern as sequence of floats, see also *PatternRenderer* - • **min\_hatch\_line\_distance** – minimum hatch line distance to render, raises an *DenseHatchingLinesError* exception if the distance between hatch lines is smaller than this value - **Raises** - • *HatchLineDirectionError* – hatch baseline has no direction, (0, 0) vector - • *DenseHatchingLinesError* – hatching lines are too narrow - **hatch\_line(distance: float) -\> *HatchLine*** Returns the *HatchLine* at the given signed *distance*. - **pattern\_renderer(distance: float) -\> *PatternRenderer*** Returns the *PatternRenderer* for the given signed *distance*. - **signed\_distance(point: *Vec2*) -\> float** Returns the signed normal distance of the given *point* from this hatch baseline. - **class ezdxf.render.hatching.HatchLine(origin: *Vec2*, direction: *Vec2*, distance: float)** Represents a single hatch line. - **Parameters** - • **origin** – the origin of the hatch line as *Vec2* instance - • **direction** – the hatch line direction as *Vec2* instance, must not (0, 0) - • **distance** – the normal distance to the base hatch line as float - **intersect\_line(a: *Vec2*, b: *Vec2*, dist\_a: float, dist\_b: float) -\> *Intersection*** Returns the *Intersection* of this hatch line and the line defined by the points *a* and *b*. The arguments *dist\_a* and *dist\_b* are the signed normal distances of the points *a* and *b* from the hatch baseline. The normal distances from the baseline are easy to calculate by the *HatchBaseLine.signed\_distance()* method and allow a fast intersection calculation by a simple point interpolation. - **Parameters** - • **a** – start point of the line as *Vec2* instance - • **b** – end point of the line as *Vec2* instance - • **dist\_a** – normal distance of point *a* to the hatch baseline as float - • **dist\_b** – normal distance of point *b* to the hatch baseline as float - **intersect\_cubic\_bezier\_curve(curve: *Bezier4P*) -\> Sequence\[*Intersection*\]** Returns 0 to 3 *Intersection* points of this hatch line with a cubic Bèzier curve. - **Parameters** **curve** – the cubic Bèzier curve as *ezdxf.math.Bezier4P* instance - **class ezdxf.render.hatching.PatternRenderer(hatch\_line: *HatchLine*, pattern: Sequence\[float\])** The hatch pattern of a DXF entity has one or more *HatchBaseLine* instances with an origin, direction, offset and line pattern. The *PatternRenderer* for a certain distance from the baseline has to be acquired from the *HatchBaseLine* by the *pattern\_renderer()* method. The origin of the hatch line is the starting point of the line pattern. The offset defines the origin of the adjacent hatch line and doesn’t have to be orthogonal to the hatch line direction. **Line Pattern** The line pattern is a sequence of floats, where a value \> 0.0 is a dash, a value \< 0.0 is a gap and value of 0.0 is a point. - **Parameters** - • **hatch\_line** – *HatchLine* - • **pattern** – the line pattern as sequence of float values - **render(start: *Vec2*, end: *Vec2*) -\> Iterator\[tuple\[*Vec2*, *Vec2*\]\]** Yields the pattern lines as pairs of *Vec2* instances from the start- to the end point on the hatch line. For points the start- and end point are the same *Vec2* instance and can be tested by the **is** operator. The start- and end points should be located collinear at the hatch line of this instance, otherwise the points a projected onto this hatch line. - **class ezdxf.render.hatching.Intersection(type: *IntersectionType* = IntersectionType.NONE, p0: *Vec2* = Vec2(nan, nan), p1: *Vec2* = Vec2(nan, nan))** Represents an intersection. - **type** intersection type as *IntersectionType* instance - **p0** (first) intersection point as *Vec2* instance - **p1** second intersection point as *Vec2* instance, only if *type* is COLLINEAR - **class ezdxf.render.hatching.IntersectionType(value, names=\_not\_given, \*values, module=None, qualname=None, type=None, start=1, boundary=None)** - **NONE** no intersection - **REGULAR** regular intersection point at a polygon edge or a Bèzier curve - **START** intersection point at the start vertex of a polygon edge - **END** intersection point at the end vertex of a polygon edge - **COLLINEAR** intersection is collinear to a polygon edge - **class ezdxf.render.hatching.Line(start: 'Vec2', end: 'Vec2', distance: 'float')** - **start** start point as *Vec2* instance - **end** end point as *Vec2* instance - **distance** signed normal distance to the *HatchBaseLine* ### Helper Functions - **ezdxf.render.hatching.hatch\_boundary\_paths(polygon: DXFPolygon, filter\_text\_boxes=True) -\> list\[*Path*\]** Returns the hatch boundary paths as *ezdxf.path.Path* instances of HATCH and MPOLYGON entities. Ignores text boxes if argument *filter\_text\_boxes* is **True**. - **ezdxf.render.hatching.hatch\_line\_distances(point\_distances: Sequence\[float\], normal\_distance: float) -\> list\[float\]** Returns all hatch line distances in the range of the given point distances. - **ezdxf.render.hatching.pattern\_baselines(polygon: DXFPolygon, min\_hatch\_line\_distance: float = MIN\_HATCH\_LINE\_DISTANCE, \*, jiggle\_origin: bool = False) -\> Iterator\[*HatchBaseLine*\]** Yields the hatch pattern baselines of HATCH and MPOLYGON entities as *HatchBaseLine* instances. Set *jiggle\_origin* to **True** to move pattern line origins a small amount to avoid intersections in corner points which causes errors in patterns. ### Exceptions - **class ezdxf.render.hatching.HatchingError** Base exception class of the **hatching** module. - **class ezdxf.render.hatching.HatchLineDirectionError** Hatching direction is undefined or a (0, 0) vector. - **class ezdxf.render.hatching.DenseHatchingLinesError** Very small hatching distance which creates too many hatching lines. **TODO:** - • ACAD\_TABLE helper tools - • Dynamic Block helper tools ### Global Options ### Global Options Object The global *ezdxf* options are stored in the object *ezdxf.options*. Recommended usage of the global **options** object: ``` import ezdxf value = ezdxf.options.attribute ``` **IMPORTANT:** Most options are only read at startup (support folders, paths to executables), changing these values has no effect at runtime. To change these options, you must create a configuration file, see section *Config Files*. The **options** object uses the Standard Python class **ConfigParser** to manage the configuration. Shortcut attributes like *test\_files* are simple properties and most shortcuts are read only marked by (Read only), read and writeable attributes are marked by (Read/Write). To change options, especially the read only attributes, you have to edit the config file with a text editor, or set options by the *set()* method and write the current configuration into a config file. ### Config Files The default config files are loaded from the user home directory as “~/.config/ezdxf/ezdxf.ini”, and the current working directory as “./ezdxf.ini”. A custom config file can be specified by the environment variable **EZDXF\_CONFIG\_FILE**. Ezdxf follows the *XDG Base Directory specification* if the environment variable **XDG\_CONFIG\_HOME** is set. The config file loading order: - 1\. user home directory: “~/.config/ezdxf/ezdxf.ini” - 2\. current working directory: “./ezdxf.ini” - 3\. config file specified by **EZDXF\_CONFIG\_FILE** A configuration file that is loaded later does not replace the previously loaded ones, only the existing options in the newly loaded file are added to the configuration and can overwrite existing options. Configuration files are regular INI files, managed by the standard Python *ConfigParser* class. File Structure: ``` [core] default_dimension_text_style = OpenSansCondensed-Light test_files = D:\Source\dxftest support_dirs = "C:\Program Files\Bricsys\BricsCAD V23 en_US\Fonts", "~/dir2", "~/dir3", load_proxy_graphics = true store_proxy_graphics = true log_unprocessed_tags = false filter_invalid_xdata_group_codes = true write_fixed_meta_data_for_testing = false disable_c_ext = false [browse-command] text_editor = "C:\Program Files\Notepad++\notepad++.exe" "{filename}" -n{num} ``` ### Modify and Save Changes This code shows how to get and set values of the underlying **ConfigParser** object, but use the shortcut attributes if available: ``` # Set options, value has to ba a str, use "true"/"false" for boolean values ezdxf.options.set(section, key, value) # Get option as string value = ezdxf.options.get(section, key, default="") # Special getter for boolean, int and float value = ezdxf.options.get_bool(section, key, default=False) value = ezdxf.options.get_int(section, key, default=0) value = ezdxf.options.get_float(section, key, default=0.0) ``` If you set options, they are not stored automatically in a config file, you have to write back the config file manually: ``` # write back the default user config file "ezdxf.ini" in the # user home directory ezdxf.options.write_home_config() # write back to the default config file "ezdxf.ini" in the # current working directory ezdxf.options.write_file() # write back to a specific config file ezdxf.options.write_file("my_config.ini") # which has to be loaded manually at startup ezdxf.options.read_file("my_config.ini") ``` This example shows how to change the *test\_files* path and save the changes into a custom config file “my\_config.ini”: ``` import ezdxf test_files = Path("~/my-dxf-test-files").expand_user() ezdxf.options.set( ezdxf.options.CORE, # section "test_files", # key "~/my-dxf-test-files", # value ) ezdxf.options.write_file("my_config.ini") ``` ### Use a Custom Config File You can specify a config file by the environment variable **EZDXF\_CONFIG\_FILE**, which is loaded after the default config files. ``` C:\> set EZDXF_CONFIG_FILE=D:\user\path\custom.ini ``` Custom config files are not loaded automatically like the default config files. This example shows how to load the previous created custom config file “my\_config.ini” from the current working directory: ``` import ezdxf ezdxf.options.read("my_config.ini") ``` That is all and because this is the last loaded config file, it overrides all default config files and the config file specified by **EZDXF\_CONFIG\_FILE**. ### Functions - **ezdxf.options.set(section: str, key: str, value: str)** Set option *key* in *section* to *values* as **str**. - **ezdxf.options.get(section: str, key: str, default: str = '') -\> str** Get option *key* in *section* as string. - **ezdxf.options.get\_bool(section: str, key: str, default: bool = False) -\> bool** Get option *key* in *section* as **bool**. - **ezdxf.options.get\_int(section: str, key: str, default: int = 0) -\> int** Get option *key* in *section* as **int**. - **ezdxf.options.get\_float(section: str, key: str, default: float = 0.0) -\> flot** Get option *key* in *section* as **float**. - **ezdxf.options.write(fp: TextIO)** Write configuration into given file object *fp*, the file object must be a writeable text file with “utf8” encoding. - **ezdxf.options.write\_file(filename: str = 'ezdxf.ini')** Write current configuration into file *filename*, default is “ezdxf.ini” in the current working directory. - **ezdxf.options.write\_home\_config()** Write configuration into file “~/.config/ezdxf/ezdxf.ini”, **$XDG\_CONFIG\_HOME** is supported if set. - **ezdxf.options.read\_file(filename: str)** Append content from config file *filename*, but does not reset the configuration. - **ezdxf.options.print()** Print configuration to *stdout*. - **ezdxf.options.reset()** Reset options to factory default values. - **ezdxf.options.delete\_default\_config\_files()** Delete the default config files “ezdxf.ini” in the current working and in the user home directory “~/.config/ezdxf”, **$XDG\_CONFIG\_HOME** is supported if set. - **ezdxf.options.preserve\_proxy\_graphics(state=True)** Enable/disable proxy graphic load/store support by setting the options **load\_proxy\_graphics** and **store\_proxy\_graphics** to *state*. - **ezdxf.options.loaded\_config\_files** Read only property of loaded config files as tuple for **Path** objects. ### Core Options For all core options the section name is **core**. ### Default Dimension Text Style The default dimension text style is used by the DIMENSION renderer of *ezdxf*, if the specified text style exist in the STYLE table. To use any of the default style of *ezdxf* you have to setup the styles at the creation of the DXF document: **ezdxf.new(setup=True)**, or setup the *ezdxf* default styles for a loaded DXF document: ``` import ezdxf from ezdxf.tool.standard import setup_drawing doc = ezdxf.readfile("your.dxf") setup_drawing(doc) ``` Config file key: **default\_dimension\_text\_style** Shortcut attribute: - **ezdxf.options.default\_dimension\_text\_style** (Read/Write) Get/Set default text style for DIMENSION rendering, default value is **OpenSansCondensed-Light**. ### Load Proxy Graphic Proxy graphics are not essential for DXF files, but they can provide a simple graphical representation for complex entities, but extra memory is needed to store this information. You can save some memory by not loading the proxy graphic, but the proxy graphic is lost if you write back the DXF file. The current version of *ezdxf* uses this proxy graphic to render MLEADER entities by the *drawing* add-on. Config file key: **load\_proxy\_graphics** Shortcut attribute: - **ezdxf.options.load\_proxy\_graphics** (Read/Write) Load proxy graphics if **True**, default is **True**. ### Store Proxy Graphic Prevent exporting proxy graphics if set to **False**. Config file key: **store\_proxy\_graphics** Shortcut attribute: - **ezdxf.options.store\_proxy\_graphics** (Read/Write) Export proxy graphics if **True**, default is **True**. ### Support Directories Search directories for support files: - • plot style tables, the .ctb or .stb pen assignment files - • shape font files of type .shx or .shp or .lff **IMPORTANT:** When you add new font directories to **support\_dirs** or new fonts to one of the support directories, you have to rebuild the font cache to use these fonts, see section *Rebuilding the Font Cache* for more information. Config file key: **support\_dirs** Shortcut attribute: - **ezdxf.options.support\_dirs** (Read/Write) Search directories as list of strings. Use quotes for paths including spaces: ``` [core] support_dirs = ~/dir1, ~/dir2, "~/dir 3", ``` ### Debugging Options For all debugging options the section name is **core**. ### Test Files Path to test files. Some of the *CADKit* test files are used by the integration tests, these files should be located in the **ezdxf.options.test\_files\_path / "CADKitSamples"** folder. Config file key: **test\_files** Shortcut attributes: - **ezdxf.options.test\_files** (Read only) Returns the path to the *ezdxf* test files as **str**, expands “~” construct automatically. - **ezdxf.options.test\_files\_path** (Read only) Path to test files as **pathlib.Path** object. ### Filter Invalid XDATA Group Codes Only a very limited set of group codes is valid in the XDATA section and AutoCAD is very picky about that. *Ezdxf* removes invalid XDATA group codes if this option is set to **True**, but this needs processing time, which is wasted if you get your DXF files from trusted sources like AutoCAD or BricsCAD. Config file key: **filter\_invalid\_xdata\_group\_codes** - **ezdxf.options.filter\_invalid\_xdata\_group\_codes** (Read only) Filter invalid XDATA group codes, default value is **True**. ### Log Unprocessed Tags Logs unprocessed DXF tags, this helps to find new and undocumented DXF features. Config file key: **log\_unprocessed\_tags** - **ezdxf.options.log\_unprocessed\_tags** (Read/Write) Log unprocessed DXF tags for debugging, default value is **False**. ### Write Fixed Meta Data for Testing Write the DXF files with fixed meta data to test your DXF files by a diff-like command, this is necessary to get always the same meta data like the saving time stored in the HEADER section. This may not work across different *ezdxf* versions! Config file key: **write\_fixed\_meta\_data\_for\_testing** - **ezdxf.options.write\_fixed\_meta\_data\_for\_testing** (Read/Write) Enable this option to always create same meta data for testing scenarios, e.g. to use a diff-like tool to compare DXF documents, default is **False**. ### Disable C-Extension It is possible to deactivate the optional C-extensions if there are any issues with the C-extensions. This has to be done in a default config file or by environment variable before the first import of *ezdxf*. For **pypy3** the C-extensions are always disabled, because the JIT compiled Python code is much faster. **IMPORTANT:** This option works only in the **default config files**, user config files which are loaded by *ezdxf.options.read\_file()* cannot disable the C-Extensions, because at this point the setup process of *ezdxf* is already finished! Config file key: **disable\_c\_ext** - **ezdxf.options.disable\_c\_ext** (Read only) This option disables the C-extensions if **True**. This can only be done before the first import of *ezdxf* by using a config file or the environment variable **EZDXF\_DISABLE\_C\_EXT**. ### Use C-Extensions - **ezdxf.options.use\_c\_ext** (Read only) Shows the actual state of C-extensions usage. ### Environment Variables Some feature can be controlled by environment variables. Command line example for disabling the optional C-extensions on Windows: ``` C:\> set EZDXF_DISABLE_C_EXT=1 ``` **IMPORTANT:** If you change any environment variable, you have to restart the Python interpreter! - **EZDXF\_DISABLE\_C\_EXT** Set environment variable **EZDXF\_DISABLE\_C\_EXT** to **1** or **True** to disable the usage of the C-extensions. - **EZDXF\_TEST\_FILES** Path to the *ezdxf* test files required by some tests, for instance the *CADKit* sample files should be located in the **EZDXF\_TEST\_FILES/CADKitSamples** folder. See also option *ezdxf.options.test\_files*. - **EZDXF\_CONFIG\_FILE** Specifies a user config file which will be loaded automatically after the default config files at the first import of *ezdxf*. ### For Developers ### DXF Internals - • *DXF Reference* provided by Autodesk. - • *DXF Developer Documentation* provided by Autodesk. ### Basic DXF Structures ### DXF File Encoding ### DXF R2004 and prior Drawing files of DXF R2004 (AC1018) and prior are saved as ASCII files with the encoding set by the header variable $DWGCODEPAGE, which is **ANSI\_1252** by default if $DWGCODEPAGE is not set. Characters used in the drawing which do not exist in the chosen ASCII encoding are encoded as unicode characters with the schema **\\U+nnnn**. see *Unicode table* ### Known $DWGCODEPAGE encodings | | | | | --- | --- | --- | | DXF | Python | Name | | ANSI\_874 | cp874 | Thai | | ANSI\_932 | cp932 | Japanese | | ANSI\_936 | gbk | UnifiedChinese | | ANSI\_949 | cp949 | Korean | | ANSI\_950 | cp950 | TradChinese | | ANSI\_1250 | cp1250 | CentralEurope | | ANSI\_1251 | cp1251 | Cyrillic | | ANSI\_1252 | cp1252 | WesternEurope | | ANSI\_1253 | cp1253 | Greek | | ANSI\_1254 | cp1254 | Turkish | | ANSI\_1255 | cp1255 | Hebrew | | ANSI\_1256 | cp1256 | Arabic | | ANSI\_1257 | cp1257 | Baltic | | ANSI\_1258 | cp1258 | Vietnam | ### DXF R2007 and later Starting with DXF R2007 (AC1021) the drawing file is UTF-8 encoded, the header variable $DWGCODEPAGE is still in use, but I don’t know, if the setting still has any meaning. Encoding characters in the unicode schema **\\U+nnnn** is still functional. **SEE ALSO:** *String value encoding* ### DXF Tags A Drawing Interchange File is simply an ASCII text file with a file type of .dxf and special formatted text. The basic file structure are DXF tags, a DXF tag consist of a DXF group code as an integer value on its own line and a the DXF value on the following line. In the ezdxf documentation DXF tags will be written as (group code, value). With the introduction of extended symbol names in DXF R2000, the 255-character limit for strings has been increased to 2049 single-byte characters not including the newline at the end of the line. Nonetheless its safer to use only strings with 255 and less characters, because its not clear if this fact is true for ALL string group codes or only for symbols like layer- or text style names and not all 3rd party libraries may handle this fact correct. The MTEXT content and binary data is still divided into chunks with less than 255 characters. Group codes are indicating the value type: | | | | --- | --- | | Group Code | Value Type | | 0-9 | String | | 10-39 | Double precision 3D point value | | 40-59 | Double-precision floating-point value | | 60-79 | 16-bit integer value | | 90-99 | 32-bit integer value | | 100 | String | | 102 | String | | 105 | String representing hexadecimal (hex) handle value | | 110-119 | Double precision floating-point value | | 120-129 | Double precision floating-point value | | 130-139 | Double precision floating-point value | | 140-149 | Double precision scalar floating-point value | | 160-169 | 64-bit integer value | | 170-179 | 16-bit integer value | | 210-239 | Double-precision floating-point value | | 270-279 | 16-bit integer value | | 280-289 | 16-bit integer value | | 290-299 | Boolean flag value | | 300-309 | Arbitrary text string | | 310-319 | String representing hex value of binary chunk | | 320-329 | Arbitrary pointer, hex object ID, not translated during INSERT and XREF operations | | 330-339 | Soft-pointer, hex object ID, translated during INSERT and XREF operations | | 340-349 | Hard-pointer, hex object ID, translated during INSERT and XREF operations | | 350-359 | Soft-owner, hex object ID, translated during INSERT and XREF operations | | 360-369 | Hard-owner, hex object ID, translated during INSERT and XREF operations | | 370-379 | 16-bit integer value | | 380-389 | 16-bit integer value | | 390-399 | String representing hex handle value | | 400-409 | 16-bit integer value | | 410-419 | String | | 420-429 | 32-bit integer value | | 430-439 | String | | 440-449 | 32-bit integer value | | 450-459 | Long | | 460-469 | Double-precision floating-point value | | 470-479 | String | | 480-481 | Hard-pointer, hex object ID, translated during INSERT and XREF operations | | 999 | Comment (string) | | 1000-1009 | String | | 1010-1059 | Double-precision floating-point value | | 1060-1070 | 16-bit integer value | | 1071 | 32-bit integer value | Explanation for some important group codes: | | | | --- | --- | | Group Code | Meaning | | 0 | DXF structure tag, entity start/end or table entries | | 1 | The primary text value for an entity | | 2 | A name: Attribute tag, Block name, and so on. Also used to identify a DXF section or table name. | | 3-4 | Other textual or name values | | 5 | Entity handle as hex string (fixed) | | 6 | Line type name (fixed) | | 7 | Text style name (fixed) | | 8 | Layer name (fixed) | | 9 | Variable name identifier (used only in HEADER section of the DXF file) | | 10 | Primary X coordinate (start point of a Line or Text entity, center of a Circle, etc.) | | 11-18 | Other X coordinates | | 20 | Primary Y coordinate. 2n values always correspond to 1n values and immediately follow them in the file (expected by ezdxf!) | | 21-28 | Other Y coordinates | | 30 | Primary Z coordinate. 3n values always correspond to 1n and 2n values and immediately follow them in the file (expected by ezdxf!) | | 31-38 | Other Z coordinates | | 39 | This entity’s thickness if nonzero (fixed) | | 40-48 | Float values (text height, scale factors, etc.) | | 49 | Repeated value - multiple 49 groups may appear in one entity for variable length tables (such as the dash lengths in the LTYPE table). A 7x group always appears before the first 49 group to specify the table length | | 50-58 | Angles in degree | | 62 | Color number (fixed) | | 66 | “Entities follow” flag (fixed), only in INSERT and POLYLINE entities | | 67 | Identifies whether entity is in modelspace (0) or paperspace (1) | | 68 | Identifies whether viewport is on but fully off screen, is not active, or is off | | 69 | Viewport identification number | | 70-78 | Integer values such as repeat counts, flag bits, or modes | | 105 | DIMSTYLE entity handle as hex string (fixed) | | 210, 220, 230 | X, Y, and Z components of extrusion direction (fixed) | | 310 | Proxy entity graphics as binary encoded data | | 330 | Owner handle as hex string | | 347 | MATERIAL handle as hex string | | 348 | VISUALSTYLE handle as hex string | | 370 | Lineweight in mm times 100 (e.g. 0.13mm = 13). | | 390 | PLOTSTYLE handle as hex string | | 420 | True color value as 0x00RRGGBB 24-bit value | | 430 | Color name as string | | 440 | Transparency value 0x020000TT 0 = fully transparent / 255 = opaque | | 999 | Comments | For explanation of all group codes see: *DXF Group Codes in Numerical Order Reference* provided by Autodesk ### Extended Data *DXF R2018 Reference* Extended data (XDATA) is created by AutoLISP or ObjectARX applications but any other application like *ezdxf* can also define XDATA. If an entity contains extended data, it **follows** the entity’s normal definition. But extended group codes (\>=1000) can appear **before** the XDATA section, an example is the BLOCKBASEPOINTPARAMETER entity in AutoCAD Civil 3D or AutoCAD Map 3D. | | | | --- | --- | | Group Code | Description | | 1000 | Strings in extended data can be up to 255 bytes long (with the 256th byte reserved for the null character) | | 1001 | (fixed) Registered application name (ASCII string up to 31 bytes long) for XDATA | | 1002 | (fixed) An extended data control string can be either **'{'** or **'}'**. These braces enable applications to organize their data by subdividing the data into lists. Lists can be nested. | | 1003 | Name of the layer associated with the extended data | | 1004 | Binary data is organized into variable-length chunks. The maximum length of each chunk is 127 bytes. In ASCII DXF files, binary data is represented as a string of hexadecimal digits, two per binary byte | | 1005 | Database Handle of entities in the drawing database, see also: *About 1005 Group Codes* | | 1010, 1020, 1030 | Three real values, in the order X, Y, Z. They can be used as a point or vector record that will not be modified at any transformation of the entity. | | 1011, 1021, 1031 | a WCS point that is moved, scaled, rotated and mirrored along with the entity | | 1012, 1012, 1022 | a WCS displacement that is scaled, rotated and mirrored along with the entity, but is not moved | | 1013, 1023, 1033 | a WCS direction that is rotated and mirrored along with the entity, but is not moved or scaled | | 1040 | A real value | | 1041 | Distance, a real value that is scaled along with the parent entity | | 1042 | Scale Factor, also a real value that is scaled along with the parent. The difference between a distance and a scale factor is application-defined | | 1070 | A 16-bit integer (signed or unsigned) | | 1071 | A 32-bit signed (long) integer | The (1001, …) tag indicates the beginning of extended data. In contrast to normal entity data, with extended data the same group code can appear multiple times, and **order is important**. Extended data is grouped by registered application name. Each registered application group begins with a (1001, APPID) tag, with the application name as APPID string value. Registered application names correspond to APPID symbol table entries. An application can use as many APPID names as needed. APPID names are permanent, although they can be purged if they aren’t currently used in the drawing. Each APPID name can have **no more than one data group** attached to each entity. Within an application group, the sequence of extended data groups and their meaning is defined by the application. ### String value encoding String values stored in a DXF file is plain ASCII or UTF-8, AutoCAD also supports CIF (Common Interchange Format) and MIF (Maker Interchange Format) encoding. The UTF-8 format is only supported in DXF R2007 and later. Ezdxf on import converts all strings into Python unicode strings without encoding or decoding CIF/MIF. String values containing Unicode characters are represented with control character sequences **\\U+nnnn**. (e.g. **r'TEST\\U+7F3A\\U+4E4F\\U+89E3\\U+91CA\\U+6B63THIS\\U+56FE'**) To support the DXF unicode encoding ezdxf registers an encoding codec *dxf\_backslash\_replace*, defined in **ezdxf.lldxf.encoding()**. String values can be stored with these dxf group codes: - • 0 - 9 - • 100 - 101 - • 300 - 309 - • 410 - 419 - • 430 - 439 - • 470 - 479 - • 999 - 1003 ### Multi tag text (MTEXT) If the text string is less than 250 characters, all characters appear in tag (1, …). If the text string is longer than 250 characters, the string is divided into 250-character chunks, which appear in one or more (3, …) tags. If (3, …) tags are used, the last group is a (1, …) tag and has fewer than 250 characters: ``` 3 ... TwoHundredAndFifty Characters .... 3 ... TwoHundredAndFifty Characters .... 1 less than TwoHundredAndFifty Characters ``` As far I know this is only supported by the MTEXT entity. **SEE ALSO:** *DXF File Encoding* ### DXF R13 and later tag structure With the introduction of DXF R13 Autodesk added additional group codes and DXF tag structures to the DXF Standard. ### Subclass Markers Subclass markers (100, Subclass Name) divides DXF objects into several sections. Group codes can be reused in different sections. A subclass ends with the following subclass marker or at the beginning of xdata or the end of the object. See *Subclass Marker Example* in the DXF Reference. ### Quote about group codes from the DXF reference Some group codes that define an entity always appear; others are optional and appear only if their values differ from the defaults. **Do not** write programs that **rely on the order given here**. The end of an entity is indicated by the next 0 group, which begins the next entity or indicates the end of the section. **Note:** Accommodating DXF files from future releases of AutoCAD will be easier if you write your DXF processing program in a table-driven way, ignore undefined group codes, and make no assumptions about the order of group codes in an entity. With each new AutoCAD release, new group codes will be added to entities to accommodate additional features. ### Usage of group codes in subclasses twice Some later entities entities contains the same group code twice for different purposes, so order in the sense of which one comes first is important. (e.g. ATTDEF group code 280) ### Tag order is sometimes important especially for AutoCAD In LWPOLYLINE the order of tags is important, if the *count* tag is not the first tag in the AcDbPolyline subclass, AutoCAD will not close the polyline when the *close* flag is set, by the way other applications like BricsCAD ignores the tag order and renders the polyline always correct. ### Extension Dictionary The extension dictionary is an optional sequence that stores the handle of a DICTIONARY object that belongs to the current object, which in turn may contain entries. This facility allows attachment of arbitrary database objects to any database object. Any object or entity may have this section. The extension dictionary tag sequence: ``` 102 {ACAD_XDICTIONARY 360 Hard-owner ID/handle to owner dictionary 102 } ``` ### Persistent Reactors Persistent reactors are an optional sequence that stores object handles of objects registering themselves as reactors on the current object. Any object or entity may have this section. The persistent reactors tag sequence: ``` 102 {ACAD_REACTORS 330 first Soft-pointer ID/handle to owner dictionary 330 second Soft-pointer ID/handle to owner dictionary ... 102 } ``` ### Application-Defined Codes Starting at DXF R13, DXF objects can contain application-defined codes outside of XDATA. This application-defined codes can contain any tag except (0, …) and (102, ‘{…’). “{YOURAPPID” means the APPID string with an preceding “{”. The application defined data tag sequence: ``` 102 {YOURAPPID ... 102 } ``` **(102, 'YOURAPPID}')** is also a valid closing tag: ``` 102 {YOURAPPID ... 102 YOURAPPID} ``` All groups defined with a beginning (102, …) appear in the DXF reference before the first subclass marker, I don’t know if these groups can appear after the first or any subclass marker. Ezdxf accepts them at any position, and by default ezdxf adds new app data in front of the first subclass marker to the first tag section of an DXF object. **Exception XRECORD:** Tags with group code 102 and a value string without a preceding “{” or the scheme “YOURAPPID}”, should be treated as usual group codes. ### Embedded Objects The concept of embedded objects was introduced with AutoCAD 2018 (DXF version AC1032) and this is the only information I found about it at the Autodesk knowledge base: *Embedded and Encapsulated Objects* Quote from *Embedded and Encapsulated Objects*: For DXF filing, the embedded object must be filed out and in after all the data of the encapsulating object has been filed out and in. A separator is needed between the encapsulating object’s data and the subsequent embedded object’s data. The separator must be similar in function to the group 0 or 100 in that it must cause the filer to stop reading data. The normal DXF group code 0 cannot be used because DXF proxies use it to determine when to stop reading data. The group code 100 could have been used, but it might have caused confusion when manually reading a DXF file, and there was a need to distinguish when an embedded object is about to be written out in order to do some internal bookkeeping. Therefore, the DXF group code 101 was introduced. **Hard facts:** - • Only used in ATTRIB, ATTDEF (embedded MTEXT) and MTEXT (columns) in DXF R2018. - • Embedded object start with (101, “Embedded Object”) tag - • Embedded object is appended to the encapsulated object - • Embedded object tags can contain any group code except the DXF structure tag (0, …) **Unconfirmed assumptions:** - • The embedded object is written before the *Extended Data*. No examples for entities including embedded objects and XDATA at the same time. - • XDATA sections replaced by embedded objects, at least for the MTEXT entity - • The encapsulating object can contain more than one embedded object. - • Embedded objects separated by (101, “Embedded Object”) tags - • every entity can contain embedded objects Real world example from an AutoCAD 2018 file: ``` 100 <<< start of encapsulating object AcDbMText 10 2762.148 20 2327.073 30 0.0 40 2.5 41 18.852 46 0.0 71 1 72 5 1 {\fArial|b0|i0|c162|p34;CHANGE;\P\P\PTEXT} 73 1 44 1.0 101 <<< start of embedded object Embedded Object 70 1 10 1.0 20 0.0 30 0.0 11 2762.148 21 2327.073 31 0.0 40 18.852 41 0.0 42 15.428 43 15.043 71 2 72 1 44 18.852 45 12.5 73 0 74 0 46 0.0 ``` ### Handles A handle is an arbitrary but in your DXF file unique hex value as string like ‘10FF’. It is common to to use uppercase letters for hex numbers. Handle can have up to 16 hexadecimal digits (8 bytes). For DXF R10 until R12 the usage of handles was optional. The header variable $HANDLING set to 1 indicate the usage of handles, else $HANDLING is 0 or missing. For DXF R13 and later the usage of handles is mandatory and the header variable $HANDLING was removed. The $HANDSEED variable in the header section should be greater than the biggest handle used in the DXF file, so a CAD application can assign handle values starting with the $HANDSEED value. But as always, don’t rely on the header variable it could be wrong, AutoCAD ignores this value. ### Handle Definition Entity handle definition is always the **(5, ...)**, except for entities of the DIMSTYLE table **(105, ...)**, because the DIMSTYLE entity has also a group code 5 tag for DIMBLK. ### Handle Pointer A pointer is a reference to a DXF object in the same DXF file. There are four types of pointers: - • Soft-pointer handle - • Hard-pointer handle - • Soft-owner handle - • Hard-owner handle Also, a group code range for “arbitrary” handles is defined to allow convenient storage of handle values that are unchanged at any operation (AutoCAD). ### Pointer and Ownership A pointer is a reference that indicates usage, but not possession or responsibility, for another object. A pointer reference means that the object uses the other object in some way, and shares access to it. An ownership reference means that an owner object is responsible for the objects for which it has an owner handle. An object can have any number of pointer references associated with it, but it can have only one owner. ### Hard and Soft References Hard references, whether they are pointer or owner, protect an object from being purged. Soft references do not. In AutoCAD, block definitions and complex entities are hard owners of their elements. A symbol table and dictionaries are soft owners of their elements. Polyline entities are hard owners of their vertex and seqend entities. Insert entities are hard owners of their attrib and seqend entities. When establishing a reference to another object, it is recommended that you think about whether the reference should protect an object from the PURGE command. A hard- and soft pointers will be translated during INSERT and XREF operations. ### Arbitrary Handles Arbitrary handles are distinct in that they are not translated to session-persistent identifiers internally, or to entity names in AutoLISP, and so on. They are stored as handles. When handle values are translated in drawing-merge operations, arbitrary handles are ignored. In all environments, arbitrary handles can be exchanged for entity names of the current drawing by means of the handent functions. A common usage of arbitrary handles is to refer to objects in external DXF and DWG files. ### About 1005 Group Codes **(1005, ...)** xdata have the same behavior and semantics as soft pointers, which means that they are translated whenever the host object is merged into a different drawing. However, 1005 items are not translated to session-persistent identifiers or internal entity names in AutoLISP and ObjectARX. They are stored as handles. When a drawing with handles and extended data handles is imported into another drawing using INSERT, INSERT *, XREF Bind, XBIND, or partial OPEN, the extended* *data handles are \*\*translated\** in the same manner as their corresponding entity handles, thus maintaining their binding. This is also done in the EXPLODE block operation or for any other AutoCAD operation. When AUDIT detects an extended data handle that doesn’t match the handle of an entity in the drawing file, it is considered an error. If AUDIT is fixing entities, it sets the handle to “0” ### DXF File Structure A DXF File is simply an ASCII text file with a file type of .dxf and special formatted text. The basic file structure are DXF tags, a DXF tag consist of a DXF group code as an integer value on its own line and a the DXF value on the following line. In the ezdxf documentation DXF tags will be written as **(group code, value)**. There exist a binary DXF format, but it seems that it is not often used and for reducing file size, zipping is much more efficient. *ezdxf* does support reading binary encoded DXF files. **SEE ALSO:** For more information about DXF tags see: *DXF Tags* A usual DXF file is organized in sections, starting with the DXF tag (0, ‘SECTION’) and ending with the DXF tag (0, ‘ENDSEC’). The (0, ‘EOF’) tag signals the end of file. - 1\. **HEADER:** General information about the drawing is found in this section of the DXF file. Each parameter has a variable name starting with ‘$’ and an associated value. Has to be the first section. - 2\. **CLASSES:** Holds the information for application defined classes. (DXF R13 and later) - 3\. **TABLES:**: Contains several tables for style and property definitions. - • Linetype table (LTYPE) - • Layer table (LAYER) - • Text Style table (STYLE) - • View table (VIEW): (IMHO) layout of the CAD working space, only interesting for interactive CAD applications - • Viewport configuration table (VPORT): The VPORT table is unique in that it may contain several entries with the same name (indicating a multiple-viewport configuration). The entries corresponding to the active viewport configuration all have the name \*ACTIVE. The first such entry describes the current viewport. - • Dimension Style table (DIMSTYLE) - • User Coordinate System table (UCS) (IMHO) only interesting for interactive CAD applications - • Application Identification table (APPID): Table of names for all applications registered with a drawing. - • Block Record table (BLOCK\_RECORD) (DXF R13 and Later) - 4\. **BLOCKS:** Contains all block definitions. The block name \*Model\_Space or \*MODEL\_SPACE is reserved for the drawing modelspace and the block name \*Paper\_Space or \*PAPER\_SPACE is reserved for the *active* paperspace layout. Both block definitions are empty, the content of the modelspace and the *active* paperspace is stored in the ENTITIES section. The entities of other layouts are stored in special block definitions called \*Paper\_Spacennn, nnn is an arbitrary but unique number. - 5\. **ENTITIES:** Contains all graphical entities of the modelspace and the *active* paperspace layout. Entities of other layouts are stored in the BLOCKS sections. - 6\. **OBJECTS:** Contains all non-graphical objects of the drawing (DXF R13 and later) - 7\. **THUMBNAILIMAGE:** Contains a preview image of the DXF file, it is optional and can usually be ignored. (DXF R13 and later) - 8\. **ACDSDATA:** (DXF R2013 and later) No information in the DXF reference about this section - 9\. **END OF FILE** For further information read the original *DXF Reference*. Structure of a usual DXF R12 file: ``` 0 <<< Begin HEADER section, has to be the first section SECTION 2 HEADER <<< Header variable items go here 0 <<< End HEADER section ENDSEC 0 <<< Begin TABLES section SECTION 2 TABLES 0 TABLE 2 VPORT 70 <<< viewport table maximum item count <<< viewport table items go here 0 ENDTAB 0 TABLE 2 APPID, DIMSTYLE, LTYPE, LAYER, STYLE, UCS, VIEW, or VPORT 70 <<< Table maximum item count, a not reliable value and ignored by AutoCAD <<< Table items go here 0 ENDTAB 0 <<< End TABLES section ENDSEC 0 <<< Begin BLOCKS section SECTION 2 BLOCKS <<< Block definition entities go here 0 <<< End BLOCKS section ENDSEC 0 <<< Begin ENTITIES section SECTION 2 ENTITIES <<< Drawing entities go here 0 <<< End ENTITIES section ENDSEC 0 <<< End of file marker (required) EOF ``` ### Minimal DXF Content ### DXF R12 Contrary to the previous chapter, the DXF R12 format (AC1009) and prior requires just the ENTITIES section: ``` 0 SECTION 2 ENTITIES 0 ENDSEC 0 EOF ``` ### DXF R13/R14 and later DXF version R13/14 and later needs much more DXF content than DXF R12. Required sections: HEADER, CLASSES, TABLES, ENTITIES, OBJECTS The HEADER section requires two entries: - • $ACADVER - • $HANDSEED The CLASSES section can be empty, but some DXF entities requires class definitions to work in AutoCAD. The TABLES section requires following tables: - • VPORT entry \*ACTIVE is not required! Empty table is ok for AutoCAD. - • LTYPE with at least the following line types defined: - • BYBLOCK - • BYLAYER - • CONTINUOUS - • LAYER with at least an entry for layer ‘0’ - • STYLE with at least an entry for style STANDARD - • VIEW can be empty - • UCS can be empty - • APPID with at least an entry for ACAD - • DIMSTYLE with at least an entry for style STANDARD - • BLOCK\_RECORDS with two entries: - • \*MODEL\_SPACE - • \*PAPER\_SPACE The BLOCKS section requires two BLOCKS: - • \*MODEL\_SPACE - • \*PAPER\_SPACE The ENTITIES section can be empty. The OBJECTS section requires following entities: - • DICTIONARY - the root dict - one entry named ACAD\_GROUP - • DICTIONARY ACAD\_GROUP can be empty Minimal DXF to download: *https://github.com/mozman/ezdxf/tree/master/examples\_dxf* ### Data Model ### Database Objects (from the DXF Reference) AutoCAD drawings consist largely of structured containers for database objects. Database objects each have the following features: - • A handle whose value is unique to the drawing/DXF file, and is constant for the lifetime of the drawing. This format has existed since AutoCAD Release 10, and as of AutoCAD Release 13, handles are always enabled. - • An optional XDATA table, as entities have had since AutoCAD Release 11. - • An optional persistent reactor table. - • An optional ownership pointer to an extension dictionary which, in turn, owns subobjects placed in it by an application. Symbol tables and symbol table records are database objects and, thus, have a handle. They can also have xdata and persistent reactors in their DXF records. ### DXF R12 Data Model The DXF R12 data model is identical to the file structure: - • HEADER section: common settings for the DXF drawing - • TABLES section: definitions for LAYERS, LINETYPE, STYLES …. - • BLOCKS section: block definitions and its content - • ENTITIES section: modelspace and paperspace content References are realized by simple names. The INSERT entity references the BLOCK definition by the BLOCK name, a TEXT entity defines the associated STYLE and LAYER by its name and so on, handles are not needed. Layout association of graphical entities in the ENTITIES section by the paper\_space tag **(67, 0 or 1)**, 0 or missing tag means modelspace, 1 means paperspace. The content of BLOCK definitions is enclosed by the BLOCK and the ENDBLK entity, no additional references are needed. A clean and simple file structure and data model, which seems to be the reason why the DXF R12 Reference (released 1992) is still a widely used file format and Autodesk/AutoCAD supports the format by reading and writing DXF R12 files until today (DXF R13/R14 has no writing support by AutoCAD!). **TODO: list of available entities** **SEE ALSO:** More information about the DXF *DXF File Structure* ### DXF R13+ Data Model With the DXF R13 file format, handles are mandatory and they are really used for organizing the new data structures introduced with DXF R13. The HEADER section is still the same with just more available settings. The new CLASSES section contains AutoCAD specific data, has to be written like AutoCAD it does, but must not be understood. The TABLES section got a new BLOCK\_RECORD table - see *Block Management Structures* for more information. The BLOCKS sections is mostly the same, but with handles, owner tags and new ENTITY types. Not active paperspace layouts store their content also in the BLOCKS section - see *Layout Management Structures* for more information. The ENTITIES section is also mostly same, but with handles, owner tags and new ENTITY types. **TODO: list of new available entities** And the new OBJECTS section - now its getting complicated! Most information about the OBJECTS section is just guessed or gathered by trail and error, because the documentation of the OBJECTS section and its objects in the DXF reference provided by Autodesk is very shallow. This is also the reason why I started the DXF Internals section, may be it helps other developers to start one or two steps above level zero. The OBJECTS sections stores all the non-graphical entities of the DXF drawing. Non-graphical entities from now on just called ‘DXF objects’ to differentiate them from graphical entities, just called ‘entities’. The OBJECTS section follows commonly the ENTITIES section, but this is not mandatory. DXF R13 introduces several new DXF objects, which resides exclusive in the OBJECTS section, taken from the DXF R14 reference, because I have no access to the DXF R13 reference, the DXF R13 reference is a compiled .hlp file which can’t be read on Windows 10 or later, this a perfect example for not using closed (proprietary) data formats ;): - • DICTIONARY: a general structural entity as a \ container - • ACDBDICTIONARYWDFLT: a DICTIONARY with a default value - • DICTIONARYVAR: used by AutoCAD to store named values in the database - • ACAD\_PROXY\_OBJECT: proxy object for entities created by other applications than AutoCAD - • GROUP: groups graphical entities without the need of a BLOCK definition - • IDBUFFER: just a list of references to objects - • IMAGEDEF: IMAGE definition structure, required by the IMAGE entity - • IMAGEDEF\_REACTOR: also required by the IMAGE entity - • LAYER\_INDEX: container for LAYER names - • MLINESTYLE - • OBJECT\_PTR - • RASTERVARIABLES - • SPATIAL\_INDEX: is always written out empty to a DXF file. This object can be ignored. - • SPATIAL\_FILTER - • SORTENTSTABLE: control for regeneration/redraw order of entities - • XRECORD: used to store and manage arbitrary data. This object is similar in concept to XDATA but is not limited by size or order. Not supported by R13c0 through R13c3. Still missing the LAYOUT object, which is mandatory in DXF R2000 to manage multiple paperspace layouts. I don’t know how DXF R13/R14 manages multiple layouts or if they even support this feature, but I don’t care much about DXF R13/R14, because AutoCAD has no write support for this two formats anymore. Ezdxf tries to upgrade this two DXF versions to DXF R2000 with the advantage of only two different data models to support: DXF R12 and DXF R2000+ New objects introduced by DXF R2000: - • LAYOUT: management object for modelspace and multiple paperspace layouts - • ACDBPLACEHOLDER: surprise - just a place holder New objects in DXF R2004: - • DIMASSOC - • LAYER\_FILTER - • MATERIAL - • PLOTSETTINGS - • VBA\_PROJECT New objects in DXF R2007: - • DATATABLE - • FIELD - • LIGHTLIST - • RENDER - • RENDERENVIRONMENT - • MENTALRAYRENDERSETTINGS - • RENDERGLOBAL - • SECTION - • SUNSTUDY - • TABLESTYLE - • UNDERLAYDEFINITION - • VISUALSTYLE - • WIPEOUTVARIABLES New objects in DXF R2013: - • GEODATA New objects in DXF R2018: - • ACDBNAVISWORKSMODELDEF Undocumented objects: - • SCALE - • ACDBSECTIONVIEWSTYLE - • FIELDLIST ### Objects Organisation Many objects in the OBJECTS section are organized in a tree-like structure of DICTIONARY objects. Starting point for this data structure is the ‘root’ DICTIONARY with several entries to other DICTIONARY objects. The root DICTIONARY has to be the first object in the OBJECTS section. The management dicts for GROUP and LAYOUT objects are really important, but IMHO most of the other management tables are optional and for the most use cases not necessary. Ezdxf creates only these entries in the root dict and most of them pointing to an empty DICTIONARY: - • ACAD\_COLOR: points to an empty DICTIONARY - • ACAD\_GROUP: required - • ACAD\_LAYOUT: required - • ACAD\_MATERIAL: points to an empty DICTIONARY - • ACAD\_MLEADERSTYLE: points to an empty DICTIONARY - • ACAD\_MLINESTYLE: points to an empty DICTIONARY - • ACAD\_PLOTSETTINGS: points to an empty DICTIONARY - • ACAD\_PLOTSTYLENAME: required, points to ACDBDICTIONARYWDFLT with one entry: ‘Normal’ - • ACAD\_SCALELIST: points to an empty DICTIONARY - • ACAD\_TABLESTYLE: points to an empty DICTIONARY - • ACAD\_VISUALSTYLE: points to an empty DICTIONARY ### Root DICTIONARY content for DXF R2018 ``` 0 SECTION 2 <<< start of the OBJECTS section OBJECTS 0 <<< root DICTIONARY has to be the first object in the OBJECTS section DICTIONARY 5 <<< handle C 330 <<< owner tag 0 <<< always #0, has no owner 100 AcDbDictionary 281 <<< hard owner flag 1 3 <<< first entry ACAD_CIP_PREVIOUS_PRODUCT_INFO 350 <<< handle to target (pointer) 78B <<< points to a XRECORD with product info about the creator application 3 <<< entry with unknown meaning, if I should guess: something with about colors ... ACAD_COLOR 350 4FB <<< points to a DICTIONARY 3 <<< entry with unknown meaning ACAD_DETAILVIEWSTYLE 350 7ED <<< points to a DICTIONARY 3 <<< GROUP management, mandatory in all DXF versions ACAD_GROUP 350 4FC <<< points to a DICTIONARY 3 <<< LAYOUT management, mandatory if more than the *active* paperspace is used ACAD_LAYOUT 350 4FD <<< points to a DICTIONARY 3 <<< MATERIAL management ACAD_MATERIAL 350 4FE <<< points to a DICTIONARY 3 <<< MLEADERSTYLE management ACAD_MLEADERSTYLE 350 4FF <<< points to a DICTIONARY 3 <<< MLINESTYLE management ACAD_MLINESTYLE 350 500 <<< points to a DICTIONARY 3 <<< PLOTSETTINGS management ACAD_PLOTSETTINGS 350 501 <<< points to a DICTIONARY 3 <<< plot style name management ACAD_PLOTSTYLENAME 350 503 <<< points to a ACDBDICTIONARYWDFLT 3 <<< SCALE management ACAD_SCALELIST 350 504 <<< points to a DICTIONARY 3 <<< entry with unknown meaning ACAD_SECTIONVIEWSTYLE 350 7EB <<< points to a DICTIONARY 3 <<< TABLESTYLE management ACAD_TABLESTYLE 350 505 <<< points to a DICTIONARY 3 <<< VISUALSTYLE management ACAD_VISUALSTYLE 350 506 <<< points to a DICTIONARY 3 <<< entry with unknown meaning ACDB_RECOMPOSE_DATA 350 7F3 3 <<< entry with unknown meaning AcDbVariableDictionary 350 7AE <<< points to a DICTIONARY with handles to DICTIONARYVAR objects 0 DICTIONARY ... ... 0 ENDSEC ``` ### DXF Structures ### DXF Sections ### HEADER Section In DXF R12 and prior the HEADER section was optional, but since DXF R13 the HEADER section is mandatory. The overall structure is: ``` 0 <<< Begin HEADER section SECTION 2 HEADER 9 $ACADVER <<< Header variable items go here 1 AC1009 ... 0 ENDSEC <<< End HEADER section ``` A header variable has a name defined by a **(9, Name)** tag and following value tags. **SEE ALSO:** Documentation of *ezdxf* *HeaderSection* class. DXF Reference: *Header Variables* ### CLASSES Section The CLASSES section contains CLASS definitions which are only important for Autodesk products, some DXF entities require a class definition or AutoCAD will not open the DXF file. The CLASSES sections was introduced with DXF AC1015 (AutoCAD Release R13). **SEE ALSO:** DXF Reference: *About the DXF CLASSES Section* Documentation of *ezdxf* *ClassesSection* class. The CLASSES section in DXF files holds the information for application-defined classes whose instances appear in the BLOCKS, ENTITIES, and OBJECTS sections of the database. It is assumed that a class definition is permanently fixed in the class hierarchy. All fields are required. **Update 2019-03-03:** Class names are not unique, Autodesk Architectural Desktop 2007 uses the same name, but with different CPP class names in the CLASS section, so storing classes in a dictionary by name as key caused loss of class entries in ezdxf, using a tuple of (name, cpp\_class\_name) as storage key solved the problem. ### CLASS Entities **SEE ALSO:** DXF Reference: *Group Codes for the CLASS entity* CLASS entities have no handle and therefore ezdxf does not store the CLASS entity in the drawing entities database! ``` 0 SECTION 2 <<< begin CLASSES section CLASSES 0 <<< first CLASS entity CLASS 1 <<< class DXF entity name; THIS ENTRY IS MAYBE NOT UNIQUE ACDBDICTIONARYWDFLT 2 <<< C++ class name; always unique AcDbDictionaryWithDefault 3 <<< application name ObjectDBX Classes 90 <<< proxy capabilities flags 0 91 <<< instance counter for custom class, since DXF version AC1018 (R2004) 0 <<< no problem if the counter is wrong, AutoCAD doesn't care about 280 <<< was-a-proxy flag: 1= class was not loaded when this DXF file was created 0 <<< 0= otherwise 281 <<< is-an-entity flag: 1= instances reside in the BLOCKS or ENTITIES section 0 <<< 0= instances may appear only in the OBJECTS section 0 <<< next CLASS entity CLASS ... 0 <<< end of CLASSES section ENDSEC ``` ### TABLES Section The TABLES section contains the resource tables of a DXF document. ### APPID Table The *APPID* table stores unique application identifiers. These identifiers are used to mark sub-sections in the XDATA section of DXF entities. AutoCAD will not load DXF files which uses AppIDs without an entry in the AppIDs table and the “ACAD” entry must always exist. Some known AppIDs: | | | | | --- | --- | --- | | APPID | Used by | Description | | ACAD | Autodesk | various use cases | | AcAecLayerStandard | Autodesk | layer description | | AcCmTransparency | Autodesk | layer transparency | | HATCHBACKGROUNDCOLOR | Autodesk | background color for pattern fillings | | EZDXF | ezdxf | meta data | **SEE ALSO:** - • DXF Reference: *TABLES Section* - • DXF Reference: *APPID* Table - • *AppID* class ### Table Structure DXF R12 ``` 0 <<< start of table TABLE 2 <<< table type APPID 70 <<< count of table entries, AutoCAD ignores this value 3 0 <<< 1. table entry APPID 2 <<< unique application identifier ACAD 70 <<< flags, see `APPID`_ reference 0 <<< in common cases always 0 0 <<< next table entry APPID ... 0 <<< end of APPID table ENDTAB ``` ### Table Structure DXF R2000+ ``` 0 <<< start of table TABLE 2 <<< table type APPID 5 <<< table handle 3 330 <<< owner tag, tables have no owner 0 100 <<< subclass marker AcDbSymbolTable 70 <<< count of table entries, AutoCAD ignores this value 3 0 <<< first table entry APPID 5 <<< handle of appid 2A 330 <<< owner handle, handle of APPID table 3 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbRegAppTableRecord 2 <<< unique application identifier ACAD 70 <<< flags, see `APPID`_ reference 0 <<< in common cases always 0 0 <<< next table entry APPID ... 0 <<< end of APPID table ENDTAB ``` ### Name References APPID table entries are referenced by name: - • XDATA section of DXF entities ### BLOCK\_RECORD Table Block records are essential elements for the entities management, each layout (modelspace and paperspace) and every block definition has a block record entry. This block record is the hard *owner* of the entities of layouts, each entity has an owner handle which points to a block record of the layout. ### DIMSTYLE Table The *DIMSTYLE* table stores all dimension style definitions of a DXF drawing. You have access to the dimension styles table by the attribute **Drawing.dimstyles**. **SEE ALSO:** - • DXF Reference: *TABLES Section* - • DXF Reference: *DIMSTYLE* Table ### Table Structure DXF R12 ``` 0 <<< start of table TABLE 2 <<< set table type DIMSTYLE 70 <<< count of line types defined in this table, AutoCAD ignores this value 9 0 <<< 1. DIMSTYLE table entry DIMSTYLE <<< DIMSTYLE data tags 0 <<< 2. DIMSTYLE table entry DIMSTYLE <<< DIMSTYLE data tags and so on 0 <<< end of DIMSTYLE table ENDTAB ``` ### DIMSTYLE Entry DXF R12 ### DIMSTYLE Variables DXF R12 Source: *CADDManager Blog* \[image\] \[image\] | | | | | --- | --- | --- | | DIMVAR | Code | Description | | DIMALT | 170 | Controls the display of alternate units in dimensions. | | DIMALTD | 171 | Controls the number of decimal places in alternate units. If DIMALT is turned on, DIMALTD sets the number of digits displayed to the right of the decimal point in the alternate measurement. | | DIMALTF | 143 | Controls the multiplier for alternate units. If DIMALT is turned on, DIMALTF multiplies linear dimensions by a factor to produce a value in an alternate system of measurement. The initial value represents the number of millimeters in an inch. | | DIMAPOST | 4 | Specifies a text prefix or suffix (or both) to the alternate dimension measurement for all types of dimensions except angular. For instance, if the current units are Architectural, DIMALT is on, DIMALTF is 25.4 (the number of millimeters per inch), DIMALTD is 2, and DIMPOST is set to “mm”, a distance of 10 units would be displayed as 10”\[254.00mm\]. | | DIMASZ | 41 | Controls the size of dimension line and leader line arrowheads. Also controls the size of hook lines. Multiples of the arrowhead size determine whether dimension lines and text should fit between the extension lines. DIMASZ is also used to scale arrowhead blocks if set by DIMBLK. DIMASZ has no effect when DIMTSZ is other than zero. | | DIMBLK | 5 | Sets the arrowhead block displayed at the ends of dimension lines. | | DIMBLK1 | 6 | Sets the arrowhead for the first end of the dimension line when DIMSAH is 1. | | DIMBLK2 | 7 | Sets the arrowhead for the second end of the dimension line when DIMSAH is 1. | | DIMCEN | 141 | Controls drawing of circle or arc center marks and centerlines by the DIMCENTER, DIMDIAMETER, and DIMRADIUS commands. For DIMDIAMETER and DIMRADIUS, the center mark is drawn only if you place the dimension line outside the circle or arc. 0 = No center marks or lines are drawn \<0 = Centerlines are drawn \>0 = Center marks are drawn | | DIMCLRD | 176 | Assigns colors to dimension lines, arrowheads, and dimension leader lines. 0 = BYBLOCK 1-255 = ACI AutoCAD Color Index 256 = BYLAYER | | DIMCLRE | 177 | Assigns colors to dimension extension lines, values like DIMCLRD | | DIMCLRT | 178 | Assigns colors to dimension text, values like DIMCLRD | | DIMDLE | 46 | Sets the distance the dimension line extends beyond the extension line when oblique strokes are drawn instead of arrowheads. | | DIMDLI | 43 | Controls the spacing of the dimension lines in baseline dimensions. Each dimension line is offset from the previous one by this amount, if necessary, to avoid drawing over it. Changes made with DIMDLI are not applied to existing dimensions. | | DIMEXE | 44 | Specifies how far to extend the extension line beyond the dimension line. | | DIMEXO | 42 | Specifies how far extension lines are offset from origin points. With fixed-length extension lines, this value determines the minimum offset. | | DIMGAP | 147 | Sets the distance around the dimension text when the dimension line breaks to accommodate dimension text. Also sets the gap between annotation and a hook line created with the LEADER command. If you enter a negative value, DIMGAP places a box around the dimension text. DIMGAP is also used as the minimum length for pieces of the dimension line. When the default position for the dimension text is calculated, text is positioned inside the extension lines only if doing so breaks the dimension lines into two segments at least as long as DIMGAP. Text placed above or below the dimension line is moved inside only if there is room for the arrowheads, dimension text, and a margin between them at least as large as DIMGAP: 2 \* (DIMASZ + DIMGAP). | | DIMLFAC | 144 | Sets a scale factor for linear dimension measurements. All linear dimension distances, including radii, diameters, and coordinates, are multiplied by DIMLFAC before being converted to dimension text. Positive values of DIMLFAC are applied to dimensions in both modelspace and paperspace; negative values are applied to paperspace only. DIMLFAC applies primarily to nonassociative dimensions (DIMASSOC set 0 or 1). For nonassociative dimensions in paperspace, DIMLFAC must be set individually for each layout viewport to accommodate viewport scaling. DIMLFAC has no effect on angular dimensions, and is not applied to the values held in DIMRND, DIMTM, or DIMTP. | | DIMLIM | 72 | Generates dimension limits as the default text. Setting DIMLIM to On turns DIMTOL off. 0 = Dimension limits are not generated as default text 1 = Dimension limits are generated as default text | | DIMPOST | 3 | Specifies a text prefix or suffix (or both) to the dimension measurement. For example, to establish a suffix for millimeters, set DIMPOST to mm; a distance of 19.2 units would be displayed as 19.2 mm. If tolerances are turned on, the suffix is applied to the tolerances as well as to the main dimension. Use “\<\>” to indicate placement of the text in relation to the dimension value. For example, enter “\<\>mm” to display a 5.0 millimeter radial dimension as “5.0mm”. If you entered mm “\<\>”, the dimension would be displayed as “mm 5.0”. | | DIMRND | 45 | Rounds all dimensioning distances to the specified value. For instance, if DIMRND is set to 0.25, all distances round to the nearest 0.25 unit. If you set DIMRND to 1.0, all distances round to the nearest integer. Note that the number of digits edited after the decimal point depends on the precision set by DIMDEC. DIMRND does not apply to angular dimensions. | | DIMSAH | 173 | Controls the display of dimension line arrowhead blocks. 0 = Use arrowhead blocks set by DIMBLK 1 = Use arrowhead blocks set by DIMBLK1 and DIMBLK2 | | DIMSCALE | 40 | Sets the overall scale factor applied to dimensioning variables that specify sizes, distances, or offsets. Also affects the leader objects with the LEADER command. Use MLEADERSCALE to scale multileader objects created with the MLEADER command. 0.0 = A reasonable default value is computed based on the scaling between the current model space viewport and paperspace. If you are in paperspace or modelspace and not using the paperspace feature, the scale factor is 1.0. \>0 = A scale factor is computed that leads text sizes, arrowhead sizes, and other scaled distances to plot at their face values. DIMSCALE does not affect measured lengths, coordinates, or angles. Use DIMSCALE to control the overall scale of dimensions. However, if the current dimension style is annotative, DIMSCALE is automatically set to zero and the dimension scale is controlled by the CANNOSCALE system variable. DIMSCALE cannot be set to a non-zero value when using annotative dimensions. | | DIMSE1 | 75 | Suppresses display of the first extension line. 0 = Extension line is not suppressed 1 = Extension line is suppressed | | DIMSE2 | 76 | Suppresses display of the second extension line. 0 = Extension line is not suppressed 1 = Extension line is suppressed | | DIMSOXD | 175 | Suppresses arrowheads if not enough space is available inside the extension lines. 0 = Arrowheads are not suppressed 1 = Arrowheads are suppressed If not enough space is available inside the extension lines and DIMTIX is on, setting DIMSOXD to On suppresses the arrowheads. If DIMTIX is off, DIMSOXD has no effect. | | DIMTAD | 77 | Controls the vertical position of text in relation to the dimension line. 0 = Centers the dimension text between the extension lines. 1 = Places the dimension text above the dimension line except when the dimension line is not horizontal and text inside the extension lines is forced horizontal (DIMTIH = 1). The distance from the dimension line to the baseline of the lowest line of text is the current DIMGAP value. 2 = Places the dimension text on the side of the dimension line farthest away from the defining points. 3 = Places the dimension text to conform to Japanese Industrial Standards (JIS). 4 = Places the dimension text below the dimension line. | | DIMTFAC | 146 | Specifies a scale factor for the text height of fractions 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 DIMTFAC is set to 0.7500, the text height of fractions and tolerances is three-quarters the size of dimension text. | | DIMTIH | 73 | Controls the position of dimension text inside the extension lines for all dimension types except Ordinate. 0 = Aligns text with the dimension line 1 = Draws text horizontally | | DIMTIX | 174 | Draws text between extension lines. 0 = Varies with the type of dimension. For linear and angular dimensions, text is placed inside the extension lines if there is sufficient room. For radius and diameter dimensions hat don’t fit inside the circle or arc, DIMTIX has no effect and always forces the text outside the circle or arc. 1 = Draws dimension text between the extension lines even if it would ordinarily be placed outside those lines | | DIMTM | 48 | Sets the minimum (or lower) tolerance limit for dimension text when DIMTOL or DIMLIM is on. DIMTM accepts signed values. If DIMTOL is on and DIMTP and DIMTM are set to the same value, a tolerance value is drawn. If DIMTM and DIMTP values differ, the upper tolerance is drawn above the lower, and a plus sign is added to the DIMTP value if it is positive. For DIMTM, the program uses the negative of the value you enter (adding a minus sign if you specify a positive number and a plus sign if you specify a negative number). | | DIMTOFL | 172 | Controls whether a dimension line is drawn between the extension lines even when the text is placed outside. For radius and diameter dimensions (when DIMTIX is off), draws a dimension line inside the circle or arc and places the text, arrowheads, and leader outside. 0 = Does not draw dimension lines between the measured points when arrowheads are placed outside the measured points 1 = Draws dimension lines between the measured points even when arrowheads are placed outside the measured points | | DIMTOH | 74 | Controls the position of dimension text outside the extension lines. 0 = Aligns text with the dimension line 1 = Draws text horizontally | | DIMTOL | 71 | Appends tolerances to dimension text. Setting DIMTOL to on turns DIMLIM off. | | DIMTP | 47 | Sets the maximum (or upper) tolerance limit for dimension text when DIMTOL or DIMLIM is on. DIMTP accepts signed values. If DIMTOL is on and DIMTP and DIMTM are set to the same value, a tolerance value is drawn. If DIMTM and DIMTP values differ, the upper tolerance is drawn above the lower and a plus sign is added to the DIMTP value if it is positive. | | DIMTSZ | 142 | Specifies the size of oblique strokes drawn instead of arrowheads for linear, radius, and diameter dimensioning. 0 = Draws arrowheads. \>0 = Draws oblique strokes instead of arrowheads. The size of the oblique strokes is determined by this value multiplied by the DIMSCALE value | | DIMTVP | 145 | Controls the vertical position of dimension text above or below the dimension line. The DIMTVP value is used when DIMTAD = 0. The magnitude of the vertical offset of text is the product of the text height and DIMTVP. Setting DIMTVP to 1.0 is equivalent to setting DIMTAD = 1. The dimension line splits to accommodate the text only if the absolute value of DIMTVP is less than 0.7. | | DIMTXT | 140 | Specifies the height of dimension text, unless the current text style has a fixed height. | | DIMZIN | 78 | Controls the suppression of zeros in the primary unit value. Values 0-3 affect feet-and-inch dimensions only: 0 = Suppresses zero feet and precisely zero inches 1 = Includes zero feet and precisely zero inches 2 = Includes zero feet and suppresses zero inches 3 = Includes zero inches and suppresses zero feet 4 (Bit 3) = Suppresses leading zeros in decimal dimensions (for example, 0.5000 becomes .5000) 8 (Bit 4) = Suppresses trailing zeros in decimal dimensions (for example, 12.5000 becomes 12.5) 12 (Bit 3+4) = Suppresses both leading and trailing zeros (for example, 0.5000 becomes .5) | ### Table Structure DXF R2000+ ``` 0 <<< start of table TABLE 2 <<< set table type DIMSTYLE 5 <<< DIMSTYLE table handle 5F 330 <<< owner tag, tables has no owner 0 100 <<< subclass marker AcDbSymbolTable 70 <<< count of dimension styles defined in this table, AutoCAD ignores this value 9 0 <<< 1. DIMSTYLE table entry DIMSTYLE <<< DIMSTYLE data tags 0 <<< 2. DIMSTYLE table entry DIMSTYLE <<< DIMSTYLE data tags and so on 0 <<< end of DIMSTYLE table ENDTAB ``` ### Additional DIMSTYLE Variables DXF R13/14 Source: *CADDManager Blog* | | | | | --- | --- | --- | | DIMVAR | code | Description | | DIMADEC | 179 | Controls the number of precision places displayed in angular dimensions. | | DIMALTTD | 274 | Sets the number of decimal places for the tolerance values in the alternate units of a dimension. | | DIMALTTZ | 286 | Controls suppression of zeros in tolerance values. | | DIMALTU | 273 | Sets the units format for alternate units of all dimension substyles except Angular. | | DIMALTZ | 285 | Controls the suppression of zeros for alternate unit dimension values. DIMALTZ values 0-3 affect feet-and-inch dimensions only. | | DIMAUNIT | 275 | Sets the units format for angular dimensions. 0 = Decimal degrees 1 = Degrees/minutes/seconds 2 = Grad 3 = Radians | | DIMBLK\_HANDLE | 342 | defines DIMBLK as handle to the BLOCK RECORD entry | | DIMBLK1\_HANDLE | 343 | defines DIMBLK1 as handle to the BLOCK RECORD entry | | DIMBLK2\_HANDLE | 344 | defines DIMBLK2 as handle to the BLOCK RECORD entry | | DIMDEC | 271 | Sets the number of decimal places displayed for the primary units of a dimension. The precision is based on the units or angle format you have selected. | | DIMDSEP | 278 | Specifies a single-character decimal separator to use when creating dimensions whose unit format is decimal. When prompted, enter a single character at the Command prompt. If dimension units is set to Decimal, the DIMDSEP character is used instead of the default decimal point. If DIMDSEP is set to NULL (default value, reset by entering a period), the decimal point is used as the dimension separator. | | DIMJUST | 280 | Controls the horizontal positioning of dimension text. 0 = Positions the text above the dimension line and center-justifies it between the extension lines 1 = Positions the text next to the first extension line 2 = Positions the text next to the second extension line 3 = Positions the text above and aligned with the first extension line 4 = =Positions the text above and aligned with the second extension line | | DIMSD1 | 281 | Controls suppression of the first dimension line and arrowhead. When turned on, suppresses the display of the dimension line and arrowhead between the first extension line and the text. 0 = First dimension line is not suppressed 1 = First dimension line is suppressed | | DIMSD2 | 282 | Controls suppression of the second dimension line and arrowhead. When turned on, suppresses the display of the dimension line and arrowhead between the second extension line and the text. 0 = Second dimension line is not suppressed 1 = Second dimension line is suppressed | | DIMTDEC | 272 | Sets the number of decimal places to display in tolerance values for the primary units in a dimension. This system variable has no effect unless DIMTOL is set to On. The default for DIMTOL is Off. | | DIMTOLJ | 283 | Sets the vertical justification for tolerance values relative to the nominal dimension text. This system variable has no effect unless DIMTOL is set to On. The default for DIMTOL is Off. 0 = Bottom 1 = Middle 2 = Top | | DIMTXSTY\_HANDLE | 340 | Specifies the text style of the dimension as handle to STYLE table entry | | DIMTZIN | 284 | Controls the suppression of zeros in tolerance values. Values 0-3 affect feet-and-inch dimensions only. 0 = Suppresses zero feet and precisely zero inches 1 = Includes zero feet and precisely zero inches 2 = Includes zero feet and suppresses zero inches 3 = Includes zero inches and suppresses zero feet 4 = Suppresses leading zeros in decimal dimensions (for example, 0.5000 becomes .5000) 8 = Suppresses trailing zeros in decimal dimensions (for example, 12.5000 becomes 12.5) 12 = Suppresses both leading and trailing zeros (for example, 0.5000 becomes .5) | | DIMUPT | 288 | Controls options for user-positioned text. 0 = Cursor controls only the dimension line location 1 = Cursor controls both the text position and the dimension line location | ### Additional DIMSTYLE Variables DXF R2000 Source: *CADDManager Blog* | | | | | --- | --- | --- | | DIMVAR | Code | Description | | DIMALTRND | 148 | Rounds off the alternate dimension units. | | DIMATFIT | 289 | Determines how dimension text and arrows are arranged when space is not sufficient to place both within the extension lines. 0 = Places both text and arrows outside extension lines 1 = Moves arrows first, then text 2 = Moves text first, then arrows 3 = Moves either text or arrows, whichever fits best A leader is added to moved dimension text when DIMTMOVE is set to 1. | | DIMAZIN | 79 | Suppresses zeros for angular dimensions. 0 = Displays all leading and trailing zeros 1 = Suppresses leading zeros in decimal dimensions (for example, 0.5000 becomes .5000) 2 = Suppresses trailing zeros in decimal dimensions (for example, 12.5000 becomes 12.5) 3 = Suppresses leading and trailing zeros (for example, 0.5000 becomes .5) | | DIMFRAC | 276 | Sets the fraction format when DIMLUNIT is set to 4 (Architectural) or 5 (Fractional). 0 = Horizontal stacking 1 = Diagonal stacking 2 = Not stacked (for example, 1/2) | | DIMLDRBLK\_HANDLE | 341 | Specifies the arrow type for leaders. Handle to BLOCK RECORD | | DIMLUNIT | 277 | Sets units for all dimension types except Angular. 1 = Scientific 2 = Decimal 3 = Engineering 4 = Architectural (always displayed stacked) 5 = Fractional (always displayed stacked) 6 = Microsoft Windows Desktop (decimal format using Control Panel settings for decimal separator and number grouping symbols) | | DIMLWD | 371 | Assigns lineweight to dimension lines. -3 = Default (the LWDEFAULT value) -2 = BYBLOCK -1 = BYLAYER | | DIMLWE | 372 | Assigns lineweight to extension lines. -3 = Default (the LWDEFAULT value) -2 = BYBLOCK -1 = BYLAYER | | DIMTMOVE | 279 | Sets dimension text movement rules. 0 = Moves the dimension line with dimension text 1 = Adds a leader when dimension text is moved 2 = Allows text to be moved freely without a leader | ### Text Location This image shows the default text locations created by *BricsCAD* for dimension variables **dimtad** and **dimjust**: \[image\] ### Unofficial DIMSTYLE Variables for DXF R2007 and later The following DIMVARS are **not documented** in the *DXF Reference* by Autodesk. | | | | | --- | --- | --- | | DIMVAR | Code | Description | | DIMTFILL | 69 | Text fill 0=off; 1=background color; 2=custom color (see DIMTFILLCLR) | | DIMTFILLCLR | 70 | Text fill custom color as color index | | DIMFXLON | 290 | Extension line has fixed length if set to 1 | | DIMFXL | 49 | Length of extension line below dimension line if fixed (DIMFXLON is 1), DIMEXE defines the the length above the dimension line | | DIMJOGANG | 50 | Angle of oblique dimension line segment in jogged radius dimension | | DIMLTYPE\_HANDLE | 345 | Specifies the LINETYPE of the dimension line. Handle to LTYPE table entry | | DIMLTEX1\_HANDLE | 346 | Specifies the LINETYPE of the extension line 1. Handle to LTYPE table entry | | DIMLTEX2\_HANDLE | 347 | Specifies the LINETYPE of the extension line 2. Handle to LTYPE table entry | ### Extended Settings as Special XDATA Groups Prior to DXF R2007, some extended settings for the dimension and the extension lines are stored in the XDATA section by following entries, this is not documented by *Autodesk*: ``` 1001 ACAD_DSTYLE_DIM_LINETYPE <<< linetype for dimension line 1070 380 <<< group code, which differs from R2007 DIMDLTYPE 1005 FFFF <<< handle to LTYPE entry 1001 ACAD_DSTYLE_DIM_EXT1_LINETYPE <<< linetype for extension line 1 1070 381 <<< group code, which differs from R2007 DIMLTEX1 1005 FFFF <<< handle to LTYPE entry 1001 ACAD_DSTYLE_DIM_EXT2_LINETYPE <<< linetype for extension line 1 1070 382 <<< group code, which differs from R2007 DIMLTEX2 1005 FFFF <<< handle to LTYPE entry 1001 ACAD_DSTYLE_DIMEXT_ENABLED <<< extension line fixed 1070 383 <<< group code, which differs from R2007 DIMEXFIX 1070 1 <<< fixed if 1 else 0 1001 ACAD_DSTYLE_DIMEXT_LENGTH <<< extension line fixed length 1070 378 <<< group code, which differs from R2007 DIMEXLEN 1040 1.33 <<< length of extension line below dimension line ``` This XDATA groups requires also an appropriate APPID entry in the APPID table. This feature is not supported by *ezdxf*. ### LAYER Table TODO **SEE ALSO:** - • DXF Reference: *TABLES Section* - • DXF Reference: *LAYER* Table - • *Layer* class ### Table Structure DXF R2000+ ``` 0 <<< start of table TABLE 2 <<< name of table "LAYER" LAYER 5 <<< handle of the TABLE 2 330 <<< owner tag is always "0" 0 100 <<< subclass marker AcDbSymbolTable 70 <<< count of layers defined in this table, AutoCAD ignores this value 5 0 <<< 1. LAYER table entry LAYER ... <<< LAYER entity tags 0 <<< 2. LAYER table entry LAYER ... <<< LAYER entity tags 0 <<< end of TABLE ENDTAB ``` ### Layer Entity Tags DXF R2000+ There are some quirks: - • the frozen/thawed state is stored in flags (group code 70) - • the locked/unlocked state is stored in flags (group code 70) - • the off state is stored as negative color value (group code 6) - • the layer description is stored in the XDATA section - • the transparency value is stored in the XDATA section ``` 0 <<< LAYER table entry LAYER 5 <<< handle of LAYER 10 330 <<< owner handle, handle of LAYER table 2 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbLayerTableRecord 2 <<< layer name 0 <<< layer "0" 70 <<< flags 0 62 <<< color 7 <<< a negative value switches the layer off 420 <<< optional true color value 0 6 <<< linetype Continuous 290 <<< optional plot flag 1 370 <<< lineweight -3 390 <<< handle to plot style F 347 <<< material handle 47 348 <<< unknown1 0 1001 <<< XDATA section, APPID AcAecLayerStandard 1000 <<< unknown first value, here an empty string 1000 <<< layer description This layer has a description 1001 <<< APPID AcCmTransparency 1071 <<< layer transparency value 0 ``` ### Layer Viewport Overrides Some layer attributes can be overridden individually for any VIEWPORT entity. This overrides are stored as extension dictionary entries of the LAYER entity pointing to XRECORD entities in the objects section: ``` 0 LAYER 5 9F 102 <<< APP data, extension dictionary {ACAD_XDICTIONARY 360 <<< handle to the xdict in the objects section B3 102 } 330 2 100 AcDbSymbolTableRecord 100 AcDbLayerTableRecord 2 LayerA ... ``` The extension DICTIONARY entity: ``` 0 <<< entity type DICTIONARY 5 <<< handle B3 330 <<< owner handle 9F <<< the layer owns this dictionary 100 <<< subclass marker AcDbDictionary 280 <<< hard owned flag 1 281 <<< cloning type 1 <<< keep existing 3 <<< transparency override ADSK_XREC_LAYER_ALPHA_OVR 360 <<< handle to XRECORD E5 3 <<< color override ADSK_XREC_LAYER_COLOR_OVR 360 <<< handle to XRECORD B4 3 <<< linetype override ADSK_XREC_LAYER_LINETYPE_OVR 360 <<< handle to XRECORD DD 3 <<< lineweight override ADSK_XREC_LAYER_LINEWT_OVR 360 <<< handle to XRECORD E2 ``` Transparency override XRECORD: ``` 0 <<< entity type XRECORD 5 <<< handle E5 102 <<< reactors app data {ACAD_REACTORS 330 B3 <<< extension dictionary 102 } 330 <<< owner tag B3 <<< extension dictionary 100 <<< subclass marker AcDbXrecord 280 <<< cloning flag 1 <<< keep existing 102 <<< for each overridden VIEWPORT one entry {ADSK_LYR_ALPHA_OVERRIDE 335 <<< handle to VIEWPORT AC 440 <<< transparency override 33554661 102 } ``` Color override XRECORD: ``` 0 XRECORD ... <<< like transparency XRECORD 102 <<< for each overridden VIEWPORT one entry {ADSK_LYR_COLOR_OVERRIDE 335 <<< handle to VIEWPORT AF 420 <<< color override -1023409925 <<< raw color value 102 } ``` Linetype override XRECORD: ``` 0 XRECORD ... <<< like transparency XRECORD 102 <<< for each overridden VIEWPORT one entry {ADSK_LYR_LINETYPE_OVERRIDE 335 <<< handle to VIEWPORT AC 343 <<< linetype override DC <<< handle to LINETYPE table entry 102 } ``` Lineweight override XRECORD: ``` 0 XRECORD ... <<< like transparency XRECORD 102 <<< for each overridden VIEWPORT one entry {ADSK_LYR_LINEWT_OVERRIDE 335 <<< handle to VIEWPORT AC 91 <<< lineweight override 13 <<< lineweight value 102 } ``` ### Name References LAYER table entries are referenced by name: - • all graphical DXF entities - • VIEWPORT entity, frozen layers - • LAYER\_FILTER - • LAYER\_INDEX ### LTYPE Table The *LTYPE* table stores all line type definitions of a DXF drawing. Every line type used in the drawing has to have a table entry, or the DXF drawing is invalid for AutoCAD. DXF R12 supports just simple line types, DXF R2000+ supports also complex line types with text or shapes included. You have access to the line types table by the attribute **Drawing.linetypes**. The line type table itself is not stored in the entity database, but the table entries are stored in entity database, and can be accessed by its handle. **SEE ALSO:** - • DXF Reference: *TABLES Section* - • DXF Reference: *LTYPE* Table - • *Linetype* class ### Table Structure DXF R12 ``` 0 <<< start of table TABLE 2 <<< table type LTYPE 70 <<< count of table entries, AutoCAD ignores this value 9 0 <<< 1. LTYPE table entry LTYPE <<< LTYPE data tags 0 <<< 2. LTYPE table entry LTYPE <<< LTYPE data tags and so on 0 <<< end of LTYPE table ENDTAB ``` ### Table Structure DXF R2000+ ``` 0 <<< start of table TABLE 2 <<< table type LTYPE 5 <<< table handle 5F 330 <<< owner tag, tables have no owner 0 100 <<< subclass marker AcDbSymbolTable 70 <<< count of table entiries, AutoCAD ignores this value 9 0 <<< 1. LTYPE table entry LTYPE <<< LTYPE data tags 0 <<< 2. LTYPE table entry LTYPE <<< LTYPE data tags and so on 0 <<< end of LTYPE table ENDTAB ``` ### Simple Line Type *ezdxf* setup for line type “CENTER”: ``` dwg.linetypes.add("CENTER", description="Center ____ _ ____ _ ____ _ ____ _ ____ _ ____", pattern=[2.0, 1.25, -0.25, 0.25, -0.25], ) ``` ### Simple Line Type Tag Structure DXF R2000+ ``` 0 <<< line type table entry LTYPE 5 <<< handle of line type 1B1 330 <<< owner handle, handle of LTYPE table 5F 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbLinetypeTableRecord 2 <<< line type name CENTER 70 <<< flags 0 3 Center ____ _ ____ _ ____ _ ____ _ ____ _ ____ 72 <<< signature tag 65 <<< ascii code for "A" 73 <<< count of pattern groups starting with a code 49 tag 4 <<< 4 pattern groups 40 <<< overall pattern length in drawing units 2.0 49 <<< 1. pattern group 1.25 <<< >0 line, <0 gap, =0 point 74 <<< type marker 0 <<< 0 for line group 49 <<< 2. pattern group -0.25 74 0 49 <<< 3. pattern group 0.25 74 0 49 <<< 4. pattern group -0.25 74 0 ``` ### Complex Line Type TEXT *ezdxf* setup for line type “GASLEITUNG”: ``` dwg.linetypes.add("GASLEITUNG", description="Gasleitung2 ----GAS----GAS----GAS----GAS----GAS----GAS--", length=1, pattern='A,.5,-.2,["GAS",STANDARD,S=.1,U=0.0,X=-0.1,Y=-.05],-.25', ) ``` ### TEXT Tag Structure ``` 0 LTYPE 5 614 330 5F 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbLinetypeTableRecord 2 GASLEITUNG 70 0 3 Gasleitung2 ----GAS----GAS----GAS----GAS----GAS----GAS-- 72 <<< signature tag 65 <<< ascii code for "A" 73 <<< count of pattern groups starting with a code 49 tag 3 <<< 3 pattern groups 40 <<< overall pattern length in drawing units 1 49 <<< 1. pattern group 0.5 <<< >0 line, <0 gap, =0 point 74 <<< type marker 0 <<< 0 for line group 49 <<< 2. pattern group -0.2 74 <<< type marker 2 <<< 2 for text group 75 <<< shape number in shape-file 0 <<< always 0 for text group 340 <<< handle to text style "STANDARD" 11 46 <<< scaling factor: "s" in pattern definition 0.1 50 <<< rotation angle: "r" and "u" in pattern definition 0.0 44 <<< shift x units: "x" in pattern definition = parallel to line direction -0.1 45 <<< shift y units: "y" in pattern definition = normal to line direction -0.05 9 <<< text GAS 49 <<< 3. pattern group -0.25 74 0 ``` ### Complex Line Type SHAPE ezdxf setup for line type ‘GRENZE2’: ``` dwg.linetypes.new('GRENZE2', dxfattribs={ 'description': 'Grenze eckig ----[]-----[]----[]-----[]----[]--', 'length': 1.45, 'pattern': 'A,.25,-.1,[132,ltypeshp.shx,x=-.1,s=.1],-.1,1', }) ``` ### SHAPE Tag Structure ``` 0 LTYPE 5 615 330 5F 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbLinetypeTableRecord 2 GRENZE2 70 0 3 Grenze eckig ----[]-----[]----[]-----[]----[]-- 72 <<< signature tag 65 <<< ascii code for "A" 73 <<< count of pattern groups starting with a code 49 tag 4 <<< 4 pattern groups 40 <<< overall pattern length in drawing units 1.45 49 <<< 1. pattern group 0.25 <<< >0 line, <0 gap, =0 point 74 <<< type marker 0 <<< 0 for line group 49 <<< 2. pattern group -0.1 74 <<< type marker 4 <<< 4 for shape group 75 <<< shape number in shape-file 132 340 <<< handle to shape-file entry "ltypeshp.shx" 616 46 <<< scaling factor: "s" in pattern definition 0.1 50 <<< rotation angle: "r" and "u" in pattern definition 0.0 44 <<< shift x units: "x" in pattern definition = parallel to line direction -0.1 45 <<< shift y units: "y" in pattern definition = normal to line direction 0.0 49 <<< 3. pattern group -0.1 74 0 49 <<< 4. pattern group 1.0 74 0 ``` ### Name References LTYPE table entries are referenced by name: - • all graphical DXF entities - • LAYER table entry - • DIMSTYLE table entry - • DIMSTYLE override - • MLINESTYLE ### STYLE Table The *STYLE* table stores all text styles and shape-file definitions. The “STANDARD” entry must always exist. Shape-files are also defined by a STYLE table entry, the bit 0 of the flags-tag is set to 1 and the name-tag is an empty string, the only important data is the font-tag with group code 3 which stores the associated SHX font file. **SEE ALSO:** - • DXF Reference: *TABLES Section* - • DXF Reference: *STYLE* Table - • *Textstyle* class ### Table Structure DXF R12 ``` 0 <<< start of table TABLE 2 <<< table type STYLE 70 <<< count of table entries, AutoCAD ignores this value 1 0 <<< first table entry STYLE 2 <<< text style name Standard 70 <<< flags, see `STYLE`_ reference 0 40 <<< fixed text height; 0 if not fixed 0.0 41 <<< width factor 1.0 50 <<< oblique angle 0.0 71 <<< text generation flags; 2=backwards (mirror-x), 4=upside down (mirror-y) 0 42 <<< last height used 2.5 3 <<< font file name; SHX or TTF file name txt 4 <<< big font name; SHX file with unicode symbols; empty if none 0 <<< next text style STYLE ... 0 <<< end of STYLE table ENDTAB ``` ### Table Structure DXF R2000+ ``` 0 <<< start of table TABLE 2 <<< table type STYLE 5 <<< table handle 5 330 <<< owner tag, tables have no owner 0 100 <<< subclass marker AcDbSymbolTable 70 <<< count of table entries, AutoCAD ignores this value 1 0 <<< first table entry STYLE 5 <<< handle of text style 29 330 <<< owner handle, handle of STYLE table 5 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbTextStyleTableRecord 2 <<< text style name Standard 70 <<< flags, see `STYLE`_ reference 0 40 <<< fixed text height; 0 if not fixed 0.0 41 <<< width factor 1.0 50 <<< oblique angle 0.0 71 <<< text generation flags; 2=backwards (mirror-x), 4=upside down (mirror-y) 0 42 <<< last height used 2.5 3 <<< font file name; SHX or TTF file name txt 4 <<< big font name; SHX file with unicode symbols; empty if none 0 <<< next text style STYLE ... 0 <<< end of STYLE table ENDTAB ``` ### Extended Font Data Additional information of the font-family, italic and bold style flags are stored in the XDATA section of the STYLE entity by the APPID “ACAD”: ``` 0 STYLE ... 3 Arial.ttf 4 1001 <<< start of the XDATA section ACAD <<< APPID 1000 <<< font family name Arial 1071 <<< style flags, see table below 50331682 ``` | | | | | --- | --- | --- | | Flag | dec | hex | | ITALIC | 16777216 | 0x1000000 | | BOLD | 33554432 | 0x2000000 | ### Name References STYLE table entries are referenced by name: - • TEXT entity - • MTEXT entity - • DIMSTYLE table entry - • DIMSTYLE override ### UCS Table TODO ### VIEW Table The *VIEW* entry stores a named view of the model or a paperspace layout. This stored views makes parts of the drawing or some view points of the model in a CAD applications more accessible. This views have no influence to the drawing content or to the generated output by exporting PDFs or plotting on paper sheets, they are just for the convenience of CAD application users. Using *ezdxf* you have access to the views table by the attribute **Drawing.views**. The views table itself is not stored in the entity database, but the table entries are stored in entity database, and can be accessed by its handle. ### DXF R12 ``` 0 VIEW 2 <<< name of view VIEWNAME 70 <<< flags bit-coded: 1st bit -> (0/1 = modelspace/paperspace) 0 <<< modelspace 40 <<< view width in Display Coordinate System (DCS) 20.01 10 <<< view center point in DCS 40.36 <<< x value 20 <<< group code for y value 15.86 <<< y value 41 <<< view height in DCS 17.91 11 <<< view direction from target point, 3D vector 0.0 <<< x value 21 <<< group code for y value 0.0 <<< y value 31 <<< group code for z value 1.0 <<< z value 12 <<< target point in WCS 0.0 <<< x value 22 <<< group code for y value 0.0 <<< y value 32 <<< group code for z value 0.0 <<< z value 42 <<< lens (focal) length 50.0 <<< 50mm 43 <<< front clipping plane, offset from target 0.0 44 <<< back clipping plane, offset from target 0.0 50 <<< twist angle 0.0 71 <<< view mode 0 ``` **SEE ALSO:** *Coordinate Systems* ### DXF R2000+ Mostly the same structure as DXF R12, but with handle, owner tag and subclass markers. ``` 0 <<< adding the VIEW table head, just for information TABLE 2 <<< table name VIEW 5 <<< handle of table, see owner tag of VIEW table entry 37C 330 <<< owner tag of table, always #0 0 100 <<< subclass marker AcDbSymbolTable 70 <<< VIEW table (max.) count, not reliable (ignore) 9 0 <<< first VIEW table entry VIEW 5 <<< handle 3EA 330 <<< owner, the VIEW table is the owner of the VIEW entry 37C <<< handle of the VIEW table 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbViewTableRecord 2 <<< view name, from here all the same as DXF R12 VIEWNAME 70 0 40 20.01 10 40.36 20 15.86 41 17.91 11 0.0 21 0.0 31 1.0 12 0.0 22 0.0 32 0.0 42 50.0 43 0.0 44 0.0 50 0.0 71 0 281 <<< render mode 0-6 (... too much options) 0 <<< 0= 2D optimized (classic 2D) 72 <<< UCS associated (0/1 = no/yes) 0 <<< 0 = no ``` DXF R2000+ supports additional features in the VIEW entry, see the *VIEW* table reference provided by Autodesk. ### VPORT Configuration Table The *VPORT* table stores the modelspace viewport configurations. A viewport configuration is a tiled view of multiple viewports or just one viewport. \[image\] In contrast to other tables the VPORT table can have multiple entries with the same name, because all VPORT entries of a multi-viewport configuration are having the same name - the viewport configuration name. The name of the actual displayed viewport configuration is **'\*ACTIVE'**, as always table entry names are case insensitive (**'\*ACTIVE' == '\*Active'**). The available display area in AutoCAD has normalized coordinates, the lower-left corner is (0, 0) and the upper-right corner is (1, 1) regardless of the true aspect ratio and available display area in pixels. A single viewport configuration has one VPORT entry **'\*ACTIVE'** with the lower-left corner (0, 0) and the upper-right corner (1, 1). The following statements refer to a 2D plan view: the view-target-point defines the origin of the DCS (Display Coordinate system), the view-direction vector defines the z-axis of the *DCS*, the view-center-point (in DCS) defines the point in modelspace translated to the center point of the viewport, the view height and the aspect-ratio defines how much of the modelspace is displayed. AutoCAD tries to fit the modelspace area into the available viewport space e.g. view height is 15 units and aspect-ratio is 2.0 the modelspace to display is 30 units wide and 15 units high, if the viewport has an aspect ratio of 1.0, AutoCAD displays 30x30 units of the modelspace in the viewport. If the modelspace aspect-ratio is 1.0 the modelspace to display is 15x15 units and fits properly into the viewport area. But tests show that the translation of the view-center-point to the middle of the viewport not always work as I expected. (still digging…) **NOTE:** All floating point values are rounded to 2 decimal places for better readability. ### DXF R12 Multi-viewport configuration with three viewports. ``` 0 <<< table start TABLE 2 <<< table type VPORT 70 <<< VPORT table (max.) count, not reliable (ignore) 3 0 <<< first VPORT entry VPORT 2 <<< VPORT (configuration) name *ACTIVE 70 <<< standard flags, bit-coded 0 10 <<< lower-left corner of viewport 0.45 <<< x value, virtual coordinates in range [0 - 1] 20 <<< group code for y value 0.0 <<< y value, virtual coordinates in range [0 - 1] 11 <<< upper-right corner of viewport 1.0 <<< x value, virtual coordinates in range [0 - 1] 21 <<< group code for y value 1.0 <<< y value, virtual coordinates in range [0 - 1] 12 <<< view center point (in DCS), ??? 13.71 <<< x value 22 <<< group code for y value 0.02 <<< y value 13 <<< snap base point (in DCS) 0.0 <<< x value 23 <<< group code for y value 0.0 <<< y value 14 <<< snap spacing X and Y 1.0 <<< x value 24 <<< group code for y value 1.0 <<< y value 15 <<< grid spacing X and Y 0.0 <<< x value 25 <<< group code for y value 0.0 <<< y value 16 <<< view direction from target point (in WCS), defines the z-axis of the DCS 1.0 <<< x value 26 <<< group code for y value -1.0 <<< y value 36 <<< group code for z value 1.0 <<< z value 17 <<< view target point (in WCS), defines the origin of the DCS 0.0 <<< x value 27 <<< group code for y value 0.0 <<< y value 37 <<< group code for z value 0.0 <<< z value 40 <<< view height 35.22 41 <<< viewport aspect ratio 0.99 42 <<< lens (focal) length 50.0 <<< 50mm 43 <<< front clipping planes, offsets from target point 0.0 44 <<< back clipping planes, offsets from target point 0.0 50 <<< snap rotation angle 0.0 51 <<< view twist angle 0.0 71 <<< view mode 0 72 <<< circle zoom percent 1000 73 <<< fast zoom setting 1 74 <<< UCSICON setting 3 75 <<< snap on/off 0 76 <<< grid on/off 0 77 <<< snap style 0 78 <<< snap isopair 0 0 <<< next VPORT entry VPORT 2 <<< VPORT (configuration) name *ACTIVE <<< same as first VPORT entry 70 0 10 0.0 20 0.5 11 0.45 21 1.0 12 8.21 22 9.41 ... ... 0 <<< next VPORT entry VPORT 2 <<< VPORT (configuration) name *ACTIVE <<< same as first VPORT entry 70 0 10 0.0 20 0.0 11 0.45 21 0.5 12 2.01 22 -9.33 ... ... 0 ENDTAB ``` ### DXF R2000+ Mostly the same structure as DXF R12, but with handle, owner tag and subclass markers. ``` 0 <<< table start TABLE 2 <<< table type VPORT 5 <<< table handle 151F 330 <<< owner, table has no owner - always #0 0 100 <<< subclass marker AcDbSymbolTable 70 <<< VPORT table (max.) count, not reliable (ignore) 3 0 <<< first VPORT entry VPORT 5 <<< entry handle 158B 330 <<< owner, VPORT table is owner of VPORT entry 151F 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbViewportTableRecord 2 <<< VPORT (configuration) name *ACTIVE 70 <<< standard flags, bit-coded 0 10 <<< lower-left corner of viewport 0.45 <<< x value, virtual coordinates in range [0 - 1] 20 <<< group code for y value 0.0 <<< y value, virtual coordinates in range [0 - 1] 11 <<< upper-right corner of viewport 1.0 <<< x value, virtual coordinates in range [0 - 1] 21 <<< group code for y value 1.0 <<< y value, virtual coordinates in range [0 - 1] 12 <<< view center point (in DCS) 13.71 <<< x value 22 <<< group code for y value 0.38 <<< y value 13 <<< snap base point (in DCS) 0.0 <<< x value 23 <<< group code for y value 0.0 <<< y value 14 <<< snap spacing X and Y 1.0 <<< x value 24 <<< group code for y value 1.0 <<< y value 15 <<< grid spacing X and Y 0.0 <<< x value 25 <<< group code for y value 0.0 <<< y value 16 <<< view direction from target point (in WCS) 1.0 <<< x value 26 <<< group code for y value -1.0 <<< y value 36 <<< group code for z value 1.0 <<< z value 17 <<< view target point (in WCS) 0.0 <<< x value 27 <<< group code for y value 0.0 <<< y value 37 <<< group code for z value 0.0 <<< z value 40 <<< view height 35.22 41 <<< viewport aspect ratio 0.99 42 <<< lens (focal) length 50.0 <<< 50mm 43 <<< front clipping planes, offsets from target point 0.0 44 <<< back clipping planes, offsets from target point 0.0 50 <<< snap rotation angle 0.0 51 <<< view twist angle 0.0 71 <<< view mode 0 72 <<< circle zoom percent 1000 73 <<< fast zoom setting 1 74 <<< UCSICON setting 3 75 <<< snap on/off 0 76 <<< grid on/off 0 77 <<< snap style 0 78 <<< snap isopair 0 281 <<< render mode 1-6 (... too many options) 0 <<< 0 = 2D optimized (classic 2D) 65 <<< Value of UCSVP for this viewport. (0 = UCS will not change when this viewport is activated) 1 <<< 1 = then viewport stores its own UCS which will become the current UCS whenever the viewport is activated. 110 <<< UCS origin (3D point) 0.0 <<< x value 120 <<< group code for y value 0.0 <<< y value 130 <<< group code for z value 0.0 <<< z value 111 <<< UCS X-axis (3D vector) 1.0 <<< x value 121 <<< group code for y value 0.0 <<< y value 131 <<< group code for z value 0.0 <<< z value 112 <<< UCS Y-axis (3D vector) 0.0 <<< x value 122 <<< group code for y value 1.0 <<< y value 132 <<< group code for z value 0.0 <<< z value 79 <<< Orthographic type of UCS 0-6 (... too many options) 0 <<< 0 = UCS is not orthographic 146 <<< elevation 0.0 1001 <<< extended data - undocumented ACAD_NAV_VCDISPLAY 1070 3 0 <<< next VPORT entry VPORT 5 158C 330 151F 100 AcDbSymbolTableRecord 100 AcDbViewportTableRecord 2 <<< VPORT (configuration) name *ACTIVE <<< same as first VPORT entry 70 0 10 0.0 20 0.5 11 0.45 21 1.0 12 8.21 22 9.72 ... ... 0 <<< next VPORT entry VPORT 5 158D 330 151F 100 AcDbSymbolTableRecord 100 AcDbViewportTableRecord 2 <<< VPORT (configuration) name *ACTIVE <<< same as first VPORT entry 70 0 10 0.0 20 0.0 11 0.45 21 0.5 12 2.01 22 -8.97 ... ... 0 ENDTAB ``` The TABLES section of DXF R13 and later looks like this: ``` 0 SECTION 2 <<< begin TABLES section TABLES 0 <<< first TABLE TABLE 2 <<< name of table "LTYPE" LTYPE 5 <<< handle of the TABLE 8 330 <<< owner handle is always "0" 0 100 <<< subclass marker AcDbSymbolTable 70 <<< count of table entries 4 <<< do not rely on this value! 0 <<< first table entry LTYPE ... 0 <<< second table entry LTYPE ... 0 <<< end of TABLE ENDTAB 0 <<< next TABLE TABLE 2 <<< name of table "LAYER" LAYER 5 <<< handle of the TABLE 2 330 <<< owner handle is always "0" 0 100 <<< subclass marker AcDbSymbolTable 70 <<< count of table entries 1 0 <<< first table entry LAYER ... 0 <<< end of TABLE ENDTAB 0 <<< end of SECTION ENDSEC ``` The TABLES section of DXF R12 and prior is a bit simpler and does not contain the BLOCK\_RECORD table. The handles in DXF R12 and prior are optional and only present if the HEADER variable $HANDLING is 1. ``` 0 SECTION 2 <<< begin TABLES section TABLES 0 <<< first TABLE TABLE 2 <<< name of table "LTYPE" LTYPE 5 <<< optional handle of the TABLE 8 70 <<< count of table entries 4 0 <<< first table entry LTYPE ... 0 <<< second table entry LTYPE ... 0 <<< end of TABLE ENDTAB 0 <<< next TABLE TABLE 2 <<< name of table "LAYER" LAYER 5 <<< optional handle of the TABLE 2 70 <<< count of table entries 1 0 <<< first table entry LAYER ... 0 <<< end of TABLE ENDTAB 0 <<< end of SECTION ENDSEC ``` ### BLOCKS Section The BLOCKS section contains all BLOCK definitions, beside the *normal* reusable BLOCKS used by the INSERT entity, all layouts, as there are the modelspace and all paperspace layouts, have at least a corresponding BLOCK definition in the BLOCKS section. The name of the modelspace BLOCK is “\*Model\_Space” (DXF R12: “$MODEL\_SPACE”) and the name of the *active* paperspace BLOCK is “\*Paper\_Space” (DXF R12: “$PAPER\_SPACE”), the entities of these two layouts are stored in the ENTITIES section, the *inactive* paperspace layouts are named by the scheme “\*Paper\_Spacennnn”, and the content of the inactive paperspace layouts are stored in their BLOCK definition in the BLOCKS section. The content entities of blocks are stored between the BLOCK and the ENDBLK entity. BLOCKS section structure: ``` 0 <<< start of a SECTION SECTION 2 <<< start of BLOCKS section BLOCKS 0 <<< start of 1. BLOCK definition BLOCK ... <<< Block content ... 0 <<< end of 1. Block definition ENDBLK 0 <<< start of 2. BLOCK definition BLOCK ... <<< Block content ... 0 <<< end of 2. Block definition ENDBLK 0 <<< end of BLOCKS section ENDSEC ``` **SEE ALSO:** *Block Management Structures* *Layout Management Structures* ### ENTITIES Section TODO ### OBJECTS Section Objects in the OBJECTS section are organized in a hierarchical tree order, starting with the *named objects dictionary* as the first entity in the OBJECTS section (**Drawing.rootdict**). Not all entities in the OBJECTS section are included in this tree, *Extension Dictionary* and XRECORD data of graphical entities are also stored in the OBJECTS section. ### DXF Tables ### DXF Entities ### DIMENSION Internals **SEE ALSO:** - • DXF Reference: *DIMENSION* - • DXFInternals: *DIMSTYLE Table* \[image\] ### MESH Internals The MESH entity is the compact version of the PolyFaceMesh implemented by the *Polyline* entity . The entity stores the vertices, edges and faces in a single entity and was introduced in DXF version R13/R14. For more information about the top level stuff go to the *Mesh* class. **SEE ALSO:** - • DXF Reference: *MESH* - • *ezdxf.entities.Mesh* class The following DXF code represents this cube with subdivision level of 0: \[image\] ``` 0 MESH <<< DXF type 5 <<< entity handle 2F 330 <<< block record handle of owner layout 17 100 AcDbEntity 8 0 <<< layer 62 6 <<< color 100 AcDbSubDMesh <<< subclass marker 71 2 <<< version 72 1 <<< blend crease, 1 is "on", 0 is "off" 91 0 <<< subdivision level is 0 92 8 <<< vertex count, 8 cube corners 10 <<< 1. vertex, x-axis 0.0 20 <<< y-axis 0.0 30 <<< z-axis 0.0 10 <<< 2. vertex 1.0 20 0.0 30 0.0 10 <<< 3. vertex 1.0 20 1.0 30 0.0 10 <<< 4. vertex 0.0 20 1.0 30 0.0 10 <<< 5. vertex 0.0 20 0.0 30 1.0 10 <<< 6. vertex 1.0 20 0.0 30 1.0 10 <<< 7. vertex 1.0 20 1.0 30 1.0 10 <<< 8. vertex 0.0 20 1.0 30 1.0 93 <<< size of face list 30 <<< size = count of group code 90 tags = 6 x 5 90 <<< vertex count of face 1 4 <<< MESH supports ngons, count = 3, 4, 5, 6 ... 90 0 <<< face 1, index of 1. vertex 90 3 <<< face 1, index of 2. vertex 90 2 <<< face 1, index of 3. vertex 90 1 <<< face 1, index of 4. vertex 90 4 <<< vertex count of face 2 90 4 <<< face 2, index of 1. vertex 90 5 <<< face 2, index of 2. vertex 90 6 <<< face 2, index of 3. vertex 90 7 <<< face 2, index of 4. vertex 90 4 <<< vertex count of face 3 90 0 <<< face 3, index of 1. vertex 90 1 <<< face 3, index of 2. vertex 90 5 <<< face 3, index of 3. vertex 90 4 <<< face 3, index of 4. vertex 90 4 <<< vertex count of face 4 90 1 <<< face 4, index of 1. vertex 90 2 <<< face 4, index of 2. vertex 90 6 <<< face 4, index of 3. vertex 90 5 <<< face 4, index of 4. vertex 90 4 <<< vertex count of face 5 90 3 <<< face 5, index of 1. vertex 90 7 <<< face 5, index of 2. vertex 90 6 <<< face 5, index of 3. vertex 90 2 <<< face 5, index of 4. vertex 90 4 <<< vertex count of face 6 90 0 <<< face 6, index of 1. vertex 90 4 <<< face 6, index of 2. vertex 90 7 <<< face 6, index of 3. vertex 90 3 <<< face 6, index of 4. vertex 94 <<< edge count, each edge has exact two group code 90 tags 4 <<< the real edge count not the group code 90 tags! 90 0 <<< edge 1, vertex 1 90 1 <<< edge 1, vertex 1 90 1 <<< edge 2, vertex 1 90 2 <<< edge 2, vertex 2 90 2 <<< edge 3, vertex 1 90 3 <<< edge 3, vertex 2 90 3 <<< edge 4, vertex 1 90 0 <<< edge 4, vertex 2 95 <<< edge crease count, has to match edge count! 4 140 3.0 <<< crease value for edge 1 140 3.0 <<< crease value for edge 2 140 3.0 <<< crease value for edge 3 140 3.0 <<< crease value for edge 4 90 <<< property overwrite??? 0 ``` The edge and crease data have only a meaning if subdivision of the geometry will be applied! A crease value equal to the subdivision level prevents subdividing for the edge completely, a value between 0.0 and the subdivision level applies subdivision partially. The cube with subdivision level of 3 and crease values of 3.0: \[image\] Front view for better details: \[image\] The cube with subdivision levels of 3 and crease values of 2.0: \[image\] The cube with subdivision level of 3 and crease values of 1.0: \[image\] The property overriding protocol is not documented in the DXF reference and currently I have no access to a CAD application which can created property overriding. ### MULTILEADER Internals The MULTILEADER leader is a very complex entity and has also some weird and unique properties. - 1\. MULTILEADER has the alias name MLEADER which is accepted by any *reliable CAD application*, but all of them create the entity as MULTILEADER - 2\. uses *raw-color* values to define colors - 3\. creates a complex context data structures beyond simple tags inside the subclass **AcDbMLeader** **SEE ALSO:** - • *ezdxf.entities.MultiLeader* - • *ezdxf.entities.MLeaderStyle* - • *ezdxf.render.MultiLeaderBuilder* - • *Tutorial for MultiLeader* - • DXF Reference: *MLEADER* Example for *ezdxf.entities.MLeaderContext* created by BricsCAD: ``` 300 CONTEXT_DATA{ 40 1.0 <<< content scale 10 (x, y, z) <<< content base point 41 4.0 <<< text height 140 4.0 <<< arrowhead size 145 2.0 <<< landing gap size 174 1 <<< doc missing 175 1 <<< doc missing 176 0 <<< doc missing 177 0 <<< doc missing 290 1 <<< has_mtext_content <<< START MText Content tags: 304 MTEXT content string 11 (0.0, 0.0, 1.0) <<< extrusion vector 340 #A0 <<< text style as handle 12 (x, y, z) <<< text location 13 (1.0, 0.0, 0.0) <<< text direction 42 0.0 <<< text rotation 43 0.0 <<< text width 44 0.0 <<< text height 45 1.0 <<< text line space factor 170 1 <<< text line space style 90 -1056964608 <<< text color (raw value) 171 1 <<< text attachment 172 1 <<< text flow direction 91 -939524096 <<< text background color (raw value) 141 1.5 <<< text background scale factor 92 0 <<< text background transparency 291 0 <<< has_text_bg_color 292 0 <<< has_text_bg_fill 173 0 <<< text column type 293 0 <<< use text auto height 142 0.0 <<< text column width 143 0.0 <<< text column gutter width 294 0 <<< text column flow reversed 144 missing <<< text column height (optional?) 295 0 <<< text use word break <<< END MText Content tags: 296 0 <<< has_block_content <<< START Block content tags <<< END Block content tags 110 (0.0, 0.0, 0.0) <<< MLEADER plane origin point 111 (1.0, 0.0, 0.0) <<< MLEADER plane x-axis direction 112 (0.0, 1.0, 0.0) <<< MLEADER plane y-axis direction 297 0 <<< MLEADER normal reversed 302 LEADER{ ... 303 } 302 LEADER{ ... 303 } 272 9 <<< doc missing 273 9 <<< doc missing 301 } <<< BricsCAD example for block content: 300 CONTEXT_DATA{ 40 1.0 10 (x, y, z) 41 4.0 140 4.0 145 2.0 174 1 175 1 176 0 177 0 290 0 <<< has_mtext_content 296 1 <<< has_block_content <<< START Block content tags 341 #94 <<< dxf.block_record_handle 14 (0.0, 0.0, 1.0) <<< Block extrusion vector 15 (x, y, z) <<< Block location 16 (1.0, 1.0, 1.0) <<< Block scale vector, the x-, y- and z-axis scaling factors 46 0.0 <<< Block rotation in radians! 93 -1056964608 <<< Block color (raw value) 47 1.0 <<< start of transformation matrix (16x47) 47 0.0 47 0.0 47 18.427396871473 47 0.0 47 1.0 47 0.0 47 0.702618780008 47 0.0 47 0.0 47 1.0 47 0.0 47 0.0 47 0.0 47 0.0 47 1.0 <<< end of transformation matrix <<< END Block content tags 110 (0.0, 0.0, 0.0) <<< MLEADER plane origin point 111 (1.0, 0.0, 0.0) <<< MLEADER plane x-axis direction 112 (0.0, 1.0, 0.0) <<< MLEADER plane y-axis direction 297 0 <<< MLEADER normal reversed 302 LEADER{ ... 303 } 272 9 273 9 301 } <<< Attribute content and other redundant block data is stored in the AcDbMLeader <<< subclass: 100 AcDbMLeader 270 2 <<< dxf.version 300 CONTEXT_DATA{ <<< start context data ... 301 } <<< end context data 340 #6D <<< dxf.style_handle 90 6816768 <<< dxf.property_override_flags ... <<< property overrides 292 0 <<< dxf.has_frame_text <<< mostly redundant block data: 344 #94 <<< dxf.block_record_handle 93 -1056964608 <<< dxf.block_color (raw value) 10 (1.0, 1.0, 1.0) <<< dxf.block_scale_vector 43 0.0 <<< dxf.block_rotation in radians! 176 0 <<< dxf.block_connection_type 293 0 <<< dxf.is_annotative <<< REPEAT: (optional) 94 <<< arrow head index? 345 <<< arrow head handle <<< REPEAT: (optional) 330 #A3 <<< ATTDEF handle 177 1 <<< ATTDEF index 44 0.0 <<< ATTDEF width 302 B <<< ATTDEF text (reused group code) ... common group codes 294, 178, 179, ... ``` ### MTEXT Internals The MTEXT entity stores multiline text in a single entity and was introduced in DXF version R13/R14. For more information about the top level stuff go to the *MText* class. **SEE ALSO:** - • DXF Reference: *MTEXT* - • *ezdxf.entities.MText* class ### Orientation The MTEXT entity does not establish an OCS. The entity has a **text\_direction** attribute, which defines the local x-axis, the **extrusion** attribute defines the normal vector and the y-axis = extrusion cross x-axis. The MTEXT entity can have also a **rotation** attribute (in degrees), the x-axis attribute has higher priority than the **rotation** attribute, but it is not clear how to convert the **rotation** attribute into a **text\_direction** vector, but for most common cases, where only the **rotation** attribute is present, the **extrusion** is most likely the WCS z-axis and the **rotation** is the direction in the xy-plane. ### Text Content The content text is divided across multiple tags of group code 3 and 1, the last line has the group code 1, each line can have a maximum line length of 255 bytes, but BricsCAD (and AutoCAD?) store only 249 bytes in single line and one byte is not always one char. ### Inline Code Specials The text formatting is done by inline codes, see the *MText* class. Information gathered by implementing the **MTextEditor** and the **MTextParser** classes: - • - **caret encoded characters:** - • “^I” tabulator - • “^J” (LF) is a valid line break like “\\P” - • “^M” (CR) is ignored - • other characters render as empty square “▯” - • a space “ “ after the caret renders the caret glyph: “1^ 2” renders “1^2” - • - **special encoded characters:** - • “%%c” and “%%C” renders “Ø” (alt-0216) - • “%%d” and “%%D” renders “°” (alt-0176) - • “%%p” and “%%P” renders “±” (alt-0177) - • - **Alignment command “\\A”: argument “0”, “1” or “2” is expected** - • the terminator symbol “;” is optional - • the arguments “3”, “4”, “5”, “6”, “7”, “8”, “9” and “-” default to 0 - • other characters terminate the command and will be printed: “\\AX”, renders “X” - • - **ACI color command “\\C”: int argument is expected** - • the terminator symbol “;” is optional - • a leading “-” or “+” terminates the command, “\\C+5” renders “\\C+5” - • arguments \> 255, are ignored but consumed “\\C1000” renders nothing, not even a “0” - • a trailing “;” after integers is always consumed, even for much to big values, “\\C10000;” renders nothing - • - **RGB color command “\\c”: int argument is expected** - • the terminator symbol “;” is optional - • a leading “-” or “+” terminates the command, “\\c+255” renders “\\c+255” - • arguments \>= 16777216 are masked by: value & 0xFFFFFF - • a trailing “;” after integers is always consumed, even for much to big values, “\\c9999999999;” renders nothing and switches the color to yellow (255, 227, 11) - • - **Height command “\\H” and “\\H…x”: float argument is expected** - • the terminator symbol “;” is optional - • a leading “-” is valid, but negative values are ignored - • a leading “+” is valid - • a leading “.” is valid like “\\H.5x” for height factor 0.5 - • exponential format is valid like “\\H1e2” for height factor 100 and “\\H1e-2” for 0.01 - • an invalid floating point value terminates the command, “\\H1..5” renders “\\H1..5” - • - **Other commands with floating point arguments like the height command:** - • Width commands “\\W” and “\\W…x” - • Character tracking commands “\\T” and “\\T…x”, negative values are used - • Slanting (oblique) command “\\Q” - • - **Stacking command “\\S”:** - • build fractions: “numerator (upr)” + “stacking type char (t)” + “denominator (lwr)” + “;” - • divider chars: “^”, “/” or “#” - • a space “ “ after the divider char “^” is mandatory to avoid caret decoding: “\\S1^ 2;” - • the terminator symbol “;” is mandatory to end the command, all chars beyond the “\\S” until the next “;” or the end of the string are part of the fraction - • backslash escape “\\;” to render the terminator char - • a space “ “ after the divider chars “/” and “#” is rendered as space “ ” in front of the denominator - • the numerator and denominator can contain spaces - • backslashes “\\” inside the stacking command are ignored (except “\\;”) “\\S\\N^ \\P” render “N” over “P”, therefore property changes (color, text height, …) are not possible inside the stacking command - • grouping chars “{” and “}” render as simple curly braces - • caret encoded chars are decoded “^I”, “^J”, “^M”, but render as a simple space “ “ or as the replacement char “▯” plus a space - • a divider char after the first divider char, renders as the char itself: “\\S1/2/3” renders the horizontal fraction “1” / “2/3” - • - **Font command “\\f” and “\\F”: export only “\\f”, parse both, “\\F” ignores some arguments** - • the terminator symbol “;” is mandatory to end the command, all chars beyond the “\\f” until the next “;” or the end of the string are part of the command - • the command arguments are separated by the pipe char “\|” - • arguments: “font family name” \| “bold” \| “italic” \| “codepage” \| “pitch”; example “\\fArial\|b0\|i0\|c0\|p0;” - • only the “font family name” argument is required, fonts which are not available on the system are replaced by the “TXT.SHX” shape font - • the “font family name” is the font name shown in font selection widgets in desktop applications - • “b1” to use the bold font style, any other second char is interpreted as “non bold” - • “i1” to use an italic font style, any other second char is interpreted as “non italic” - • “c???” change codepage, “c0” use the default codepage, because of the age of unicode no further investigations, also seems to be ignored by AutoCAD and BricsCAD - • “p???” change pitch size, “p0” means don’t change, ignored by AutoCAD and BricsCAD, to change the text height use the “\\H” command - • the order is not important, but export always in the shown order: “\\fArial\|b0\|i0;” the arguments “c0” and “p0” are not required - • - **Paragraph properties command “\\p”** - • the terminator symbol “;” is mandatory to end the command, all chars beyond the “\\p” until the next “;” or the end of the string are part of the command - • the command arguments are separated by commas “,” - • all values are factors for the initial char height of the MTEXT entity, example: char height = 2.5, “\\pl1;” set the left paragraph indentation to 1 x 2.5 = 2.5 drawing units. - • all values are floating point values, see height command - • arguments are “i”, “l”, “r”, “q”, “t” - • a “\*” as argument value, resets the argument to the initial value: “i0”, “l0”, “r0”, the “q” argument most likely depends on the text direction; I haven’t seen “t\*”. The sequence used by BricsCAD to reset all values is **"\\pi\*,l\*,r\*,q\*,t;"** - • “i” indentation of the first line relative to the “l” argument as floating point value, “\\pi1.5” - • “l” left paragraph indentation as floating point value, “\\pl1.5” - • “r” right paragraph indentation as floating point value, “\\pr1.5” - • “x” is required if a “q” or a “t” argument is present, the placement of the “x” has no obvious rules - • “q” paragraph alignment - • “ql” left paragraph alignment - • “qr” right paragraph alignment - • “qc” center paragraph alignment - • “qj” justified paragraph alignment - • “qd” distributed paragraph alignment - • “t” tabulator stops as comma separated list, the default tabulator stops are located at 4, 8, 12, …, by defining at least one tabulator stop, the default tabulator stops will be ignored. There 3 kind of tabulator stops: left, right and center adjusted stops, e.g. “pxt1,r5,c8”: - • a left adjusted stop has no leading char, two left adjusted stops “\\pxt1,2;” - • a right adjusted stop has a preceding “r” char, “\\pxtr1,r2;” - • a center adjusted stop has a preceding “c” char, “\\pxtc1,c2;” complex example to create a numbered list with two items: **"pxi-3,l4t4;1.^Ifirst item\\P2.^Isecond item"** - • a parser should be very flexible, I have seen several different orders of the arguments and placing the sometimes required “x” has no obvious rules. - • exporting seems to be safe to follow these three rules: - 1\. the command starts with “\\px”, the “x” does no harm, if not required - 2\. argument order “i”, “l”, “r”, “q”, “t”, any of the arguments can be left off - 3\. terminate the command with a “;” ### Height Calculation There is no reliable way to calculate the MTEXT height from the existing DXF attributes. The **rect\_height** (group code 43) attribute is not required and seldom present. DXF R2007 introduced the **defined\_height** attribute to store the defined column height of the MTEXT entity but only in column mode. MTEXT entities without columns, except MTEXT entities created with column type “No Columns”, store always 0.0 as defined column height. Which seems to mean: defined by the rendered text content. The only way to calculate the MTEXT height is to replicate the rendering results of AutoCAD/BricsCAD by implementing a rendering engine for MTEXT. In column mode the MTEXT height is stored for every column for DXF version before R2018. In DXF R2018+ the column heights are only stored if **MTextColumns.auto\_height** is **False**. If **MTextColumns.auto\_height** is **True**. But DXF R2018+ stores the MTEXT total width and height in explicit attributes. ### Width Calculation The situation for width calculation is better than for the height calculation, but the attributes **width** and **rect\_width** are not mandatory. There is a difference between MTEXT entities with and without columns: Without columns the attribute **width** (reference column width) contains the true entity width if present. A long word can overshoot this width! The **rect\_width** attribute is seldom present. For MTEXT with columns, the **width** attribute is maybe wrong, the correct width for a column is stored in the **column\_width** attribute and the **total\_width** attribute stores the total width of the MTEXT entity overall columns, see also following section “Column Support”. ### Background Filling The background fill support is available for DXF R2007+. The group code 90 defines the kind of background fill: | | | | --- | --- | | 0 | off | | 1 | color defined by group code 63, 421 or 431 | | 2 | drawing window color | | 3 | background (canvas) color | | 16 | bit-flag text frame, see Open Design Alliance Specification 20.4.46 | Group codes to define background fill attributes: | | | | --- | --- | | 45 | scaling factor for the border around the text, the value should be in the range of \[1, 5\], where 1 fits exact the MText entity | | 63 | set the background color by *ACI*. | | 421 | set the background color as *true-color* value. | | 431 | set the background color by color name - no idea how this works | | 441 | set the transparency of the background fill, not supported by AutoCAD or BricsCAD. | Group codes 45, 90 and 63 are required together if one of them is used. The group code 421 and 431 also requires the group code 63, even this value is ignored. ``` ... 1 eu feugiat nulla facilisis at vero eros et accumsan et iusto ... 73 1 44 1.0 90 1, b00000001 <<< use a color 63 1 <<< ACI color (red) 45 1.5 <<< bg scaling factor, relative to the char height 441 0 <<< ignored (optional) ... ``` \[image\] The background scaling does not alter the **width**, **column\_width** or **total\_width** attributes. The background acquires additional space around the MTEXT entity. Columns with background color: \[image\] ### Text Frame The MTEXT entity can have a text frame only, without a background filling, group code 90 has value 16. In this case all other background related tags are removed (45, 63, 421, 431, 441) and the scaling factor is 1.5 by default. ### XDATA for Text Frame This XDATA exist only if the text frame flag in group code 90 is set and for DXF version \< R2018! ``` ... 1001 ACAD 1000 ACAD_MTEXT_TEXT_BORDERS_BEGIN 1070 80 <<< group code for repeated flags 1070 16 <<< repeated group code 90? 1070 46 <<< group code for scaling factor, which is fixed? 1040 1.5 <<< scaling factor 1070 81 <<< group code for repeated flow direction? 1070 1 <<< flow direction? 1070 5 <<< group code for a handle, multiple entries possible 1005 #A8 <<< handle to the LWPOLYLINE text frame 1070 5 <<< group code for next handle 1005 #A9 <<< next handle ... 1000 ACAD_MTEXT_TEXT_BORDERS_END ``` ### Extra LWPOLYLINE Entity as Text Frame The newer versions of AutoCAD and BricsCAD get all the information they need from the MTEXT entity, but it seems that older versions could not handle the text frame property correct. Therefore AutoCAD and BricsCAD create a separated LWPOLYLINE entity for the text frame for DXF versions \< R2018. The handle to this text frame entity is stored in the XDATA as group code 1005, see section above. Because this LWPOLYLINE is not required *ezdxf* does **not** create such a text frame entity nor the associated XDATA and *ezdxf* also **removes** this data from loaded DXF files at the second loading stage. ### Column Support CAD applications build multiple columns by linking 2 or more MTEXT entities together. In this case each column is a self-sufficient entity in DXF version R13 until R2013. The additional columns specifications are stored in the XDATA if the MTEXT which represents the first column. DXF R2018 changed the implementation into a single MTEXT entity which contains all the content text at once and stores the column specification in an embedded object. **HINT:** The **width** attribute for the linked MTEXT entities could be wrong. Always use the **column\_width** and the **total\_width** attributes in column mode. There are two column types, the **static** type has the same column height for all columns, the **dynamic** type can have the same (auto) height or an individual height for each column. Common facts about columns for all column types: - • all columns have the same column width - • all columns have the same gutter width - • the top of the column are at the same height ### Column Type The column type defines how a CAD application should create the columns, this is not important for the file format, because the result of this calculation, the column count and the column height, is stored the DXF file. | | | | --- | --- | | Column Type in BricsCAD | Description | | Static | All columns have the same height. The “auto height” flag is 0. | | Dynamic (auto height) | Same as the static type, all columns have the same height. The “auto height” flag is 1. The difference to the static type is only important for interactive CAD applications. | | Dynamic (manual height) | same as the dynamic (auto height) type, but each column can have an individual height. | | No column | A regular MTEXT with “defined column height” attribute? | | | | | | | --- | --- | --- | --- | | Column Type | Defined Height | Auto Height | Column Heights | | Static | stored | False | not stored | | Dynamic auto | stored | True | not stored | | Dynamic manual | not stored | False | stored (last=0) | ### Column Count For DXF versions \< R2018 the column count is always given by the count of linked MTEXT columns. Caution: the column count stored in the XDATA section by group code 76 may not match the count of linked MTEXT entities and AutoCAD is OK with that! In DXF R2018+ this property is not available, because there are no linked MTEXT entities anymore. R2018+: For the column types “static” and “dynamic manual” the correct column count is stored as group code 72. For the column type “dynamic auto” the stored *column count is 0*. It is possible to calculate the column count from the total width and the column width if the total width is correct like in AutoCAD and BricsCAD. ### Static Columns R2000 Example for a **static** column specification: - • Column Type: Static - • Number of Columns: 3 - • Height: 150.0, manual entered value and all columns have the same height - • Width: 50.0 - • Gutter Width: 12.5 \[image\] The column height is stored as the “defined column height” in XDATA (46) or the embedded object (41). DXF R2000 example with a static column specification stored in XDATA: ``` 0 MTEXT 5 <<< entity handle 9D 102 {ACAD_XDICTIONARY 360 9F 102 } 330 <<< block record handle of owner layout 1F 100 AcDbEntity 8 <<< layer 0 100 <<< begin of MTEXT specific data AcDbMText 10 <<< (10, 20, 30) insert location in WCS 285.917876152751 20 276.101821192053 30 0.0 40 <<< character height in drawing units 2.5 41 <<< reference column width, if not in column mode 62.694... <<< in column mode: the real column is defined in XDATA (48) 71 <<< attachment point 1 72 <<< text flow direction 1 3 <<< begin of text Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam ... 3 kimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit ... 3 ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ... 3 At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd ... 3 ore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio ... 1 <<< last text line and end of text euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. 73 <<< line spacing style 1 44 <<< line spacing factor 1.0 1001 AcadAnnotative 1000 AnnotativeData 1002 { 1070 1 1070 0 1002 } 1001 <<< AppID "ACAD" contains the column specification ACAD 1000 ACAD_MTEXT_COLUMN_INFO_BEGIN 1070 75 <<< group code column type 1070 1 <<< column type: 0=no column; 1=static columns; 2=dynamic columns 1070 79 <<< group code column auto height 1070 0 <<< flag column auto height 1070 76 <<< group code column count 1070 3 <<< column count 1070 78 <<< group code column flow reversed 1070 0 <<< flag column flow reversed 1070 48 <<< group code column width 1040 50.0 <<< column width in column mode 1070 49 <<< group code column gutter 1040 12.5 <<< column gutter width 1000 ACAD_MTEXT_COLUMN_INFO_END 1000 <<< linked MTEXT entities specification ACAD_MTEXT_COLUMNS_BEGIN 1070 47 <<< group code for column count, incl. the 1st column - this entity 1070 3 <<< column count 1005 1B4 <<< handle to 2nd column as MTEXT entity 1005 1B5 <<< handle to 3rd column as MTEXT entity 1000 ACAD_MTEXT_COLUMNS_END 1000 ACAD_MTEXT_DEFINED_HEIGHT_BEGIN 1070 46 <<< group code for defined column height 1040 150.0 <<< defined column height 1000 ACAD_MTEXT_DEFINED_HEIGHT_END ``` The linked column MTEXT **#1B4** in a compressed representation: ``` 0 MTEXT ... 100 AcDbMText 10 (348.417876152751, 276.101821192053, 0.0) 40 2.5 41 175.0 <<< invalid reference column width ... 1001 ACAD 1000 ACAD_MTEXT_DEFINED_HEIGHT_BEGIN 1070 46 <<< defined column height 1040 150.0 1000 ACAD_MTEXT_DEFINED_HEIGHT_END ``` The linked MTEXT has no column specification except the “defined column height” in the XDATA. The reference column **width** is not the real value of 50.0, see XDATA group code 48 in the main MTEXT **#9D**, instead the total width of 175.0 is stored at group code 41. This is problem if a renderer try to render this MTEXT as a standalone entity. The renderer has to fit the content into the column width by itself and without the correct column width, this will produce an incorrect result. There exist no back link to the main MTEXT **#9D**. The linked MTEXT entities appear after the main MTEXT in the layout space, but there can be other entities located between these linked MTEXT entities. The linked column MTEXT **#1B5**: ``` 0 MTEXT 5 #1B5 ... 100 AcDbMText 10 (410.917876152751, 276.101821192053, 0.0) 40 2.5 41 175.0 <<< invalid reference column width ... 1001 ACAD 1000 ACAD_MTEXT_DEFINED_HEIGHT_BEGIN 1070 46 <<< defined column height 1040 150.0 1000 ACAD_MTEXT_DEFINED_HEIGHT_END ``` ### Static Columns R2018 The MTEXT entity in DXF R2018 contains all column information in a single entity. The text content of all three columns are stored in a continuous text string, the separation into columns has to be done by the renderer. The manual column break **\\N** is **not** used to indicate automatic column breaks. The MTEXT renderer has to replicate the AutoCAD/BricsCAD rendering as exact as possible to achieve the same results, which is very hard without rendering guidelines or specifications. The example from above in DXF R2018 with a static column specification stored in an embedded object: ``` 0 MTEXT 5 <<< entity handle 9D 102 {ACAD_XDICTIONARY 360 9F 102 } 330 <<< block record handle of owner layout 1F 100 AcDbEntity 8 <<< layer 0 100 AcDbMText 10 <<< (10, 20, 30) insert location in WCS 285.917876152751 20 276.101821192053 30 0.0 40 <<< character height in drawing units 2.5 41 <<< reference column width, if not in column mode 62.694536423841 46 <<< defined column height 150.0 71 <<< attachment point 1 72 <<< text flow direction 1 3 <<< text content of all three columns Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam n... 3 imata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit... 3 a rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lor... 3 vero eos et accusam et justo duo dolores et ea rebum. Stet clita ka... 3 eu feugiat nulla facilisis at vero eros et accumsan et iusto odio s... 3 od tincidunt ut laoreet dolore magna aliquam erat volutpat. \P\PU... 3 e velit esse molestie consequat, vel illum dolore eu feugiat nulla ... 3 obis eleifend option congue nihil imperdiet doming id quod mazim pl... 3 m ad minim veniam, quis nostrud exerci tation ullamcorper suscipit ... 3 lisis. \P\PAt vero eos et accusam et justo duo dolores et ea rebu... 3 t labore et dolore magna aliquyam erat, sed diam voluptua. At vero ... 3 litr, At accusam aliquyam diam diam dolore dolores duo eirmod eos e... 1 ipsum dolor sit amet, consetetur 73 <<< line spacing style 1 44 <<< line spacing factor 1.0 101 <<< column specification as embedded object Embedded Object 70 <<< ??? 1 10 <<< (10, 20, 30) text direction vector (local x-axis) 1.0 20 0.0 30 0.0 11 <<< (11, 21, 31) repeated insert location of AcDbMText 285.917876152751 21 276.101821192053 31 0.0 40 <<< repeated reference column width 62.694536423841 41 <<< repeated defined column height 150.0 42 <<< extents (total) width 175.0 43 <<< extents (total) height, max. height if different column heights 150.0 71 <<< column type: 0=no column; 1=static columns; 2=dynamic columns 1 72 <<< column height count 3 44 <<< column width 50.0 45 <<< column gutter width 12.5 73 <<< flag column auto height 0 74 <<< flag reversed column flow 0 1001 AcadAnnotative 1000 AnnotativeData 1002 { 1070 1 1070 0 1002 } ``` ### Dynamic (auto height) Columns R2000 Example for a **dynamic** column specification: - • Column Type: Dynamic - • Number of Columns: 3 - • Height: 158.189… adjusted by widget and all columns have the same height - • Width: 50.0 - • Gutter Width: 12.5 ``` 0 MTEXT 5 #A2 <<< entity handle ... 330 #1F <<< block record handle of owner layout 100 AcDbEntity 8 0 <<< layer 100 AcDbMText 10 (-133.714579865783, 276.101821192053, 0.0) <<< insert location in WCS 40 2.5 <<< character height in drawing units 41 62.694536423841 <<< reference column width, if not in column mode 71 1 <<< attachment point 72 1 <<< flag text flow direction 3 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed dia... ... 73 1 <<< line spacing style 44 1.0 <<< line spacing factor 1001 AcadAnnotative ... 1001 ACAD 1000 ACAD_MTEXT_COLUMN_INFO_BEGIN 1070 75 <<< column type: 2=dynamic columns 1070 2 1070 79 <<< flag column auto height 1070 1 1070 76 <<< column count 1070 3 1070 78 <<< flag column flow reversed 1070 0 1070 48 <<< column width in column mode 1040 50.0 1070 49 <<< column gutter width 1040 12.5 1000 ACAD_MTEXT_COLUMN_INFO_END 1000 ACAD_MTEXT_COLUMNS_BEGIN 1070 47 <<< column count 1070 3 1005 #1B6 <<< handle to 2. column as MTEXT entity 1005 #1B7 <<< handle to 3. column as MTEXT entity 1000 ACAD_MTEXT_COLUMNS_END 1000 ACAD_MTEXT_DEFINED_HEIGHT_BEGIN 1070 46 <<< defined column height 1040 158.189308131867 1000 ACAD_MTEXT_DEFINED_HEIGHT_END ``` The linked column MTEXT **#1B6**: ``` 0 MTEXT ... 100 AcDbMText 10 (-71.214579865783, 276.101821192053, 0.0) 40 2.5 41 175.0 <<< invalid column width ... 1001 ACAD 1000 ACAD_MTEXT_DEFINED_HEIGHT_BEGIN 1070 46 <<< defined column height 1040 158.189308131867 1000 ACAD_MTEXT_DEFINED_HEIGHT_END ``` The linked column MTEXT **#1B7**: ``` 0 MTEXT ... 100 AcDbMText 10 (-8.714579865783, 276.101821192053, 0.0) 40 2.5 41 175.0 <<< invalid column width ... 1001 ACAD 1000 ACAD_MTEXT_DEFINED_HEIGHT_BEGIN 1070 46 <<< defined column height 1040 158.189308131867 1000 ACAD_MTEXT_DEFINED_HEIGHT_END ``` ### Dynamic (auto height) Columns R2018 ``` 0 MTEXT 5 #A2 <<< entity handle 102 {ACAD_XDICTIONARY 360 #A3 102 } 330 #1F <<< block record handle of owner layout 100 AcDbEntity 8 0 <<< layer 100 AcDbMText 10 (-133.714579865783, 276.101821192053, 0.0) <<< insert location in WCS 40 2.5 <<< character height in drawing units 41 62.694536423841 <<< reference column width, if not in column mode 46 158.189308131867 <<< defined column height 71 1 <<< attachment point 72 1 <<< text flow direction 3 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam... ... text content of all three columns 73 1 <<< line spacing style 44 1.0 <<< line spacing factor 101 Embedded Object 70 1, b00000001 <<< ??? 10 (1.0, 0.0, 0.0) <<< text direction vector (local x-axis) 11 (-133.714579865783, 276.101821192053, 0.0) <<< repeated insert location 40 62.694536423841 <<< repeated reference column width 41 158.189308131867 <<< repeated defined column height 42 175.0 <<< extents (total) width 43 158.189308131867 <<< extents (total) height, max. height if different column heights 71 2 <<< column type: 2=dynamic columns 72 0 <<< column height count 44 50.0 <<< column width 45 12.5 <<< column gutter width 73 1 <<< flag column auto height 74 0 <<< flag reversed column flow 1001 AcadAnnotative 1000 AnnotativeData 1002 { 1070 1 1070 0 1002 } ``` ### Dynamic (manual height) Columns R2000 Example for a **dynamic** column specification with manual height definition for three columns with different column heights. None of the (linked) MTEXT entities does contain XDATA for the defined column height. **HINT:** If “content type” is 2 and flag “column auto height” is 0, no defined height in XDATA. - • Column Type: Dynamic - • Number of Columns: 3 - • Height: 164.802450331126, max. column height - • Width: 50.0 - • Gutter Width: 12.5 \[image\] ``` 0 MTEXT 5 #9C <<< entity handle 330 #1F <<< block record handle of owner layout 100 AcDbEntity 8 0 <<< layer 100 AcDbMText 10 (69.806121185863, 276.101821192053, 0.0) <<< insert location in WCS 40 2.5 <<< character height in drawing units 41 62.694536423841 <<< reference column width, if not in column mode 71 1 <<< attachment point 72 1 <<< flag text flow direction 3 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, ... ... 73 1 <<< line spacing style 44 1.0 <<< line spacing factor 1001 ACAD 1000 ACAD_MTEXT_COLUMN_INFO_BEGIN 1070 75 <<< column type: 2=dynamic columns 1070 2 1070 79 <<< flag column auto height 1070 0 1070 76 <<< column count 1070 3 1070 78 <<< flag column flow reversed 1070 0 1070 48 <<< column width in column mode 1040 50.0 1070 49 <<< column gutter width 1040 12.5 1070 50 <<< column height count 1070 3 1040 164.802450331126 <<< column height 1. column 1040 154.311699779249 <<< column height 2. column 1040 0.0 <<< column height 3. column, takes the rest? 1000 ACAD_MTEXT_COLUMN_INFO_END 1000 ACAD_MTEXT_COLUMNS_BEGIN 1070 47 <<< column count 1070 3 1005 #1B2 <<< handle to 2. column as MTEXT entity 1005 #1B3 <<< handle to 3. column as MTEXT entity 1000 ACAD_MTEXT_COLUMNS_END ``` The linked column MTEXT **#1B2**: ``` 0 MTEXT ... 100 AcDbMText 10 (132.306121185863, 276.101821192053, 0.0) 40 2.5 41 175.0 <<< invalid reference column width ... 73 1 44 1.0 ``` The linked column MTEXT **#1B3**: ``` 0 MTEXT ... 100 AcDbMText 10 (194.806121185863, 276.101821192053, 0.0) 40 2.5 41 175.0 <<< invalid reference column width ... 73 1 44 1.0 ``` ### Dynamic (manual height) Columns R2018 **HINT:** If “content type” is 2 and flag “column auto height” is 0, the “defined column height” is 0.0. ``` 0 MTEXT 5 #9C <<< entity handle 330 #1F 100 AcDbEntity 8 0 <<< block record handle of owner layout 100 AcDbMText 10 (69.806121185863, 276.101821192053, 0.0) <<< insert location in WCS 40 2.5 <<< character height in drawing units 41 62.694536423841 <<< reference column width, if not in column mode 46 0.0 <<< defined column height 71 1 <<< attachment point 72 1 <<< text flow direction 3 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam... ... text content of all three columns 73 1 <<< line spacing style 44 1.0 <<< line spacing factor 101 Embedded Object 70 1, b00000001 <<< ??? 10 (1.0, 0.0, 0.0) <<< text direction vector (local x-axis) 11 (69.806121185863, 276.101821192053, 0.0) <<< repeated insert location 40 62.694536423841 <<< repeated reference column width 41 0.0 <<< repeated defined column height 42 175.0 <<< extents (total) width 43 164.802450331126 <<< extents (total) height, max. height if different column heights 71 2 <<< column type: 2=dynamic columns 72 3 <<< column height count 44 50.0 <<< column width 45 12.5 <<< column gutter width 73 0 <<< flag column auto height 74 0 <<< flag reversed column flow 46 164.802450331126 <<< column height 1. column 46 154.311699779249 <<< column height 2. column 46 0.0 <<< column height 3. column, takes the rest? ``` ### No Columns R2000 I have no idea why this column type exist, but at least provides a reliable value for the MTEXT height by the “defined column height” attribute. The column type is not stored in the MTEXT entity and is therefore not detectable! - • Column Type: No columns - • Number of Columns: 1 - • Height: 158.189308131867, defined column height - • Width: 175.0, reference column width ``` 0 MTEXT ... 100 AcDbMText 10 (-344.497343455795, 276.101821192053, 0.0) <<< insert location in WCS 40 2.5 <<< character height in drawing units 41 175.0 <<< reference column width 71 1 <<< attachment point 72 1 <<< flag text flow direction 3 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam... ... text content of all three columns 73 1 <<< line spacing style 44 1.0 <<< line spacing factor ... 1001 ACAD 1000 ACAD_MTEXT_DEFINED_HEIGHT_BEGIN 1070 46 <<< defined column height 1040 158.189308131867 1000 ACAD_MTEXT_DEFINED_HEIGHT_END ``` ### No Columns R2018 Does not contain an embedded object. ``` 0 MTEXT ... 100 AcDbMText 10 (-334.691900433414, 276.101821192053, 0.0) <<< insert location in WCS 40 2.5 <<< character height in drawing units 41 175.0 <<< reference column width 46 158.189308131867 <<< defined column height 71 1 <<< attachment point 72 1 <<< flag text flow direction 3 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, ... ... 73 1 <<< line spacing style 44 1.0 <<< line spacing factor 1001 AcadAnnotative ... ``` ### DXF Objects TODO ### Management Structures ### Block Management Structures A BLOCK is a layout like the modelspace or a paperspace layout, with the similarity that all these layouts are containers for graphical DXF entities. This block definition can be referenced in other layouts by the INSERT entity. By using block references, the same set of graphical entities can be located multiple times at different layouts, this block references can be stretched and rotated without modifying the original entities. A block is referenced only by its name defined by the DXF tag **(2, name)**, there is a second DXF tag **(3, name2)** for the block name, which is not further documented by Autodesk, just ignore it. The **(10, base\_point)** tag (in BLOCK defines a insertion point of the block, by ‘inserting’ a block by the INSERT entity, this point of the block is placed at the location defined by the **(10, insert)** tag in the INSERT entity, and it is also the base point for stretching and rotation. A block definition can contain INSERT entities, and it is possible to create cyclic block definitions (a BLOCK contains a INSERT of itself), but this should be avoided, CAD applications will not load the DXF file at all or maybe just crash. This is also the case for all other kinds of cyclic definitions like: BLOCK “A” -\> INSERT BLOCK “B” and BLOCK “B” -\> INSERT BLOCK “A”. **SEE ALSO:** - • ezdxf DXF Internals: *BLOCKS Section* - • DXF Reference: *BLOCKS Section* - • DXF Reference: *BLOCK Entity* - • DXF Reference: *ENDBLK Entity* - • DXF Reference: *INSERT Entity* ### Block Names Block names has to be unique and they are case insensitive (“Test” == “TEST”). If there are two or more block definitions with the same name, AutoCAD merges these blocks into a single block with unpredictable properties of all these blocks. In my test with two blocks, the final block has the name of the first block and the base-point of the second block, and contains all entities of both blocks. ### Block Definitions in DXF R12 In DXF R12 the definition of a block is located in the BLOCKS section, no additional structures are needed. The definition starts with a BLOCK entity and ends with a ENDBLK entity. All entities between this two entities are the content of the block, the block is the owner of this entities like any layout. As shown in the DXF file below (created by AutoCAD LT 2018), the BLOCK entity has no handle, but ezdxf writes also handles for the BLOCK entity and AutoCAD doesn’t complain. DXF R12 BLOCKS structure: ``` 0 <<< start of a SECTION SECTION 2 <<< start of BLOCKS section BLOCKS ... <<< modelspace and paperspace block definitions not shown, ... <<< see layout management ... 0 <<< start of a BLOCK definition BLOCK 8 <<< layer 0 2 <<< block name ArchTick 70 <<< flags 1 10 <<< base point, x 0.0 20 <<< base point, y 0.0 30 <<< base point, z 0.0 3 <<< second BLOCK name, same as (2, name) ArchTick 1 <<< xref name, if block is an external reference <<< empty string! 0 <<< start of the first entity of the BLOCK LINE 5 28E 8 0 62 0 10 500.0 20 500.0 30 0.0 11 500.0 21 511.0 31 0.0 0 <<< start of the second entity of the BLOCK LINE ... 0.0 0 <<< ENDBLK entity, marks the end of the BLOCK definition ENDBLK 5 <<< ENDBLK gets a handle by AutoCAD, but BLOCK didn't 2F2 8 <<< as every entity, also ENDBLK requires a layer (same as BLOCK entity!) 0 0 <<< start of next BLOCK entity BLOCK ... 0 <<< end BLOCK entity ENDBLK 0 <<< end of BLOCKS section ENDSEC ``` ### Block Definitions in DXF R2000+ The overall organization in the BLOCKS sections remains the same, but additional tags in the BLOCK entity, have to be maintained. Especially the concept of ownership is important. Since DXF R13 every graphic entity is associated to a specific layout and a BLOCK definition is also a layout. So all entities in the BLOCK definition, including the BLOCK and the ENDBLK entities, have an owner tag **(330, ...)**, which points to a BLOCK\_RECORD entry in the BLOCK\_RECORD table. This BLOCK\_RECORD is the main management structure for all layouts and is the real owner of the layout entities. As you can see in the chapter about *Layout Management Structures*, this concept is also valid for modelspace and paperspace layouts, because these layouts are also BLOCKS, with the special difference, that the entities of the modelspace and the *active* paperspace layout are stored in the ENTITIES section. \[image\] **SEE ALSO:** - • *DXF R13 and later tag structure* - • ezdxf DXF Internals: *TABLES Section* - • DXF Reference: *TABLES Section* - • DXF Reference: *BLOCK\_RECORD Entity* DXF R13 BLOCKS structure: ``` 0 <<< start of a SECTION SECTION 2 <<< start of BLOCKS section BLOCKS ... <<< modelspace and paperspace block definitions not shown, ... <<< see layout management 0 <<< start of BLOCK definition BLOCK 5 <<< even BLOCK gets a handle now ;) 23A 330 <<< owner tag, the owner of a BLOCK is a BLOCK_RECORD in the ... BLOCK_RECORD table 238 100 <<< subclass marker AcDbEntity 8 <<< layer of the BLOCK definition 0 100 <<< subclass marker AcDbBlockBegin 2 <<< BLOCK name ArchTick 70 <<< flags 0 10 <<< base point, x 0.0 20 <<< base point, y 0.0 30 <<< base point, z 0.0 3 <<< second BLOCK name, same as (2, name) ArchTick 1 <<< xref name, if block is an external reference <<< empty string! 0 <<< start of the first entity of the BLOCK LWPOLYLINE 5 239 330 <<< owner tag of LWPOLYLINE 238 <<< handle of the BLOCK_RECORD! 100 AcDbEntity 8 0 6 ByBlock 62 0 100 AcDbPolyline 90 2 70 0 43 0.15 10 -0.5 20 -0.5 10 0.5 20 0.5 0 <<< ENDBLK entity, marks the end of the BLOCK definition ENDBLK 5 <<< handle 23B 330 <<< owner tag, same BLOCK_RECORD as for the BLOCK entity 238 100 <<< subclass marker AcDbEntity 8 <<< ENDBLK requires the same layer as the BLOCK entity! 0 100 <<< subclass marker AcDbBlockEnd 0 <<< start of the next BLOCK BLOCK ... 0 ENDBLK ... 0 <<< end of the BLOCKS section ENDSEC ``` DXF R13 BLOCK\_RECORD structure: ``` 0 <<< start of a SECTION SECTION 2 <<< start of TABLES section TABLES 0 <<< start of a TABLE TABLE 2 <<< start of the BLOCK_RECORD table BLOCK_RECORD 5 <<< handle of the table 1 330 <<< owner tag of the table 0 <<< is always #0 100 <<< subclass marker AcDbSymbolTable 70 <<< count of table entries, not reliable 4 0 <<< start of first BLOCK_RECORD entry BLOCK_RECORD 5 <<< handle of BLOCK_RECORD, in ezdxf often referred to as "layout key" 1F 330 <<< owner of the BLOCK_RECORD is the BLOCK_RECORD table 1 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbBlockTableRecord 2 <<< name of the BLOCK or LAYOUT *Model_Space 340 <<< pointer to the associated LAYOUT object 4AF 70 <<< AC1021 (R2007) block insertion units 0 280 <<< AC1021 (R2007) block explodability 1 281 <<< AC1021 (R2007) block scalability 0 ... <<< paperspace not shown ... 0 <<< next BLOCK_RECORD BLOCK_RECORD 5 <<< handle of BLOCK_RECORD, in ezdxf often referred to as "layout key" 238 330 <<< owner of the BLOCK_RECORD is the BLOCK_RECORD table 1 100 <<< subclass marker AcDbSymbolTableRecord 100 <<< subclass marker AcDbBlockTableRecord 2 <<< name of the BLOCK ArchTick 340 <<< pointer to the associated LAYOUT object 0 <<< #0, because BLOCK doesn't have an associated LAYOUT object 70 <<< AC1021 (R2007) block insertion units 0 280 <<< AC1021 (R2007) block explodability 1 281 <<< AC1021 (R2007) block scalability 0 0 <<< end of BLOCK_RECORD table ENDTAB 0 <<< next TABLE TABLE ... 0 ENDTAB 0 <<< end of TABLES section ENDESC ``` ### Layout Management Structures Layouts are separated entity spaces, there are three different Layout types: - 1\. modelspace contains the ‘real’ world representation of the drawing subjects in real world units. - 2\. paperspace layouts are used to create different drawing sheets of the modelspace subjects for printing or PDF export - 3\. Blocks are reusable sets of graphical entities, inserted/referenced by the INSERT entity. All layouts have at least a BLOCK definition in the BLOCKS section and since DXF R13 exist the BLOCK\_RECORD table with an entry for every BLOCK in the BLOCKS section. **SEE ALSO:** Information about *Block Management Structures* The name of the modelspace BLOCK is “\*Model\_Space” (DXF R12: “$MODEL\_SPACE”) and the name of the *active* paperspace BLOCK is “\*Paper\_Space” (DXF R12: “$PAPER\_SPACE”), the entities of these two layouts are stored in the ENTITIES section, DXF R12 supports just one paperspace layout. DXF R13+ supports multiple paperspace layouts, the *active* layout is still called “\*Paper\_Space”, the additional *inactive* paperspace layouts are named by the scheme “\*Paper\_Spacennnn”, where the first inactive paper space is called “\*Paper\_Space0”, the second “\*Paper\_Space1” and so on. A none consecutive numbering is tolerated by AutoCAD. The content of the inactive paperspace layouts are stored as BLOCK content in the BLOCKS section. These names are just the DXF internal layout names, each layout has an additional layout name which is displayed to the user by the CAD application. A BLOCK definition and a BLOCK\_RECORD is not enough for a proper layout setup, an LAYOUT entity in the OBJECTS section is also required. All LAYOUT entities are managed by a DICTIONARY entity, which is referenced as “ACAD\_LAYOUT” entity in the root DICTIONARY of the DXF file. **NOTE:** All floating point values are rounded to 2 decimal places for better readability. ### LAYOUT Entity Since DXF R2000 modelspace and paperspace layouts require the DXF *LAYOUT* entity. ``` 0 LAYOUT 5 <<< handle 59 102 <<< extension dictionary (ignore) {ACAD_XDICTIONARY 360 1C3 102 } 102 <<< reactor (required?) {ACAD_REACTORS 330 1A <<< pointer to "ACAD_LAYOUT" DICTIONARY (layout management table) 102 } 330 <<< owner handle 1A <<< pointer to "ACAD_LAYOUT" DICTIONARY (same as reactor pointer) 100 <<< PLOTSETTINGS AcDbPlotSettings 1 <<< page setup name 2 <<< name of system printer or plot configuration file none_device 4 <<< paper size, part in braces should follow the schema ... (width_x_height_unit) unit is 'Inches' or 'MM' ... Letter\_(8.50_x_11.00_Inches) the part in front of the braces is ... ignored by AutoCAD 6 <<< plot view name 40 <<< size of unprintable margin on left side of paper in millimeters, ... defines also the plot origin-x 6.35 41 <<< size of unprintable margin on bottom of paper in millimeters, ... defines also the plot origin-y 6.35 42 <<< size of unprintable margin on right side of paper in millimeters 6.35 43 <<< size of unprintable margin on top of paper in millimeters 6.35 44 <<< plot paper size: physical paper width in millimeters 215.90 45 <<< plot paper size: physical paper height in millimeters 279.40 46 <<< X value of plot origin offset in millimeters, moves the plot origin-x 0.0 47 <<< Y value of plot origin offset in millimeters, moves the plot origin-y 0.0 48 <<< plot window area: X value of lower-left window corner 0.0 49 <<< plot window area: Y value of lower-left window corner 0.0 140 <<< plot window area: X value of upper-right window corner 0.0 141 <<< plot window area: Y value of upper-right window corner 0.0 142 <<< numerator of custom print scale: real world (paper) units, 1.0 ... for scale 1:50 1.0 143 <<< denominator of custom print scale: drawing units, 50.0 ... for scale 1:50 1.0 70 <<< plot layout flags, bit-coded (... too many options) 688 <<< b1010110000 = UseStandardScale(16)/PlotPlotStyle(32) ... PrintLineweights(128)/DrawViewportsFirst(512) 72 <<< plot paper units (0/1/2 for inches/millimeters/pixels), are ... pixels really supported? 0 73 <<< plot rotation (0/1/2/3 for 0deg/90deg counter-cw/upside-down/90deg cw) 1 <<< 90deg clockwise 74 <<< plot type 0-5 (... too many options) 5 <<< 5 = layout information 7 <<< current plot style name, e.g. 'acad.ctb' or 'acadlt.ctb' 75 <<< standard scale type 0-31 (... too many options) 16 <<< 16 = 1:1, also 16 if user scale type is used 147 <<< unit conversion factor 1.0 <<< for plot paper units in mm, else 0.03937... (1/25.4) for inches ... as plot paper units 76 <<< shade plot mode (0/1/2/3 for as displayed/wireframe/hidden/rendered) 0 <<< as displayed 77 <<< shade plot resolution level 1-5 (... too many options) 2 <<< normal 78 <<< shade plot custom DPI: 100-32767, Only applied when shade plot ... resolution level is set to 5 (Custom) 300 148 <<< paper image origin: X value 0.0 149 <<< paper image origin: Y value 0.0 100 <<< LAYOUT settings AcDbLayout 1 <<< layout name Layout1 70 <<< flags bit-coded 1 <<< 1 = Indicates the PSLTSCALE value for this layout when this ... layout is current 71 <<< Tab order ("Model" tab always appears as the first tab ... regardless of its tab order) 1 10 <<< minimum limits for this layout (defined by LIMMIN while this ... layout is current) -0.25 <<< x value, distance of the left paper margin from the plot ... origin-x, in plot paper units and by scale (e.g. x50 for 1:50) 20 <<< group code for y value -0.25 <<< y value, distance of the bottom paper margin from the plot ... origin-y, in plot paper units and by scale (e.g. x50 for 1:50) 11 <<< maximum limits for this layout (defined by LIMMAX while this ... layout is current) 10.75 <<< x value, distance of the right paper margin from the plot ... origin-x, in plot paper units and by scale (e.g. x50 for 1:50) 21 <<< group code for y value 8.25 <<< y value, distance of the top paper margin from the plot ... origin-y, in plot paper units and by scale (e.g. x50 for 1:50) 12 <<< insertion base point for this layout (defined by INSBASE while ... this layout is current) 0.0 <<< x value 22 <<< group code for y value 0.0 <<< y value 32 <<< group code for z value 0.0 <<< z value 14 <<< minimum extents for this layout (defined by EXTMIN while this ... layout is current), AutoCAD default is (1e20, 1e20, 1e20) 1.05 <<< x value 24 <<< group code for y value 0.80 <<< y value 34 <<< group code for z value 0.0 <<< z value 15 <<< maximum extents for this layout (defined by EXTMAX while this ... layout is current), AutoCAD default is (-1e20, -1e20, -1e20) 9.45 <<< x value 25 <<< group code for y value 7.20 <<< y value 35 <<< group code for z value 0.0 <<< z value 146 <<< elevation ??? 0.0 13 <<< UCS origin (3D Point) 0.0 <<< x value 23 <<< group code for y value 0.0 <<< y value 33 <<< group code for z value 0.0 <<< z value 16 <<< UCS X-axis (3D vector) 1.0 <<< x value 26 <<< group code for y value 0.0 <<< y value 36 <<< group code for z value 0.0 <<< z value 17 <<< UCS Y-axis (3D vector) 0.0 <<< x value 27 <<< group code for y value 1.0 <<< y value 37 <<< group code for z value 0.0 <<< z value 76 <<< orthographic type of UCS 0-6 (... too many options) 0 <<< 0 = UCS is not orthographic ??? 330 <<< ID/handle of required block table record 58 331 <<< ID/handle to the viewport that was last active in this layout ... when the layout was current 1B9 1001 <<< extended data (ignore) ... ``` And as it seems this is also not enough for a well defined LAYOUT, at least a “main” VIEWPORT entity with ID=1 is required for paperspace layouts, located in the entity space of the layout. The modelspace layout requires (?) a VPORT entity in the VPORT table (group code 331 in the AcDbLayout subclass). ### Main VIEWPORT Entity for LAYOUT The “main” viewport for layout “Layout1” shown above. This viewport is located in the associated BLOCK definition called “\*Paper\_Space0”. Group code 330 in subclass AcDbLayout points to the BLOCK\_RECORD of “\*Paper\_Space0”. Remember: the entities of the *active* paperspace layout are located in the ENTITIES section, therefore “Layout1” is not the active paperspace layout. The “main” VIEWPORT describes, how the application shows the paperspace layout on the screen, and I guess only AutoCAD needs this values. \[image\] ``` 0 VIEWPORT 5 <<< handle 1B4 102 <<< extension dictionary (ignore) {ACAD_XDICTIONARY 360 1B5 102 } 330 <<< owner handle 58 <<< points to BLOCK_RECORD (same as group code 330 in AcDbLayout of ... "Layout1") 100 AcDbEntity 67 <<< paperspace flag 1 <<< 0 = modelspace; 1 = paperspace 8 <<< layer, 0 100 AcDbViewport 10 <<< Center point (in WCS) 5.25 <<< x value 20 <<< group code for y value 4.00 <<< y value 30 <<< group code for z value 0.0 <<< z value 40 <<< width in paperspace units 23.55 <<< VIEW size in AutoCAD, depends on the workstation configuration 41 <<< height in paperspace units 9.00 <<< VIEW size in AutoCAD, depends on the workstation configuration 68 <<< viewport status field -1/0/n 2 <<< >0 On and active. The value indicates the order of stacking for ... the viewports, where 1 is the active viewport, 2 is the next, and so forth 69 <<< viewport ID 1 <<< "main" viewport has always ID=1 12 <<< view center point in Drawing Coordinate System (DCS), defines ... the center point of the VIEW in relation to the LAYOUT origin 5.25 <<< x value 22 <<< group code for y value 4.00 <<< y value 13 <<< snap base point in modelspace 0.0 <<< x value 23 <<< group code for y value 0.0 <<< y value 14 <<< snap spacing in modelspace units 0.5 <<< x value 24 <<< group code for y value 0.5 <<< y value 15 <<< grid spacing in modelspace units 0.5 <<< x value 25 <<< group code for y value 0.5 <<< y value 16 <<< view direction vector from target (in WCS) 0.0 <<< x value 26 <<< group code for y value 0.0 <<< y value 36 <<< group code for z value 1.0 <<< z value 17 <<< view target point 0.0 <<< x value 27 <<< group code for y value 0.0 <<< y value 37 <<< group code for z value 0.0 <<< z value 42 <<< perspective lens length, focal length? 50.0 <<< 50mm 43 <<< front clip plane z value 0.0 <<< z value 44 <<< back clip plane z value 0.0 <<< z value 45 <<< view height (in modelspace units) 9.00 50 <<< snap angle 0.0 51 <<< view twist angle 0.0 72 <<< circle zoom percent 1000 90 <<< Viewport status bit-coded flags (... too many options) 819232 <<< b11001000000000100000 1 <<< plot style sheet name assigned to this viewport 281 <<< render mode (... too many options) 0 <<< 0 = 2D optimized (classic 2D) 71 <<< UCS per viewport flag 1 <<< 1 = This viewport stores its own UCS which will become the ... current UCS whenever the viewport is activated 74 <<< Display UCS icon at UCS origin flag 0 <<< this field is currently being ignored and the icon always ... represents the viewport UCS 110 <<< UCS origin (3D point) 0.0 <<< x value 120 <<< group code for y value 0.0 <<< y value 130 <<< group code for z value 0.0 <<< z value 111 <<< UCS X-axis (3D vector) 1.0 <<< x value 121 <<< group code for y value 0.0 <<< y value 131 <<< group code for z value 0.0 <<< z value 112 <<< UCS Y-axis (3D vector) 0.0 <<< x value 122 <<< group code for y value 1.0 <<< y value 132 <<< group code for z value 0.0 <<< z value 79 <<< Orthographic type of UCS (... too many options) 0 <<< 0 = UCS is not orthographic 146 <<< elevation 0.0 170 <<< shade plot mode (0/1/2/3 for as displayed/wireframe/hidden/rendered) 0 <<< as displayed 61 <<< frequency of major grid lines compared to minor grid lines 5 <<< major grid subdivided by 5 348 <<< visual style ID/handle (optional) 9F 292 <<< default lighting flag, on when no user lights are specified. 1 282 <<< Default lighting type (0/1 = one distant light/two distant lights) 1 <<< one distant light 141 <<< view brightness 0.0 142 <<< view contrast 0.0 63 <<< ambient light color (ACI), write only if not black color 250 421 <<< ambient light color (RGB), write only if not black color 3355443 ``` ### Miscellaneous ### Notes on Rendering DXF Content A collection of AutoCAD behaviors determined experimentally. There may be mistakes and misunderstandings of the inner workings of the algorithms. Not all edge cases may have been considered. ### Colors - • Most entities are colored contextually, based on the layer or block that they reside in. - • Usually entity colors are stored as AutoCAD Color Indices (ACI) as an index into a lookup table. Different CAD applications may use different color palettes making consistent coloring difficult. - • If a block insert is placed on layer ‘A’, and the block contains an entity on layer ‘B’ with BYLAYER color: the entity will be drawn with the color of layer ‘B’. - • If a block insert is placed on layer ‘A’, and the block contains an entity on layer ‘0’ with BYLAYER color: the entity will be drawn with the color of layer ‘A’, it seems that layer ‘0’ is the only special case for this. - • Ff an entity has BYBLOCK color set, and it exists outside a block: it will take on the layout default color which is white in the modelspace and black in the paperspace. ### Layers and Draw Order - • Layer names are case-insensitive, the document layer table keys are stored in lowercase, and in original style in all other use cases (e.g. *entity.dxf.layer*). - • Layers do not play a role in entity draw order, only whether they appear at all based on the visibility of the layer. - • It appears that Insert entities have a single element in terms of draw order - • Entities inside a block can overlap each other and so have a draw order inside the block, but two Insert entities cannot interleave the contents of their blocks. One is completely drawn on top of the other. - • For entities inside a block, the visibility of the layer that the block is inserted does not affect the visibility of the entity *unless* the entity was created on layer 0 in which case the reverse is true: - • scenario: block created containing entity A (layer 0) and entity B (layer 1). The block is inserted into layer 2 - • entity B visible if and only if layer 1 is visible - • entity A visible if and only if layer 2 is visible ### TEXT - • The anchor of single line TEXT entities (and ATTRIB entities) is *always* the left-baseline regardless of what alignment parameters are stored in the DXF. Those are for re-adjusting the anchor when the text is edited. - • Attrib entities can have formatting commands in them ### MTEXT - • The *char\_height* in DXF corresponds to the cap-height of the font. - • The default line spacing is 5/3 \* cap-height between the previous baseline and the next baseline. The *line\_space\_factor* is a factor applied directly to this value, so a factor of 3/5 results in 0 space between lines, because each baseline is 1 \* cap-height apart. - • The middle (vertical) justification of MTEXT entities seems to be midpoint between the x-height of the first line to the baseline of the last line. - • MTEXT word wrapping seems to only break on spaces, not underscores or dashes. - • MTEXT word wrapping seems to treat multiple spaces between lines as if they were a single space. - • Alignment seems to ignore extra spaces at the start or end of lines except for the first line, where spaces at the beginning of the string have an effect. Whitespace at the beginning of the text can trigger word wrapping, which creates a single blank line at the start - • If a line ends with an explicit newline character and is shorter than the column width, only one newline is inserted. - • If a line is a single word wider than the column width, it will not be broken but will instead spill outside the text box. Placing a space before this word will create an empty line and push the word onto the next line. ### POINT - • All POINT entities have the same style defined by the HEADER variable $PDMODE. - • POINT entities can be drawn relative to the view scale or in absolute units. ### Low Level Functions Some handy tool functions used internally by **ezdxf**. - **ezdxf.tools.juliandate(date: datetime) -\> float** - **ezdxf.tools.calendardate(juliandate: float) -\> datetime** - **ezdxf.tools.set\_flag\_state(flags: int, flag: int, state: bool = True) -\> int** Set/clear binary *flag* in data *flags*. - **Parameters** - • **flags** – data value - • **flag** – flag to set/clear - • **state** – **True** for setting, **False** for clearing - **ezdxf.tools.guid() -\> str** Returns a general unique ID, based on **uuid.uuid4()**. This function creates a GUID for the header variables $VERSIONGUID and $FINGERPRINTGUID, which matches the AutoCAD pattern **{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}**. - **ezdxf.tools.bytes\_to\_hexstr(data: bytes) -\> str** Returns *data* bytes as plain hex string. - **ezdxf.tools.suppress\_zeros(s: str, leading: bool = False, trailing: bool = True)** Suppress trailing and/or leading **0** of string *s*. - **Parameters** - • **s** – data string - • **leading** – suppress leading **0** - • **trailing** – suppress trailing **0** - **ezdxf.tools.normalize\_text\_angle(angle: float, fix\_upside\_down=True) -\> float** Normalizes text *angle* to the range from 0 to 360 degrees and fixes upside down text angles. - **Parameters** - • **angle** – text angle in degrees - • **fix\_upside\_down** – rotate upside down text angle about 180 degree ### DXF Unicode Decoder The DXF format uses a special form of unicode encoding: “\\U+xxxx”. To avoid a speed penalty such encoded characters are not decoded automatically by the regular loading function:func:*ezdxf.readfile*, only the *recover* module does the decoding automatically, because this loading mode is already slow. This kind of encoding is most likely used only in older DXF versions, because since DXF R2007 the whole DXF file is encoded in **utf8** and a special unicode encoding is not necessary. The *ezdxf.has\_dxf\_unicode()* and *ezdxf.decode\_dxf\_unicode()* are new support functions to decode unicode characters “\\U+xxxx” manually. - **ezdxf.has\_dxf\_unicode(s: str) -\> bool** Returns **True** if string *s* contains **\\U+xxxx** encoded characters. - **ezdxf.decode\_dxf\_unicode(s: str) -\> str** Decode **\\U+xxxx** encoded characters. ### SAT Format “Encryption” - **ezdxf.tools.crypt.encode(text\_lines: Iterable\[str\]) -\> Iterable\[str\]** Encode the Standard *ACIS* Text (SAT) format by AutoCAD “encryption” algorithm. - **ezdxf.tools.crypt.decode(text\_lines: Iterable\[str\]) -\> Iterable\[str\]** Decode the Standard *ACIS* Text (SAT) format “encrypted” by AutoCAD. ### Developer Guides Information about *ezdxf* internals. ### Source Code Formatting Reformat code by *Black* with the default setting of 88 characters per line: ``` C:\> black ``` ### Type Annotations The use of type annotations is encouraged. New modules should pass *mypy* without errors in non-strict mode. Using **# type: ignore** is fine in tricky situations - type annotations should be helpful in understanding the code and not be a burden. The following global options are required to pass *mypy* without error messages: ``` [mypy] python_version = 3.7 ignore_missing_imports = True ``` Read *this* to learn where *mypy* searches for config files. Use the *mypy* command line option **--ignore-missing-imports** and **-p** to check the whole package from any location in the file system: ``` PS D:\Source\ezdxf.git> mypy --ignore-missing-imports -p ezdxf Success: no issues found in 255 source files ``` ### Design The *Package Design for Developers* section shows the structure of the *ezdxf* package for developers with more experience, which want to have more insight into the package an maybe want to develop add-ons or want contribute to the *ezdxf* package. **!!! UNDER CONSTRUCTION !!!** ### Package Design for Developers A DXF document is divided into several sections, this sections are managed by the **Drawing** object. For each section exist a corresponding attribute in the **Drawing** object: | | | | --- | --- | | Section | Attribute | | HEADER | **Drawing.header** | | CLASSES | **Drawing.classes** | | TABLES | **Drawing.tables** | | BLOCKS | **Drawing.blocks** | | ENTITIES | **Drawing.entities** | | OBJECTS | **Drawing.objects** | Resource entities (LAYER, STYLE, LTYPE, …) are stored in tables in the TABLES section. A table owns the table entries, the owner handle of table entry is the handle of the table. Each table has a shortcut in the **Drawing** object: | | | | --- | --- | | Table | Attribute | | APPID | **Drawing.appids** | | BLOCK\_RECORD | **Drawing.block\_records** | | DIMSTYLE | **Drawing.dimstyles** | | LAYER | **Drawing.layers** | | LTYPE | **Drawing.linetypes** | | STYLE | **Drawing.styles** | | UCS | **Drawing.ucs** | | VIEW | **Drawing.views** | | VPORT | **Drawing.viewports** | Graphical entities are stored in layouts: *Modelspace*, *Paperspace* layouts and *BlockLayout*. The core management object of this layouts is the BLOCK\_RECORD entity (*BlockRecord*), the BLOCK\_RECORD is the real owner of the entities, the owner handle of the entities is the handle of the BLOCK\_RECORD and the BLOCK\_RECORD also owns and manages the entity space of the layout which contains all entities of the layout. For more information about layouts see also: *Layout Management Structures* For more information about blocks see also: *Block Management Structures* Non-graphical entities (objects) are stored in the OBJECTS section. Every object has a parent object in the OBJECTS section, most likely a DICTIONARY object, and is stored in the entity space of the OBJECTS section. For more information about the OBJECTS section see also: *OBJECTS Section* All table entries, DXF entities and DXF objects are stored in the entities database accessible as **Drawing.entitydb**. The entity database is a simple key, value storage, key is the entity handle, value is the DXF object. For more information about the DXF data model see also: *Data Model* ### Terminology ### States DXF entities and objects can have different states: - **UNBOUND** Entity is not stored in the **Drawing** entity database and DXF attribute **handle** is **None** and attribute **doc** can be **None** - **BOUND** Entity is stored in the **Drawing** entity database, attribute **doc** has a reference to **Drawing** and DXF attribute **handle** is not **None** - **UNLINKED** Entity is not linked to a layout/owner, DXF attribute **owner** is **None** - **LINKED** Entity is linked to a layout/owner, DXF attribute **owner** is not **None** - **Virtual Entity** State: UNBOUND & UNLINKED - **Unlinked Entity** State: BOUND & UNLINKED - **Bound Entity** State: BOUND & LINKED ### Actions - **NEW** Create a new DXF document - **LOAD** Load a DXF document from an external source - **CREATE** Create DXF structures from NEW or LOAD data - **DESTROY** Delete DXF structures - **BIND** Bind an entity to a **Drawing**, set entity state to BOUND & UNLINKED and check or create required resources - **UNBIND** unbind … - **LINK** Link an entity to an owner/layout. This makes an entity to a real DXF entity, which will be exported at the saving process. Any DXF entity can only be linked to **one** parent entity like DICTIONARY or BLOCK\_RECORD. - **UNLINK** unlink … ### Loading a DXF Document Loading a DXF document from an external source, creates a new **Drawing** object. This loading process has two stages: ### First Loading Stage - • LOAD content from external source as **SectionDict**: **loader.load\_dxf\_structure()** - • LOAD tag structures as **DXFEntity** objects: **loader.load\_dxf\_entities()** - • BIND entities: **loader.load\_and\_bind\_dxf\_content()**; Special handling of the BIND process, because the **Drawing** is not full initialized, a complete validation is not possible at this stage. ### Second Loading Stage Parse **SectionDict**: - • CREATE sections: HEADER, CLASSES, TABLES, BLOCKS and OBJECTS - • CREATE layouts: Blocks, Layouts - • LINK entities to a owner/layout The ENTITIES section is a relict from older DXF versions and has to be exported including the modelspace and active paperspace entities, but all entities reside in a BLOCK definition, even modelspace and paperspace layouts are only BLOCK definitions and ezdxf has no explicit ENTITIES section. Source Code: as developer start your journey at **ezdxf.document.Drawing.read()**, which has no public documentation, because package-user should use *ezdxf.read()* and *ezdxf.readfile()*. ### New DXF Document ### Creating New DXF Entities The default constructor of each entity type creates a new virtual entity: - • DXF attribute *owner* is **None** - • DXF attribute *handle* is **None** - • Attribute *doc* is **None** The **DXFEntity.new()** constructor creates entities with given *owner*, *handle* and *doc* attributes, if *doc* is not **None** and entity is not already bound to a document, the **new()** constructor automatically bind the entity to the given document *doc*. There exist only two scenarios: - 1\. UNBOUND: *doc* is **None** and *handle* is **None** - 2\. BOUND: *doc* is not **None** and *handle* is not **None** ### Factory functions - • **new()**, create a new virtual DXF object/entity - • **load()**, load (create) virtual DXF object/entity from DXF tags - • **bind()**, bind an entity to a document, create required resources if necessary (e.g. ImageDefReactor, SEQEND) and raise exceptions for non-existing resources. - • Bind entity loaded from an external source to a document, all referenced resources must exist, but try to repair as many flaws as possible because errors were created by another application and are not the responsibility of the package-user. - • Bind an entity from another DXF document, all invalid resources will be removed silently or created (e.g. SEQEND). This is a simple import from another document without resource import, for a more advanced import including resources exist the **importer** add-on. - • Bootstrap problem for binding loaded table entries and objects in the OBJECTS section! Can’t use **Auditor** to repair this objects, because the DXF document is not fully initialized. - • **is\_bound()** returns True if *entity* is bound to document *doc* - • **unbind()** function to remove an entity from a document and set state to a virtual entity, which should also *UNLINK* the entity from layout, because an layout can not store a virtual entity. - • **cls()**, returns the class - • **register\_entity()**, registration decorator - • **replace\_entity()**, registration decorator ### Class Interfaces ### DXF Entities - • NEW constructor to create an entity from scratch - • LOAD constructor to create an entity loaded from an external source - • DESTROY interface to kill an entity, set entity state to *dead*, which means **entity.is\_alive** returns False. All entity iterators like **EntitySpace**, **EntityQuery**, and **EntityDB** must filter (ignore) *dead* entities. Calling **DXFEntity.destroy()** is a regular way to delete entities. - • LINK an entity to a layout by **BlockRecord.link()**, which set the *owner* handle to BLOCK\_RECORD handle (= layout key) and add the entity to the entity space of the BLOCK\_RECORD and set/clear the paperspace flag. ### DXF Objects - • NEW, LOAD, DESTROY see DXF entities - • LINK: Linking an DXF object means adding the entity to a parent object in the OBJECTS section, most likely a DICTIONARY object, and adding the object to the entity space of the OBJECTS section, the root-dict is the only entity in the OBJECTS section which has an invalid owner handle “0”. Any other object with an invalid or destroyed owner is an orphaned entity. The audit process destroys and removes orphaned objects. - • Extension dictionaries (ACAD\_XDICTIONARY) are DICTIONARY objects located in the OBJECTS sections and can reference/own other entities of the OBJECTS section. - • The root-dictionary is the only entity in the OBJECTS section which has an invalid owner handle “0”. Any other object with an invalid or destroyed owner is an orphaned entity. ### Layouts - • LINK interface to link an entity to a layout - • UNLINK interface to remove an entity from a layout ### Database - • BIND interface to add an entity to the database of a document - • **delete\_entity()** interface, same as UNBIND and DESTROY an entity ### Internal Data Structures ### Entity Database The *EntityDB* is a simple key/value database to store *DXFEntity* objects by it’s handle, every *Drawing* has its own *EntityDB*, stored in the **Drawing** attribute **entitydb**. Every DXF entity/object, except tables and sections, are represented as **DXFEntity** or inherited types, this entities are stored in the *EntityDB*, database-key is the **dxf.handle** as plain hex string. All iterators like **keys()**, **values()**, **items()** and **\_\_iter\_\_()** do not yield destroyed entities. **WARNING:** The **get()** method and the index operator **\[\]**, return destroyed entities and entities from the trashcan. - **class ezdxf.entitydb.EntityDB** - **\_\_getitem\_\_(handle: str) -\> *DXFEntity*** Get entity by *handle*, does not filter destroyed entities nor entities in the trashcan. - **\_\_setitem\_\_(handle: str, entity: *DXFEntity*) -\> None** Set *entity* for *handle*. - **\_\_delitem\_\_(handle: str) -\> None** Delete entity by *handle*. Removes entity only from database, does not destroy the entity. - **\_\_contains\_\_(item: str \| *DXFEntity*) -\> bool** **True** if database contains *handle*. - **\_\_len\_\_() -\> int** Count of database items. - **\_\_iter\_\_() -\> Iterator\[str\]** Iterable of all handles, does filter destroyed entities but not entities in the trashcan. - **get(handle: str) -\> *DXFEntity* \| None** Returns entity for *handle* or **None** if no entry exist, does not filter destroyed entities. - **next\_handle() -\> str** Returns next unique handle. - **keys() -\> Iterable\[str\]** Iterable of all handles, does filter destroyed entities. - **values() -\> Iterable\[*DXFEntity*\]** Iterable of all entities, does filter destroyed entities. - **items() -\> Iterable\[Tuple\[str, *DXFEntity*\]\]** Iterable of all (handle, entities) pairs, does filter destroyed entities. - **add(entity: *DXFEntity*) -\> None** Add *entity* to database, assigns a new handle to the *entity* if **entity.dxf.handle** is **None**. Adding the same entity multiple times is possible and creates only a single database entry. - **new\_trashcan() -\> Trashcan** Returns a new trashcan, empty trashcan manually by: : func:*Trashcan.clear()*. - **trashcan() -\> Trashcan** Returns a new trashcan in context manager mode, trashcan will be emptied when leaving context. - **purge() -\> None** Remove all destroyed entities from database, but does not empty the trashcan. - **query(query: str = '\*') -\> *EntityQuery*** Entity query over all entities in the DXF document. - **Parameters** **query** – query string **SEE ALSO:** *Entity Query String* and *Retrieve entities by query language* ### Entity Space - **class ezdxf.entitydb.EntitySpace(entities: Iterable\[DXFEntity\] \| None = None)** An *EntitySpace* is a collection of *DXFEntity* objects, that stores only references to **DXFEntity** objects. The *Modelspace*, any *Paperspace* layout and *BlockLayout* objects have an *EntitySpace* container to store their entities. - **\_\_iter\_\_() -\> Iterable\[*DXFEntity*\]** Iterable of all entities, filters destroyed entities. - **\_\_getitem\_\_(index) -\> *DXFEntity*** Get entity at index *item* *EntitySpace* has a standard Python list like interface, therefore *index* can be any valid list indexing or slicing term, like a single index **layout\[-1\]** to get the last entity, or an index slice **layout\[:10\]** to get the first 10 or fewer entities as **list\[DXFEntity\]**. Does not filter destroyed entities. - **\_\_len\_\_() -\> int** Count of entities including destroyed entities. - **has\_handle(handle: str) -\> bool** **True** if *handle* is present, does filter destroyed entities. - **purge()** Remove all destroyed entities from entity space. - **add(entity: *DXFEntity*) -\> None** Add *entity*. - **extend(entities: Iterable\[*DXFEntity*\]) -\> None** Add multiple *entities*. - **remove(entity: *DXFEntity*) -\> None** Remove *entity*. - **clear() -\> None** Remove all entities. ### DXF Types Required DXF tag interface: - • property **code**: group code as int - • property **value**: tag value of unspecific type - • **dxfstr()**: returns the DXF string - • **clone()**: returns a deep copy of tag ### DXFTag Factory Functions - **ezdxf.lldxf.types.dxftag(code: int, value: Any) -\> *DXFTag*** DXF tag factory function. - **Parameters** - • **code** – group code - • **value** – tag value Returns: *DXFTag* or inherited - **ezdxf.lldxf.types.tuples\_to\_tags(iterable: Iterable\[tuple\[int, Any\]\]) -\> Iterable\[*DXFTag*\]** Returns an iterable if *DXFTag* or inherited, accepts an iterable of (code, value) tuples as input. ### DXFTag - **class ezdxf.lldxf.types.DXFTag(code: int, value: Any)** Immutable DXFTag class. - **Parameters** - • **code** – group code as int - • **value** – tag value, type depends on group code - **code** group code as int (do not change) - **value** tag value (read-only property) - **\_\_eq\_\_(other) -\> bool** **True** if *other* and *self* has same content for *code* and *value*. - **\_\_getitem\_\_(index: int)** Returns *code* for index 0 and *value* for index 1, emulates a tuple. - **\_\_hash\_\_()** Hash support, *DXFTag* can be used in sets and as dict key. - **\_\_iter\_\_()** Returns (code, value) tuples. - **\_\_repr\_\_() -\> str** Returns representation string **'DXFTag(code, value)'**. - **\_\_str\_\_() -\> str** Returns content string **'(code, value)'**. - **clone() -\> *DXFTag*** Returns a clone of itself, this method is necessary for the more complex (and not immutable) DXF tag types. - **dxfstr() -\> str** Returns the DXF string e.g. **' 0\\nLINE\\n'** ### DXFBinaryTag - **class ezdxf.lldxf.types.DXFBinaryTag(DXFTag)** Immutable BinaryTags class - immutable by design, not by implementation. - **dxfstr() -\> str** Returns the DXF string for all vertex components. - **tostring() -\> str** Returns binary value as single hex-string. ### DXFVertex - **class ezdxf.lldxf.types.DXFVertex(DXFTag)** Represents a 2D or 3D vertex, stores only the group code of the x-component of the vertex, because the y-group-code is x-group-code + 10 and z-group-code id x-group-code+20, this is a rule that ALWAYS applies. This tag is *immutable* by design, not by implementation. - **Parameters** - • **code** – group code of x-component - • **value** – sequence of x, y and optional z values - **dxfstr() -\> str** Returns the DXF string for all vertex components. - **dxftags() -\> Iterable\[*DXFTag*\]** Returns all vertex components as single *DXFTag* objects. ### NONE\_TAG - **ezdxf.lldxf.types.NONE\_TAG** Special tag representing a none existing tag. ### Tags A list of *DXFTag*, inherits from Python standard list. Unlike the statement in the DXF Reference “Do not write programs that rely on the order given here”, tag order is sometimes essential and some group codes may appear multiples times in one entity. At the worst case (**Material**: normal map shares group codes with diffuse map) using same group codes with different meanings. - **class ezdxf.lldxf.tags.Tags** Subclass of **list**. Collection of *DXFTag* as flat list. Low level tag container, only required for advanced stuff. - **classmethod from\_text(text: str) -\> *Tags*** Constructor from DXF string. - **dxftype() -\> str** Returns DXF type of entity, e.g. **'LINE'**. - **get\_handle() -\> str** Get DXF handle. Raises **DXFValueError** if handle not exist. - **Returns** handle as plain hex string like **'FF00'** - **Raises** *DXFValueError* – no handle found - **replace\_handle(new\_handle: str) -\> None** Replace existing handle. - **Parameters** **new\_handle** – new handle as plain hex string e.g. **'FF00'** - **has\_tag(code: int) -\> bool** Returns **True** if a *DXFTag* with given group *code* is present. - **Parameters** **code** – group code as int - **has\_embedded\_objects() -\> bool** - **get\_first\_tag(code: int, default=DXFValueError) -\> *DXFTag*** Returns first *DXFTag* with given group code or *default*, if *default* != **DXFValueError**, else raises **DXFValueError**. - **Parameters** - • **code** – group code as int - • **default** – return value for default case or raises **DXFValueError** - **get\_first\_value(code: int, default=DXFValueError) -\> Any** Returns value of first *DXFTag* with given group code or default if *default* != **DXFValueError**, else raises **DXFValueError**. - **Parameters** - • **code** – group code as int - • **default** – return value for default case or raises **DXFValueError** - **find\_all(code: int) -\> List\[*DXFTag*\]** Returns a list of *DXFTag* with given group code. - **Parameters** **code** – group code as int - **filter(codes: Iterable\[int\]) -\> Iterable\[*DXFTag*\]** Iterate and filter tags by group *codes*. - **Parameters** **codes** – group codes to filter - **collect\_consecutive\_tags(codes: Iterable\[int\], start: int = 0, end: int = None) -\> *Tags*** Collect all consecutive tags with group code in *codes*, *start* and *end* delimits the search range. A tag code not in codes ends the process. - **Parameters** - • **codes** – iterable of group codes - • **start** – start index as int - • **end** – end index as int, **None** for end index = **len(self)** - **Returns** collected tags as *Tags* - **tag\_index(code: int, start: int = 0, end: int \| None = None) -\> int** Return index of first *DXFTag* with given group code. - **Parameters** - • **code** – group code as int - • **start** – start index as int - • **end** – end index as int, **None** for end index = **len(self)** - **update(tag: *DXFTag*)** Update first existing tag with same group code as *tag*, raises **DXFValueError** if tag not exist. - **set\_first(tag: *DXFTag*)** Update first existing tag with group code **tag.code** or append tag. - **remove\_tags(codes: Iterable\[int\]) -\> None** Remove all tags inplace with group codes specified in *codes*. - **Parameters** **codes** – iterable of group codes as int - **remove\_tags\_except(codes: Iterable\[int\]) -\> None** Remove all tags inplace except those with group codes specified in *codes*. - **Parameters** **codes** – iterable of group codes - **pop\_tags(codes: Iterable\[int\]) -\> Iterable\[*DXFTag*\]** Pop tags with group codes specified in *codes*. - **Parameters** **codes** – iterable of group codes - **classmethod strip(tags: *Tags*, codes: Iterable\[int\]) -\> *Tags*** Constructor from *tags*, strips all tags with group codes in *codes* from tags. - **Parameters** - • **tags** – iterable of *DXFTag* - • **codes** – iterable of group codes as int - **ezdxf.lldxf.tags.group\_tags(tags: Iterable\[*DXFTag*\], splitcode: int = 0) -\> Iterable\[*Tags*\]** Group of tags starts with a SplitTag and ends before the next SplitTag. A SplitTag is a tag with code == splitcode, like (0, ‘SECTION’) for splitcode == 0. - **Parameters** - • **tags** – iterable of **DXFTag** - • **splitcode** – group code of split tag - **class ezdxf.lldxf.extendedtags.ExtendedTags(tags: Iterable\[*DXFTag*\] = None, legacy=False)** Represents the extended DXF tag structure introduced with DXF R13. - **Args:** tags: iterable of *DXFTag* legacy: flag for DXF R12 tags - **appdata** Application defined data as list of **Tags** - **subclasses** Subclasses as list of **Tags** - **xdata** XDATA as list of **Tags** - **embedded\_objects** embedded objects as list of **Tags** - **noclass** Short cut to access first subclass. - **get\_handle() -\> str** Returns handle as hex string. - **dxftype() -\> str** Returns DXF type as string like “LINE”. - **replace\_handle(handle: str) -\> None** Replace the existing entity handle by a new value. - **legacy\_repair()** Legacy (DXF R12) tags handling and repair. - **clone() -\> *ExtendedTags*** Shallow copy. - **flatten\_subclasses()** Flatten subclasses in legacy mode (DXF R12). There exists DXF R12 with subclass markers, technical incorrect but works if the reader ignore subclass marker tags, unfortunately ezdxf tries to use this subclass markers and therefore R12 parsing by ezdxf does not work without removing these subclass markers. This method removes all subclass markers and flattens all subclasses into ExtendedTags.noclass. - **get\_subclass(name: str, pos: int = 0) -\> *Tags*** Get subclass *name*. - **Parameters** - • **name** – subclass name as string like “AcDbEntity” - • **pos** – start searching at subclass *pos*. - **has\_xdata(appid: str) -\> bool** **True** if has XDATA for *appid*. - **get\_xdata(appid: str) -\> *Tags*** Returns XDATA for *appid* as **Tags**. - **set\_xdata(appid: str, tags: IterableTags) -\> None** Set *tags* as XDATA for *appid*. - **new\_xdata(appid: str, tags: 'IterableTags' = None) -\> *Tags*** Append a new XDATA block. Assumes that no XDATA block with the same *appid* already exist: ``` try: xdata = tags.get_xdata('EZDXF') except ValueError: xdata = tags.new_xdata('EZDXF') ``` - **has\_app\_data(appid: str) -\> bool** **True** if has application defined data for *appid*. - **get\_app\_data(appid: str) -\> *Tags*** Returns application defined data for *appid* as **Tags** including marker tags. - **get\_app\_data\_content(appid: str) -\> *Tags*** Returns application defined data for *appid* as **Tags** without first and last marker tag. - **set\_app\_data\_content(appid: str, tags: IterableTags) -\> None** Set application defined data for *appid* for already exiting data. - **new\_app\_data(appid: str, tags: 'IterableTags' = None, subclass\_name: str = None) -\> *Tags*** Append a new application defined data to subclass *subclass\_name*. Assumes that no app data block with the same *appid* already exist: ``` try: app_data = tags.get_app_data('{ACAD_REACTORS', tags) except ValueError: app_data = tags.new_app_data('{ACAD_REACTORS', tags) ``` - **classmethod from\_text(text: str, legacy: bool = False) -\> *ExtendedTags*** Create *ExtendedTags* from DXF text. ### Packed DXF Tags Store DXF tags in compact data structures as **list** or **array.array** to reduce memory usage. - **class ezdxf.lldxf.packedtags.TagList(data: Iterable = None)** Store data in a standard Python **list**. - **Args:** data: iterable of DXF tag values. - **values** Data storage as **list**. - **clone() -\> *TagList*** Returns a deep copy. - **classmethod from\_tags(tags: *Tags*, code: int) -\> *TagList*** Setup list from iterable tags. - **Parameters** - • **tags** – tag collection as *Tags* - • **code** – group code to collect - **clear() -\> None** Delete all data values. - **class ezdxf.lldxf.packedtags.TagArray(data: Iterable = None)** *TagArray* is a subclass of *TagList*, which store data in an **array.array**. Array type is defined by class variable **DTYPE**. - **Args:** data: iterable of DXF tag values. - **DTYPE** **array.array** type as string - **values** Data storage as **array.array** - **set\_values(values: Iterable) -\> None** Replace data by *values*. - **class ezdxf.lldxf.packedtags.VertexArray(data: Iterable = None)** Store vertices in an **array.array('d')**. Vertex size is defined by class variable *VERTEX\_SIZE*. - **Args:** data: iterable of vertex values as linear list e.g. **\[x1, y1, x2, y2, x3, y3, ...\]**. - **VERTEX\_SIZE** Size of vertex (2 or 3 axis). - **\_\_len\_\_() -\> int** Count of vertices. - **\_\_getitem\_\_(index: int \| slice)** Get vertex at *index*, extended slicing supported. - **\_\_setitem\_\_(index: int, point: Sequence\[float\]) -\> None** Set vertex *point* at *index*, extended slicing not supported. - **\_\_delitem\_\_(index: int \| slice) -\> None** Delete vertex at *index*, extended slicing supported. - **\_\_iter\_\_() -\> Iterator\[Sequence\[float\]\]** Returns iterable of vertices. - **\_\_str\_\_() -\> str** String representation. - **insert(pos: int, point: Sequence\[float\])** Insert *point* in front of vertex at index *pos*. - **Parameters** - • **pos** – insert position - • **point** – point as tuple - **append(point: Sequence\[float\]) -\> None** Append *point*. - **extend(points: Iterable\[Sequence\[float\]\]) -\> None** Extend array by *points*. - **set(points: Iterable\[Sequence\[float\]\]) -\> None** Replace all vertices by *points*. - **clear() -\> None** Delete all vertices. - **clone() -\> *VertexArray*** Returns a deep copy. - **classmethod from\_tags(tags: Iterable\[*DXFTag*\], code: int = 10) -\> *VertexArray*** Setup point array from iterable tags. - **Parameters** - • **tags** – iterable of *DXFVertex* - • **code** – group code to collect - **export\_dxf(tagwriter: AbstractTagWriter, code=10)** ### XData - **class ezdxf.entities.xdata.XData** Internal management class for XDATA. **SEE ALSO:** - • XDATA user reference: *Extended Data (XDATA)* - • Wrapper class to store a list in XDATA: *XDataUserList* - • Wrapper class to store a dict in XDATA: *XDataUserDict* - • Tutorial: *Storing Custom Data in DXF Files* - • DXF Internals: *Extended Data* - • *DXF R2018 Reference* - **\_\_contains\_\_(appid: str) -\> bool** Returns **True** if DXF tags for *appid* exist. - **add(appid: str, tags: Iterable\[tuple\[int, Any\] \| *DXFTag*\]) -\> None** Add a list of DXF tags for *appid*. The *tags* argument is an iterable of (group code, value) tuples, where the group code has to be an integer value. The mandatory XDATA marker (1001, appid) is added automatically if front of the tags if missing. Each entity can contain only one list of tags for each *appid*. Adding a second list of tags for the same *appid* replaces the existing list of tags. The valid XDATA group codes are restricted to some specific values in the range from 1000 to 1071, for more information see also the internals about *Extended Data*. - **get(appid: str) -\> *Tags*** Returns the DXF tags as *Tags* list stored by *appid*. - **Raises** *DXFValueError* – no data for *appid* exist - **discard(appid)** Delete DXF tags for *appid*. None existing appids are silently ignored. - **has\_xlist(appid: str, name: str) -\> bool** Returns **True** if list *name* from XDATA *appid* exists. - **Parameters** - • **appid** – APPID - • **name** – list name - **get\_xlist(appid: str, name: str) -\> list\[tuple\]** Get list *name* from XDATA *appid*. - **Parameters** - • **appid** – APPID - • **name** – list name Returns: list of DXFTags including list name and curly braces ‘{’ ‘}’ tags - **Raises** - • *DXFKeyError* – XDATA *appid* does not exist - • *DXFValueError* – list *name* does not exist - **set\_xlist(appid: str, name: str, tags: Iterable) -\> None** Create new list *name* of XDATA *appid* with *xdata\_tags* and replaces list *name* if already exists. - **Parameters** - • **appid** – APPID - • **name** – list name - • **tags** – list content as DXFTags or (code, value) tuples, list name and curly braces ‘{’ ‘}’ tags will be added - **discard\_xlist(appid: str, name: str) -\> None** Deletes list *name* from XDATA *appid*. Ignores silently if XDATA *appid* or list *name* not exist. - **Parameters** - • **appid** – APPID - • **name** – list name - **replace\_xlist(appid: str, name: str, tags: Iterable) -\> None** Replaces list *name* of existing XDATA *appid* by *tags*. Appends new list if list *name* do not exist, but raises *DXFValueError* if XDATA *appid* do not exist. Low level interface, if not sure use *set\_xdata\_list()* instead. - **Parameters** - • **appid** – APPID - • **name** – list name - • **tags** – list content as DXFTags or (code, value) tuples, list name and curly braces ‘{’ ‘}’ tags will be added - **Raises** *DXFValueError* – XDATA *appid* do not exist - **transform(m: *Matrix44*) -\> None** Transform XDATA tags with group codes 1011, 1012, 1013, 1041 and 1042 inplace. For more information see *Extended Data* Internals. ### Application-Defined Data (AppData) Starting at DXF R13, DXF objects can contain application-defined codes (AppData) outside of XDATA. All AppData is defined with a beginning (102, “{APPID”) tag and according to the DXF reference appear should appear before the first subclass marker. There are two known use cases of this data structure in Autodesk products: - • **ACAD\_REACTORS**, store handles to persistent reactors in a DXF entity - • **ACAD\_XDICTIONARY**, store handle to the extension dictionary of a DXF entity Both AppIDs are not defined/stored in the AppID table! - **class ezdxf.entities.appdata.AppData** Internal management class for Application defined data. **SEE ALSO:** - • User reference: *Application-Defined Data (AppData)* - • Internals about *Application-Defined Codes* tags - **\_\_contains\_\_(appid: str) -\> bool** Returns **True** if application-defined data exist for *appid*. - **\_\_len\_\_() -\> int** Returns the count of AppData. - **add(appid: str, data: Iterable\[Sequence\]) -\> None** Add application-defined tags for *appid*. Adds first tag (102, “{APPID”) if not exist. Adds last tag (102, “}” if not exist. - **get(appid: str) -\> *Tags*** Get application-defined data for *appid* as *Tags* container. The first tag is always (102, “{APPID”). The last tag is always (102, “}”). - **set(tags: *Tags*) -\> None** Store raw application-defined data tags. The first tag has to be (102, “{APPID”). The last tag has to be (102, “}”). - **discard(appid: str)** Delete application-defined data for *appid* without raising and error if *appid* doesn’t exist. ### Reactors - **class ezdxf.entities.appdata.Reactors** Internal management class for persistent reactor handles. Handles are stored as hex strings like **"ABBA"**. **SEE ALSO:** - • User reference: *Reactors* - • Internals about *Persistent Reactors* tags - **\_\_contains\_\_(handle: str) -\> bool** Returns **True** if *handle* is registered. - **\_\_len\_\_() -\> int** Returns count of registered handles. - **\_\_iter\_\_() -\> Iterator\[str\]** Returns an iterator for all registered handles. - **add(handle: str) -\> None** Add a single *handle*. - **get() -\> list\[str\]** Returns all registered handles as sorted list. - **set(handles: Iterable\[str\] \| None) -\> None** Reset all handles. - **discard(handle: str)** Discard a single *handle*. ### Documentation Guide ### Formatting Guide This section is only for *myself*, because of the long pauses between develop iterations, I often forget to be consistent in documentation formatting. Documentation is written with *Sphinx* and *reSturcturedText*. Started integration of documentation into source code and using *autodoc* features of *Sphinx* wherever useful. Sphinx theme provided by *Read the Docs* : ``` pip install sphinx-rtd-theme ``` ### *guide* — Example module - **guide.example\_func(a: int, b: str, test: str = None, flag: bool = True) -\> None** Parameters *a* and *b* are positional arguments, argument *test* defaults to **None** and *flag* to **True**. Set *a* to 70 and *b* to “x” as an example. Inline code examples **example\_func(70, 'x')** or simple **example\_func(70, "x")** - • arguments: *a*, *b*, *test* and *flags* - • literal number values: 1, 2 … 999 - • literal string values: “a String” - • literal tags: (5, “F000”) - • inline code: call a **example\_func(x)** - • Python keywords: **None**, **True**, **False**, **tuple**, **list**, **dict**, **str**, **int**, **float** - • Exception classes: **DXFAttributeError** - **class guide.ExampleCls(\*\*kwargs)** The *ExampleCls* constructor accepts a number of optional keyword arguments. Each keyword argument corresponds to an instance attribute, so for example ``` e = ExampleCls(flag=True) ``` - **flag** This is the attribute *flag*. - **set\_axis(axis)** axis as (x, y, z) tuple - **Args:** axis: (x, y, z) tuple - **example\_method(flag: bool = False) -\> None** Method *example\_method()* of class *ExampleCls* ### Text Formatting - **DXF version** DXF R12 (AC1009), DXF R2004 (AC1018) - **DXF Types** DXF types are always written in uppercase letters but without further formatting: DXF, LINE, CIRCLE - **(internal API)** Marks methods as internal API, gets no public documentation. - **(internal class)** Marks classes only for internal usage, gets not public documentation. - **Spatial Dimensions** 2D and 3D with an uppercase letter D - **Axis** x-axis, y-axis and z-axis - **Planes** xy-plane, xz-plane, yz-plane - **Layouts** modelspace, paperspace \[layout\], block \[layout\] - **Extended Entity Data** AppData, XDATA, embedded object, APPID ## LAUNCHER The command line script *ezdxf* launches various sub-commands: | | | | --- | --- | | **audit** | Audit and repair DXF files | | **draw** | Draw and convert DXF files by the Matplotlib backend | | **view** | PyQt DXF file viewer | | **browse** | PyQt DXF structure browser for DXF debugging and curious people | | **browse-acis** | PyQt ACIS entity content browser for SAT/SAB debugging | | **strip** | Strip comments and THUMBNAILIMAGE section from DXF files | | **config** | Manage config files | | **info** | Show information and optional stats of DXF files as loaded by ezdxf | | **hpgl** | View and/or convert HPGL/2 plot files to DXF, SVG or PDF | The help option **-h** is supported by the main script and all sub-commands: ``` C:\> ezdxf -h usage: ezdxf [-h] [-V] [-v] [--config CONFIG] [--log LOG] {pp,audit,draw,view,browse,browse-acis,strip,config} ... Command launcher for the Python package "ezdxf": https://pypi.org/project/ezdxf/ positional arguments: {audit,draw,view,browse,strip} audit audit and repair DXF files draw draw and convert DXF files by Matplotlib view view DXF files by the PyQt viewer browse browse DXF file structure browse-acis browse ACIS structures in DXF files strip strip comments from DXF files config manage config files info show information and optional stats of DXF files loaded by ezdxf, this may not represent the original content of the file, use the browse command to see the original content optional arguments: -h, --help show this help message and exit -V, --version show version and exit -f, --fonts rebuild system font cache and print all fonts found -v, --verbose give more output --config CONFIG path to a config file --log LOG path to a verbose appending log ``` **NOTE:** The **ezdxf** script is the only executable script installed on the user system. ### System **ezdxf -V** shows the *ezdxf* and *Python* version your are running and if the C-extensions are used. ``` ezdxf 1.1.0b1 from c:\source\ezdxf.git\src\ezdxf Python version: 3.11.2 (tags/v3.11.2:878ead1, Feb 7 2023, 16:38:35) [MSC v.1934 64 bit (AMD64)] using C-extensions: yes ``` **ezdxf -f** rebuilds the system font cache and shows all fonts found. ### Audit Audit and recover the DXF file “gear.dxf” and save the recovered version as “gear.rec.dxf”: ``` C:\> ezdxf audit -s gear.dxf auditing file: gear.dxf No errors found. Saved recovered file as: gear.rec.dxf ``` Print help: ``` C:\> ezdxf audit -h usage: ezdxf audit [-h] [-s] FILE [FILE ...] positional arguments: FILE audit DXF files optional arguments: -h, --help show this help message and exit -s, --save save recovered files with extension ".rec.dxf" ``` ### Draw Convert the DXF file “gear.dxf” into a SVG file by the *Matplotlib* backend: Added in version 1.2.0: support for more backends ``` C:\> ezdxf draw -o gear.svg gear.dxf ``` The “gear.svg” created by the *Matplotlib* backend: \[image\] Show all output formats supported by the *Matplotlib* backend on your system. This output may vary: ``` C:\> ezdxf draw --formats eps: Encapsulated Postscript jpg: Joint Photographic Experts Group jpeg: Joint Photographic Experts Group pdf: Portable Document Format pgf: PGF code for LaTeX png: Portable Network Graphics ps: Postscript raw: Raw RGBA bitmap rgba: Raw RGBA bitmap svg: Scalable Vector Graphics svgz: Scalable Vector Graphics tif: Tagged Image File Format tiff: Tagged Image File Format ``` Print help: ``` C:\> ezdxf draw -h usage: ezdxf draw [-h] [--backend {matplotlib,qt,mupdf,custom_svg}] [--formats] [-l LAYOUT] [--background {DEFAULT,WHITE,BLACK,PAPERSPACE,MODELSPACE,OFF,CUSTOM}] [--all-layers-visible] [--all-entities-visible] [-o OUT] [--dpi DPI] [-f] [-v] [FILE] positional arguments: FILE DXF file to view or convert options: -h, --help show this help message and exit --backend {matplotlib,qt,mupdf,custom_svg} choose the backend to use for rendering --formats show all supported export formats and exit -l LAYOUT, --layout LAYOUT select the layout to draw, default is "Model" --background {DEFAULT,WHITE,BLACK,PAPERSPACE,MODELSPACE,OFF,CUSTOM} choose the background color to use --all-layers-visible draw all layers including the ones marked as invisible --all-entities-visible draw all entities including the ones marked as invisible (some entities are individually marked as invisible even if the layer is visible) -o OUT, --out OUT output filename for export --dpi DPI target render resolution, default is 300 -f, --force overwrite the destination if it already exists -v, --verbose give more output ``` ### View View the DXF file “gear.dxf” by the *PyQt* backend: ``` C:\> ezdxf view gear.dxf ``` \[image\] Print help: ``` C:\> ezdxf view -h usage: ezdxf view [-h] [-l LAYOUT] [--lwscale LWSCALE] [FILE] positional arguments: FILE DXF file to view optional arguments: -h, --help show this help message and exit -l LAYOUT, --layout LAYOUT select the layout to draw, default is "Model" --lwscale LWSCALE set custom line weight scaling, default is 0 to disable line weights at all ``` ### Browse Browse the internal structure of a DXF file like a file system: ``` C:\> ezdxf browse gear.dxf ``` \[image\] ``` C:\> ezdxf browse -h usage: ezdxf browse [-h] [-l LINE] [-g HANDLE] [FILE] positional arguments: FILE DXF file to browse optional arguments: -h, --help show this help message and exit -l LINE, --line LINE go to line number -g HANDLE, --handle HANDLE go to entity by HANDLE, HANDLE has to be a hex value without any prefix like 'fefe' ``` The *browse* command stores options in the config file, e.g. for the *Notepad++* on Windows: ``` [browse-command] text_editor = "C:\Program Files\Notepad++\notepad++.exe" "{filename}" -n{num} icon_size = 32 ``` **text\_editor** is a simple format string: **text\_editor.format(filename="test.dxf", num=100)** Quote commands including spaces and always quote the filename argument! For *xed* on Linux Mint use (note: absolute path to executable): ``` [browse-command] text_editor = /usr/bin/xed "{filename}" +{num} icon_size = 32 ``` For *gedit* on Linux use (untested): ``` [browse-command] text_editor = /usr/bin/gedit +{num} "{filename}" icon_size = 32 ``` The *browse* command opens a DXF structure browser to investigate the internals of a DXF file without interpreting the content. The intended usage is debugging invalid DXF files, which can not be loaded by the *ezdxf.readfile()* or the *ezdxf.recover.readfile()* functions. ### Line Numbers The low level tag loader ignores DXF comments (group code 999). If there are comments in the DXF file the line numbers displayed in the DXF browser are not synchronized, use the *strip* command beforehand to remove all comments from the DXF file in order to keep the line numbers synchronized. ### GUI Features The tree view on the left shows the outline of the DXF file. The number in round brackets on the right side of each item shows the count of structure entities within the structure layer, the value in angle brackets on the left side is the entity handle. The right list view shows the entity content as DXF tags. Structure tags (data type \) are shown in blue, a double click on a reference handle (datatype \) jumps to the referenced entity, reference handles of non-existent targets are shown in red. Clicking on the first structure tag in the list opens the DXF reference provided by Autodesk in the standard web browser. ### Auto Reload The browser automatically displays a dialog for reloading DXF files if they have been modified by an external application. ### Menus and Shortcuts - • - **File Menu** - • **Open DXF file…** *Ctrl+O* - • **Reload DXF file** *Ctrl+R* - • **Open in Text Editor** *Ctrl+T*, open the DXF file in the associated text editor at the current location - • **Export DXF Entity…** *Ctrl+E*, export the current DXF entity shown in the list view as text file - • **Copy selected DXF Tags to Clipboard** *Ctrl+C*, copy the current selected DXF tags into the clipboard - • **Copy DXF Entity to Clipboard** *Ctrl+Shift+C*, copy all DXF tags of the current DXF entity shown in the list view into the clipboard - • **Quit** *Ctrl+Q* - • - **Navigate Menu** - • **Go to Handle…** *Ctrl+G* - • **Go to Line…** *Ctrl+L* - • **Find Text…** *Ctrl+F*, opens the find text dialog - • **Next Entity** *Ctrl+Right*, go to the next entity in the DXF structure - • **Previous Entity** *Ctrl+Right*, go to the previous entity in the DXF structure - • **Show Entity in TreeView** *Ctrl+Down*, expand the left tree view to the currently displayed entity in the list view - this does not happen automatically for performance reasons - • **Entity History Back** *Alt+Left* - • **Entity History Forward** *Alt+Right* - • **Go to HEADERS Section** *Shift+H* - • **Go to BLOCKS Section** *Shift+B* - • **Go to ENTITIES Section** *Shift+E* - • **Go to OBJECTS Section** *Shift+O* - • - **Bookmarks Menu** - • **Store Bookmark…** *Ctrl+Shift+B*, store current location as named bookmark - • **Go to Bookmark…** *Ctrl+B*, go to stored location ### Browse-ACIS Show and export the *SAT* or *SAB* content of *ACIS* entities: ``` C:\> ezdxf browse-acis 3dsolid.dxf ``` \[image\] The DXF format stores modern solid geometry as *SAT* data for DXF R2000 - R2010 and as *SAB* data for DXF R2013 and later. This command shows the content of this entities and also let you export the raw data for further processing. ### Entity View The entity view is a read-only text editor, it’s possible to select and copy parts of the text into the clipboard. To improve the readability all ACIS entities get automatically an id because AutoCAD and BricsCAD use relative references for ACIS data export and do not assign entity ids. The id is shown as decimal number in parenthesis after the entity name. The **~** character is a shortcut for a null-pointer. ``` C:\>ezdxf browse-acis -h usage: ezdxf browse-acis [-h] [-g HANDLE] [FILE] positional arguments: FILE DXF file to browse options: -h, --help show this help message and exit -g HANDLE, --handle HANDLE go to entity by HANDLE, HANDLE has to be a hex value without any prefix like 'fefe' ``` ### Menus and Shortcuts - • - **File Menu** - • **Open DXF file…** *Ctrl+O* - • **Reload DXF file** *Ctrl+R* - • **Export Current Entity View…** *Ctrl+E*, Export the parsed content of the entity view as text file - • **Export Raw SAT/SAB Data…** *Ctrl+W*, export the raw SAT data as text file and the raw SAB data as a binary file for further processing - • **Quit** *Ctrl+Q* ### Strip Strip comment tags (group code 999) from ASCII DXF files and can remove the THUMBNAILIMAGE section. Binary DXF files are not supported. Added in version 1.1.3: remove handles from DXF R12 and older ``` C:\> ezdxf strip -h usage: ezdxf strip [-h] [-b] [-t] [--handles] [-v] FILE [FILE ...] positional arguments: FILE DXF file to process, wildcards "*" and "?" are supported options: -h, --help show this help message and exit -b, --backup make a backup copy with extension ".bak" from the DXF file, overwrites existing backup files -t, --thumbnail strip THUMBNAILIMAGE section --handles remove handles from DXF R12 or older files -v, --verbose give more output ``` ### Config Manage config files. ``` C:\> ezdxf config -h usage: ezdxf config [-h] [-p] [-w FILE] [--home] [--reset] optional arguments: -h, --help show this help message and exit -p, --print print configuration -w FILE, --write FILE write configuration --home create config file 'ezdxf.ini' in the user home directory '~/.config/ezdxf', $XDG_CONFIG_HOME is supported if set --reset factory reset, delete default config files 'ezdxf.ini' ``` ### Info Show information and optional stats of DXF files as loaded by *ezdxf*, this may not represent the original content of the file, use the *browse* command to see the original content. The upgrade is necessary for very old DXF versions prior to R12 and for the “special” versions R13 and R14. The *-s* option shows some statistics about the DXF content like entity count or table count. Use the *-v* option show more of everything. ``` C:\> ezdxf info -h usage: ezdxf info [-h] [-v] [-s] FILE [FILE ...] positional arguments: FILE DXF file to process, wildcards "*" and "?" are supported options: -h, --help show this help message and exit -v, --verbose give more output -s, --stats show content stats ``` This is the verbose output for an old DXF R10 file and shows that the loading process created some required structures which do not exist in DXF R10 files, like the BLOCK\_RECORD table or the OBJECTS section: ``` C:\> ezdxf info -v -s test_R10.dxf Filename: "test_R10.dxf" Loaded content was upgraded from DXF Version AC1006 (R10) Release: R12 DXF Version: AC1009 Maintenance Version: Codepage: ANSI_1252 Encoding: cp1252 Unit system: Imperial Modelspace units: Unitless $LASTSAVEDBY: $HANDSEED: 0 $FINGERPRINTGUID: {9EADDC7C-5982-4C68-B770-8A62378C2B90} $VERSIONGUID: {49336E63-D99B-45EC-803C-4D2BD03A7DE0} $USERI1=0 $USERI2=0 $USERI3=0 $USERI4=0 $USERI5=0 $USERR1=0.0 $USERR2=0.0 $USERR3=0.0 $USERR4=0.0 $USERR5=0.0 File was not created by ezdxf >= 0.16.4 File was not written by ezdxf >= 0.16.4 Content stats: LAYER table entries: 18 0 Defpoints LYR_00 LYR_01 LYR_02 LYR_03 LYR_04 LYR_05 LYR_06 LYR_07 LYR_08 LYR_09 LYR_10 LYR_11 LYR_12 LYR_13 LYR_14 LYR_15 LTYPE table entries: 13 BORDER ByBlock ByLayer CENTER CONTINUOUS CUTTING DASHDOT DASHED DIVIDE DOT HIDDEN PHANTOM STITCH STYLE table entries: 1 STANDARD DIMSTYLE table entries: 1 Standard APPID table entries: 1 ACAD UCS table entries: 0 VIEW table entries: 0 VPORT table entries: 1 *Active BLOCK_RECORD table entries: 2 *Model_Space *Paper_Space Entities in modelspace: 78 ARC (2) CIRCLE (2) LINE (74) Entities in OBJECTS section: 20 ACDBDICTIONARYWDFLT (1) ACDBPLACEHOLDER (1) DICTIONARY (11) LAYOUT (2) MATERIAL (3) MLEADERSTYLE (1) MLINESTYLE (1) ``` ### Show Version & Configuration Show the *ezdxf* version and configuration: ``` C:\> ezdxf -Vv ezdxf v0.16.5b0 @ d:\source\ezdxf.git\src\ezdxf Python version: 3.9.6 (tags/v3.9.6:db3ff76, Jun 28 2021, 15:26:21) [MSC v.1929 64 bit (AMD64)] using C-extensions: yes using Matplotlib: yes Configuration: [core] default_dimension_text_style = OpenSansCondensed-Light test_files = D:\Source\dxftest font_cache_directory = load_proxy_graphics = true store_proxy_graphics = true log_unprocessed_tags = false filter_invalid_xdata_group_codes = true write_fixed_meta_data_for_testing = false disable_c_ext = false [browse-command] text_editor = "C:\Program Files\Notepad++\notepad++.exe" "{filename}" -n{num} Environment Variables: EZDXF_DISABLE_C_EXT= EZDXF_TEST_FILES=D:\Source\dxftest EZDXF_CONFIG_FILE= Existing Configuration Files: C:\Users\manfred\.config\ezdxf\ezdxf.ini ``` **SEE ALSO:** Documentation of the *ezdxf.options* module and the *Environment Variables*. ### HPGL/2 Viewer/Converter Added in version 1.1. The **hpgl** command shows and/or converts *HPGL/2* plot files to DXF, SVG or PDF. ### DXF The page content is created at the origin of the modelspace and 1 drawing unit is 1 plot unit (1 plu = 0.025mm) unless scaling values are provided. The content of HPGL files is intended to be plotted on white paper, so the appearance on a dark background in modelspace is not very clear. To fix this, the **--map\_black\_to\_white** option maps black fillings and lines to white. All entities are mapped to a layer named **COLOR\_\<#\>** according to the pen number. In order to process the content better, it is also possible to assign the DXF elements an ACI color value according to the pen number through the **--aci** option, but then the RGB color is lost because the RGB color always has the higher priority over the *ACI* value. The first paperspace layout “Layout0” is set up to print the entire modelspace on one sheet, the size of the page is the size of the original plot file in millimeters. ### SVG The plot units are mapped 1:1 to **viewBox** units and the size of image is the size of the original plot file in millimeters. ### PDF The plot units are converted to PDF units (1/72 inch) so the size of image is the size of the original plot file in millimeters. ### All Formats HPGL/2’s merge control works at the pixel level and cannot be replicated by DXF, but to prevent fillings from obscuring text, the filled polygons are sorted by luminance - this can be forced or disabled by the **--merge\_control** option. Some plot files that contain pure HPGL/2 code do not contain the escape sequence “Enter HPGL/2 mode”, without this sequence the HPGL/2 parser cannot recognize the beginning of the HPGL/2 code. The **--force** option inserts the “Enter HPGL/2 mode” escape sequence into the data stream, regardless of whether the file is an HPGL/2 plot file or not, so be careful. ``` C:\> ezdxf hpgl -h usage: ezdxf hpgl [-h] [-e FORMAT] [-r {0,90,180,270}] [-x SX] [-y SY] [-m {0,1,2}] [-f] [--aci] [--map_black_to_white] [FILE] positional arguments: FILE view and/or convert HPGL/2 plot files, wildcards (*, ?) supported in command line mode options: -h, --help show this help message and exit -e FORMAT, --export FORMAT convert HPGL/2 plot file to SVG, PDF or DXF from the command line (no gui) -r {0,90,180,270}, --rotate {0,90,180,270} rotate page about 90, 180 or 270 degrees (no gui) -x SX, --scale_x SX scale page in x-axis direction, use negative values to mirror page, (no gui) -y SY, --scale_y SY scale page in y-axis direction, use negative values to mirror page (no gui) -m {0,1,2}, --merge_control {0,1,2} provides control over the order of filled polygons, 0=off (print order), 1=luminance (order by luminance), 2=auto (default) -f, --force inserts the mandatory 'enter HPGL/2 mode' escape sequence into the data stream; use this flag when no HPGL/2 data was found and you are sure the file is a HPGL/2 plot file --aci use pen numbers as ACI colors (DXF only) --map_black_to_white map black RGB plot colors to white RGB, does not affect ACI colors (DXF only) Note that plot files are intended to be plotted on white paper. ``` ## TUTORIALS ### 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:** - • *Document Management* - • *Usage for Beginners* ### 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: - • *Modelspace*: the common construction space - • *Paperspace*: used to to create print layouts - • *BlockLayout*: reusable elements, every block has its own entity space 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:** *Entity Query String* 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:** *Extended EntityQuery Features* ### 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:** *groupby()* documentation ### 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:** *Thematic Index of Layout Factory Methods* ### 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:** To see the defined text styles in a DXF viewer or CAD application, the applications have to know where the referenced TTF fonts can be found. This configuration is not possible by *ezdxf* and has to be done for each application as described in their documentation. See also: *Font Resources* ### 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:** *r12writer* ### 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: | | | | --- | --- | | R12 | **color**, **linetype** | | R2000 | **lineweight**, **ltscale**, **invisible** | | R2004 | **true\_color**, **transparency** | ### 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:** - • Basics about *AutoCAD Color Index (ACI)* - • *ezdxf.colors* module ### 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:** - • Basics about *True Color* - • *ezdxf.colors* module ### 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:** - • Basics about *Transparency* - • *ezdxf.colors* module ### 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:** Make sure the linetype you assign to an entity is really defined in the linetype table otherwise AutoCAD will not open the DXF file. There are no implicit checks for that by *ezdxf* but you can call the *audit()* method of the DXF document explicitly to validate the document before exporting. *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:** - • Basics about *Linetypes* - • *Tutorial for Creating Linetype Pattern* ### 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* | | | | --- | --- | | -1 | LINEWEIGHT\_BYLAYER | | -2 | LINEWEIGHT\_BYBLOCK | | -3 | LINEWEIGHT\_DEFAULT | 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:** 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. ``` # activate on screen lineweight display doc.header["$LWDISPLAY"] = 1 ``` **SEE ALSO:** - • Basics about *Lineweights* ### 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:** - • Basics about *Linetypes* ### 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:** - • *ezdxf.gfxattribs* module ### 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:** For all methods and attributes see class *Layer*. ### 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:** The behavior of entities referencing the layer by handle is unknown and may break the DXF document. ### 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, ...] ``` - **total\_pattern\_length** Sum of all linetype elements (absolute values) - **elem** if elem \> 0 it is a line, if elem \< 0 it is gap, if elem == 0.0 it is a dot 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:** Ezdxf does not check if a linetype is still in use and deleting a linetype which is still in use generates an **invalid** DXF file. The audit process *audit()* of the DXF document removes **linetype** attributes referencing non existing linetypes. 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: - • A text in quotes (e.g. “GAS”) defines a *complex TEXT linetype* and represents the pattern text itself. - • A text without quotes is a SHAPE name (in “.lin” files) and defines a *complex SHAPE linetype. Ezdxf can not translate this SHAPE name from the* *“.lin” file into the required shape file index, so \*YOU* have to translate this SHAPE name into the shape file index, e.g. saving the file with AutoCAD as DXF and searching for the DXF linetype definition, see example below and the DXF Internals: *LTYPE Table*. 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: | | | | --- | --- | | S | scaling factor, always \> 0, if S=0 the TEXT or SHAPE is not visible | | R or U | rotation relative to the line direction | | X | x-direction offset (along the line) | | Y | y-direction offset (perpendicular to the line) | 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:** - • *Tutorial for Creating DXF Drawings* - • *Tutorial for Layers* - • *ezdxf.gfxattribs* module ### 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:** - • Reference of class *Point* - • *Tutorial for Common Graphical Attributes* ### 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:** - • Reference of class *Line* - • *Tutorial for Common Graphical Attributes* - • *ezdxf.math.ConstructionLine* ### 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:** - • Reference of class *Circle* - • *Tutorial for Common Graphical Attributes* - • *ezdxf.math.ConstructionCircle* ### 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: - • *from\_2p\_angle*: arc from 2 points and an angle - • *from\_2p\_radius*: arc from 2 points and a radius - • *from\_3p*: arc from 3 points 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:** - • Reference of class *Arc* - • *Tutorial for Common Graphical Attributes* - • *ezdxf.math.ConstructionArc* ### 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:** - • Reference of class *Ellipse* - • *Tutorial for Common Graphical Attributes* - • *ezdxf.math.ConstructionEllipse* ### Further Tutorials - • *Tutorial for LWPolyline* - • *Tutorial for Spline* - • *Tutorial for Text* - • *Tutorial for MText and MTextEditor* - • *Tutorial for Hatch* - • *Tutorial for MultiLeader* - • *Tutorial for Mesh* ### Tutorial for Entity Selection This tutorial shows how to use the *ezdxf.select* module, which provides functions to select entities based on various shapes. These selection functions offer a way to filter entities based on their spatial location. This is the base document for this tutorial: \[image\] ### Why Bounding Boxes? The *select* module primarily relies on bounding boxes to perform selections. Bounding boxes offer a fast way to identify potential overlaps between entities and the selection shape. This approach prioritizes performance over absolute accuracy. **NOTE:** The bounding boxes for text-based entities and entities containing curves are not accurate! For more information read the docs for the *ezdxf.bbox* module. ### Source of Entities The source of the selection can be any iterable of DXF entities, like the modelspace, any paperspace layout or a block layout, also the result of an entity query as an *EntityQuery* container, or any collection of DXF entities that implements the **\_\_iter\_\_()** method. ### Selection Shapes - • *Window*: Defines a rectangular selection area. - • *Circle*: Selects entities within a circular area. - • *Polygon*: Selects entities based on the shape of a closed polygon. ### Using Selection Functions These selection functions utilize the selection shapes: - • *bbox\_inside()*: Selects entities whose bounding box lies withing the selection shape. - • *bbox\_outside()*: Selects entities whose bounding box is completely outside the selection shape. - • *bbox\_overlap()*: Selects entities whose bounding box overlaps the selection shape. Additional selection functions: - • *bbox\_chained()*: Selects entities that are linked together by overlapping bounding boxes. - • *bbox\_crosses\_fence()*: Selects entities whose bounding box overlaps an open polyline. - • *point\_in\_bbox()*: Selects entities where the selection point lies within the bounding box. The functions return an *EntityQuery* object, which provides access to the selected entities. You can iterate over the **EntityQuery** to access each selected entity. ### Bounding Box Inside Selection Selects entities which bounding boxes are completely within the selection shape. Example to select entities inside a window: \[image\] ``` import ezdxf from ezdxf import select doc = ezdxf.readfile("base.dxf") msp 0 doc.modelspace() window = select.Window((150, 105), (280, 240)) for entity in select.bbox_inside(window, msp): print(str(entity)) ``` output: ``` CIRCLE(#9D) LWPOLYLINE(#9E) ``` ### Bounding Box Outside Selection Selects entities whose bounding box is completely outside the selection shape. \[image\] ``` window = select.Window((185, 105), (245, 240)) for entity in select.bbox_outside(window, msp): print(str(entity)) ``` output: ``` TEXT(#9F) SPLINE(#A0) LINE(#A1) ``` ### Bounding Box Overlap Selection Selects entities whose bounding box overlaps the selection shape. This function works similar to the crossing selection in CAD applications, but not exactly the same. The function selects entities whose bounding boxes overlap the selection shape. This will also select elements where all of the entity geometry is outside the selection shape, but the bounding box overlaps the selection shape, e.g. border polylines. \[image\] ``` window = select.Window((150, 105), (280, 240)) for entity in select.bbox_overlap(window, msp): print(str(entity)) ``` output: ``` CIRCLE(#9D) LWPOLYLINE(#9E) TEXT(#9F) SPLINE(#A0) LINE(#A1) LWPOLYLINE(#A2) ``` ### Bounding Box Chained Selection Selects elements that are directly or indirectly connected to each other by overlapping bounding boxes. The selection begins at the specified starting element. \[image\] ``` # choose entity for the beginning of the chain: line = msp.query("LINE").first for entity in select.bbox_chained(line, msp): print(str(entity)) ``` output: ``` LINE(#A1) CIRCLE(#9D) LWPOLYLINE(#9E) SPLINE(#A0) ``` ### Bounding Box Crosses Fence Selects entities whose bounding box intersects an open polyline. \[image\] ``` for entity in select.bbox_crosses_fence([(83, 101), (186, 193), (300, 107)], msp): print(str(entity)) ``` output: ``` CIRCLE(#9D) LWPOLYLINE(#9E) SPLINE(#A0) LINE(#A1) ``` **NOTE:** The polyline does not cross the entity geometry itself! ### Point In Bounding Box Selection Selects entities where the selection point lies within the bounding box. \[image\] ``` for entity in select.bbox_point((264, 140), msp): print(str(entity)) ``` output: ``` LWPOLYLINE(#9E) SPLINE(#A0) ``` ### Circle Selection For the circle shape, the selection tests are carried out on the real circlar area. This example selects all entities around the CIRCLE entity within a 60 unit radius whose bounding box overlaps the circle selection: \[image\] ``` entity = msp.query("CIRCLE").first circle = select.Circle(entity.dxf.center, radius=60) for entity in select.bbox_overlap(circle, msp): print(str(entity)) ``` output: ``` CIRCLE(#9D) LWPOLYLINE(#9E) TEXT(#9F) SPLINE(#A0) ``` ### Polygon Selection As for the circle shape, the polygon selection tests are carried out on the real polygon area. **NOTE:** This may not work 100% correctly if the selection polygon has a complex concave shape! This example selects all entities whose bounding box lies entirely within the selection polygon: \[image\] ``` polygon = select.Polygon([(110, 168), (110, 107), (316, 107), (316, 243), (236, 243)]) for entity in select.bbox_inside(polygon, msp): print(str(entity)) ``` output: ``` LWPOLYLINE(#9E) SPLINE(#A0) LINE(#A1) ``` ### 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: - • *Modelspace* - • *Paperspace* - • *BlockLayout* 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:** The LWPOLYLINE is a planar element, therefore the (x, y) point coordinates are located in the *OCS* and the z-axis is stored in the **LWPolyline.dxf.elevation** attribute. The method *vertices\_in\_wcs* returns the polyline vertices as WCS coordinates. 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") ``` \[image\] 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**: - • **x** = x coordinate - • **y** = y coordinate - • **s** = start width - • **e** = end width - • **b** = bulge value - • **v** = (x, y) as tuple ``` 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") ``` \[image\] ### 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*: | | | | | | --- | --- | --- | --- | | Vert/Horiz | Left | Center | Right | | Top | **TOP\_LEFT** | **TOP\_CENTER** | **TOP\_RIGHT** | | Middle | **MIDDLE\_LEFT** | **MIDDLE\_CENTER** | **MIDDLE\_RIGHT** | | Bottom | **BOTTOM\_LEFT** | **BOTTOM\_CENTER** | **BOTTOM\_RIGHT** | | Baseline | **LEFT** | **CENTER** | **RIGHT** | 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. | | | | --- | --- | | Alignment | Description | | **ALIGNED** | Text is stretched or compressed to fit exactly between *p1* and *p2* and the text height is also adjusted to preserve height/width ratio. | | **FIT** | Text is stretched or compressed to fit exactly between *p1* and *p2* but only the text width is adjusted, the text height is fixed by the *height* attribute. | | **MIDDLE** | also a *special* adjustment, but the result is the same as for **MIDDLE\_CENTER**. | ### 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:** To see the defined text styles in a DXF viewer or CAD application, the applications have to know where the referenced TTF fonts can be found. This configuration is not possible by *ezdxf* and has to be done for each application as described in their documentation. See also: *Font Resources* ### 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*: - • open font folder *c:\\windows\\fonts* - • select and open the font-family *Open Sans* - • right-click on *Open Sans Standard* and select *Properties* - • on top of the first tab you see the font name: **'OpenSans-Regular.ttf'** 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:** The rendering result of the MTEXT entity depends on the DXF viewer or CAD application and can differ between different applications. These differences have the greatest impact on line wrapping, which can cause columns of text to have different heights in different applications! In order for the text to look similar in different programs, the formatting should be as simple as possible or omitted altogether. 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." ``` \[image\] The **MText** entity has an alias **MText.dxf.text** for the **MText.text** attribute for compatibility to the **Text** entity. **IMPORTANT:** Line endings “\\n” will be replaced by the MTEXT line endings “\\P” at DXF export, but **not** vice versa “\\P” by “\\n” at DXF file loading. ### 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*: | | | | --- | --- | | MText.dxf.attachment\_point | Value | | MTEXT\_TOP\_LEFT | 1 | | MTEXT\_TOP\_CENTER | 2 | | MTEXT\_TOP\_RIGHT | 3 | | MTEXT\_MIDDLE\_LEFT | 4 | | MTEXT\_MIDDLE\_CENTER | 5 | | MTEXT\_MIDDLE\_RIGHT | 6 | | MTEXT\_BOTTOM\_LEFT | 7 | | MTEXT\_BOTTOM\_CENTER | 8 | | MTEXT\_BOTTOM\_RIGHT | 9 | 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 ``` \[image\] ### MTEXT formatting MTEXT supports inline formatting by special codes: *MText Inline Codes* ``` mtext.text = "{\\C1;red text} - {\\C3;green text} - {\\C5;blue text}" ``` \[image\] 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;" ``` \[image\] See also the support class *MTextEditor*. ### Background color (filling) The MTEXT entity can have a background filling: - • *AutoCAD Color Index (ACI)* - • true color value as **(r, g, b)** tuple - • color name as string, use special name **'canvas'** to use the canvas background color 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** assembles just the inline code, which has to be parsed and rendered by the target CAD application, *ezdxf* has no influence to that result. Keep inline formatting as simple as possible, don’t test the limits of its capabilities, this will not work across different CAD applications and keep the formatting in a logic manner like, do not change paragraph properties in the middle of a paragraph. **There is no official documentation for the inline codes!** 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: - • by color name “red”, “green”, “blue”, “yellow”, “cyan”, “magenta”, “white” - • by *AutoCAD Color Index (ACI)* - • by RGB values ``` # 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) ``` \[image\] ### 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) ``` \[image\] 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:** The DXF/DWG format is not optimal for preserving text layouts across multiple systems, and it’s getting really bad across different CAD applications. ``` 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) ``` \[image\] ### 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 arguments: - • **indent** is the left indentation of the first line - • **left** is the left side indentation of the paragraph - • **right** is the right side indentation of the paragraph - • text adjustment: **align**, by enum **MTextParagraphAlignment** - • MTextParagraphAlignment.LEFT - • MTextParagraphAlignment.RIGHT - • MTextParagraphAlignment.CENTER - • MTextParagraphAlignment.JUSTIFIED - • MTextParagraphAlignment.DISTRIBUTED - • tabulator stops: **tab\_stops**, a tuple of tabulator stops 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) ``` \[image\] 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) ``` \[image\] ### 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) ``` \[image\] ### 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) ``` \[image\] ### 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) ``` \[image\] **SEE ALSO:** - • *MTextEditor* example code on *github*. - • Documentation of *MTextEditor* ### 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) ``` \[image\] 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)) ``` \[image\] 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. 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}) ``` - • black curve: AutoCAD/BricsCAD spline generated from fit points - • red curve: spline curve interpolation, “uniform” method - • green curve: spline curve interpolation, “chord” method - • blue curve: spline curve interpolation, “centripetal” method \[image\] Since *ezdxf* v1.1 the method *add\_cad\_spline\_control\_frame()* calculates the same control points from fit points as AutoCAD and BricsCAD. ### 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) ``` \[image\] ### 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_rational_spline(control_points, weights=[3, 1, 1, 1]) ``` \[image\] ### Spline Tangents The tangents of a spline are the directions of the first derivative of the curve: ``` # additional required imports: from ezdxf.math import Vec3, estimate_tangents import numpy as np # snip -x-x-x- fit_points = Vec3.list( [ (0, 0, 0), (1000, 600, 0), (1500, 1200, 0), (500, 1250, 0), (0, 0, 0), ] ) spline = msp.add_spline(fit_points) # draw the curve tangents as red lines: ct = spline.construction_tool() for t in np.linspace(0, ct.max_t, 30): point, derivative = ct.derivative(t, 1) msp.add_line(point, point + derivative.normalize(200), dxfattribs={"color": 1}) ``` \[image\] To get a smooth closed curve the start- and end tangents have to be set manually when the control points are calculated and they have to point in the same direction: ``` t0= Vec3(1, -1, 0) # the length (magnitude) of the tangent is not relevant! spline = msp.add_cad_spline_control_frame(fit_points, tangents=[t0, t0]) ``` \[image\] To avoid guess work the function *ezdxf.math.estimate\_tangents()* can be used to estimate the start- and end tangents of the curve: ``` tangents = estimate_tangents(fit_points) # linear interpolation of the first and the last tangent: t0 = tangents[0].lerp(tangents[-1], 0.5) msp.add_cad_spline_control_frame(fit_points, tangents=[t0, t0]) ``` \[image\] It is also possible to add the SPLINE by fit-points and setting the tangents as DXF attributes: ``` spline = msp.add_spline(fit_points) spline.dxf.flags = spline.PERIODIC | spline.CLOSED spline.dxf.start_tangent = t0 spline.dxf.end_tangent = t0 ``` ### 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 = (0, 1, 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") ``` \[image\] **WARNING:** If the mesh contains n-gons the render methods for POLYFACE and 3DFACES subdivides the n-gons into triangles, which does **not** work for concave faces. The usage of the *MeshBuilder* object is also recommended for inspecting **Polyface** entities: - • **MeshBuilder.vertices** is a sequence of 3D points as *ezdxf.math.Vec3* objects - • a face in **MeshBuilder.faces** is a sequence of indices into the **MeshBuilder.vertices** sequence ``` 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* ### 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") ``` \[image\] There exist some tools to manage meshes: - • *ezdxf.render.MeshBuilder*: The *MeshBuilder* classes are helper tools to manage meshes buildup by vertices and faces. - • *ezdxf.render.MeshTransformer*: Same functionality as *MeshBuilder* but supports inplace transformation. - • *ezdxf.render.MeshDiagnose*: A diagnose tool which can be used to analyze and detect errors of *MeshBuilder* objects like topology errors for closed surfaces. - • *ezdxf.render.FaceOrientationDetector*: A helper class for face orientation and face normal vector detection 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") ``` \[image\] ### 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: - • line **EdgePath.add\_line()** - • arc **EdgePath.add\_arc()** - • ellipse **EdgePath.add\_ellipse()** - • spline **EdgePath.add\_spline()** 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: | | | | --- | --- | | 0 | nested - altering filled and unfilled areas | | 1 | outer - area between *external* and *outermost* path is filled | | 2 | ignore - *external* path is filled | ``` 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, ) ``` \[image\] ``` # 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") ``` \[image\] 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) ``` \[image\] ### Load Hatch Patterns From File CAD applications store the hatch patterns in pattern files with the file extension **.pat**. The following script shows how to load and use these pattern files: ``` from ezdxf.tools import pattern EXAMPLE = """; a pattern file *SOLID, Solid fill 45, 0,0, 0,.125 *ANSI31, ANSI Iron, Brick, Stone masonry 45, 0,0, 0,.125 *ANSI32, ANSI Steel 45, 0,0, 0,.375 45, .176776695,0, 0,.375 *ANSI33, ANSI Bronze, Brass, Copper 45, 0,0, 0,.25 45, .176776695,0, 0,.25, .125,-.0625 *ANSI34, ANSI Plastic, Rubber 45, 0,0, 0,.75 45, .176776695,0, 0,.75 45, .353553391,0, 0,.75 45, .530330086,0, 0,.75 """ hatch = msp.add_hatch() # load your pattern file from the file system as string: # with open("pattern_file.pat", "rt") as fp: # EXAMPLE = fp.read() patterns = pattern.parse(EXAMPLE) hatch.set_pattern_fill( "MyPattern", color=7, angle=0, # the overall rotation of the pattern in degrees scale=1.0, # overall scaling of the pattern style=0, # normal hatching style pattern_type=0, # user-defined # pattern name without the preceding asterisk definition=patterns["ANSI34"], ) points = [(0, 0), (10, 0), (10, 10), (0, 10)] hatch.paths.add_polyline_path(points) msp.add_lwpolyline(points, close=True, dxfattribs={"color": 1}) ``` **SEE ALSO:** *Tutorial for Hatch Pattern Definition* ### 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 hatch pattern must be defined for a hatch scaling factor of 1.0 and a hatch rotation angle of 0 degrees! 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") ``` \[image\] 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- ``` \[image\] 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- ``` \[image\] 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- ``` \[image\] ### 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:** The raster image is NOT embedded in the DXF file! ``` import ezdxf # The IMAGE entity requires the DXF R2000 format or later. doc = ezdxf.new("R2000") # The IMAGEDEF entity is like a block definition, it just defines the image. my_image_def = doc.add_image_def( filename="mycat.jpg", size_in_pixel=(640, 360) ) msp = doc.modelspace() # The IMAGE entity is like the INSERT entity, it's just an image reference, # and there can be multiple references to the same picture in a DXF document. # 1st image reference msp.add_image( insert=(2, 1), size_in_units=(6.4, 3.6), image_def=my_image_def, rotation=0 ) # 2nd image reference msp.add_image( insert=(4, 5), size_in_units=(3.2, 1.8), image_def=my_image_def, rotation=30 ) # Get existing image definitions from the OBJECTS section: image_defs = doc.objects.query("IMAGEDEF") doc.saveas("dxf_with_cat.dxf") ``` ### Tutorial for Underlay and UnderlayDefinition 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:** The underlay file is NOT embedded into the DXF file: ``` import ezdxf doc = ezdxf.new('AC1015') # underlay requires the DXF R2000 format or later my_underlay_def = doc.add_underlay_def(filename='my_underlay.pdf', name='1') # The (PDF)DEFINITION entity is like a block definition, it just defines the underlay # 'name' is misleading, because it defines the page/sheet to be displayed # PDF: name is the page number to display # DGN: name='default' ??? # DWF: ???? msp = doc.modelspace() # add first underlay msp.add_underlay(my_underlay_def, insert=(2, 1, 0), scale=0.05) # The (PDF)UNDERLAY entity is like the INSERT entity, it creates an underlay reference, # and there can be multiple references to the same underlay in a drawing. msp.add_underlay(my_underlay_def, insert=(4, 5, 0), scale=.5, rotation=30) # get existing underlay definitions, Important: UNDERLAYDEFs resides in the objects section pdf_defs = doc.objects.query('PDFDEFINITION') # get all pdf underlay defs in drawing doc.saveas("dxf_with_underlay.dxf") ``` ### Tutorial for 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: - • *add\_multileader\_mtext()* - • *add\_multileader\_block()* 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:** MULTILEADER support has flaws in many CAD applications except Autodesk products! **SEE ALSO:** - • *ezdxf.render.MultiLeaderBuilder* classes - • *ezdxf.entities.MultiLeader* class - • *ezdxf.entities.MLeaderStyle* class - • *ezdxf.tools.text.MTextEditor* class - • *MULTILEADER Internals* ### 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), ) ``` \[image\] 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)) ``` \[image\] 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)) ``` \[image\] 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)) ``` \[image\] 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*: - • left - • right - • top - • bottom 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*: - • by\_style - • top\_of\_top\_line - • middle\_of\_top\_line - • middle\_of\_text - • middle\_of\_bottom\_line - • bottom\_of\_bottom\_line - • bottom\_of\_bottom\_line\_underline (not recommended) - • bottom\_of\_top\_line\_underline (not recommended) - • bottom\_of\_top\_line - • bottom\_of\_top\_line\_underline\_all (not recommended) The vertical connection sides support following connection types, defined by the enum *ezdxf.render.VerticalConnection*: - • by\_style - • center - • center\_overline (not recommended) 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, ) ``` \[image\] **HINT:** As shown in the quick draw section using connection types including underlines or overlines do not render well in AutoCAD/BricsCAD because of the different text measurement of *matplotlib*, therefore it’s not recommended to use any of these connection types when creating MULTILEADERS by *ezdxf*. ### 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*. - • left - • center - • right 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) ``` \[image\] 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*: - • left - • right - • top - • bottom 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* - • center\_extents - • insertion\_point 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)], ) ``` \[image\] 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)], ) ``` \[image\] 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: - • none - • straight\_lines - • splines ### 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, ) ``` \[image\] 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) ``` \[image\] 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:** If you need paperspace layouts use DXF version R2000 or newer because the export of the page dimensions does not work for DXF R12! 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: | | | | --- | --- | | 0 | no rotation | | 1 | 90 degrees counter-clockwise | | 2 | upside-down | | 3 | 90 degrees clockwise | 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:** - • AutoCAD: *About Plotting* and *About Setting the Plot Scale* - • BricsCAD: *General Procedure for Printing* ### 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:** By writing this tutorial I noticed that changing the printer/plotter and the paper size does shift the layout content, because all paper sizes are defined without margins. Maybe it’s preferable to set all margins to zero. I added the helper method *page\_setup()* to the *Drawing* class and an example *simple\_page\_setup.py* how to use it. ### 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:** AutoCAD and BricsCAD **do not crash** if the layer names do not have layer table entries and the layer names are case insensitive as all table names. **SEE ALSO:** - • Basic concept of *Layers* - • *Layer* ### 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*. - 1\. get the *Layer* object - 2\. get the *LayerOverrides* object from the layer - 3\. override the properties of the VIEWPORT - 4\. commit changes ``` layer = doc.layers.get("Layer0") override = layer.get_vp_overrides() override.set_linetype(vp.dxf.handle, "DASHED") override.commit() ``` Supported property overrides: - • ACI color - • true color - • transparency - • linetype - • lineweight **SEE ALSO:** - • Basic concept of *Layers* - • Basic concept of *AutoCAD Color Index (ACI)* - • Basic concept of *True Color* - • Basic concept of *Transparency* - • Basic concept of *Linetypes* - • Basic concept of *Lineweights* - • *Layer* - • *LayerOverrides* ### 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:** The free online book *3D Math Primer for Graphics and Game Development* is a very good resource for learning vector math and other graphic related topics, it is easy to read for beginners and especially targeted to programmers. 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:** There is a new edition of this tutorial using UCS based transformation, which are available in *ezdxf* v0.11 and later: *Tutorial for UCS Based Transformations* This edition shows the **hard way** to accomplish the transformations by low level operations. ### Placing 2D Circle in 3D Space The colors of the system axis follow the AutoCAD standard: - • red is x-axis - • green is y-axis - • blue is z-axis ``` 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) ``` \[image: 3d poyline with UCS\] \[image\] ### 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') ``` \[image: text in ucs as top view\] \[image\] \[image: text in ucs as front view\] \[image\] **HINT:** For calculating OCS angles from an UCS, be aware that 2D entities, like TEXT or ARC, are placed parallel to the xy-plane of the UCS. ### 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}, ) ``` \[image: arc in ucs as top view\] \[image\] \[image: arc in ucs as front view\] \[image\] ### 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, }) ``` \[image\] \[image\] 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, }) ``` \[image\] \[image\] 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) ``` \[image\] \[image\] 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) ``` \[image: circle in ucs as side view\] \[image\] \[image: circle in ucs as front view\] \[image\] ### 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) ``` \[image: 3d poyline with UCS\] \[image\] ### 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) ``` \[image: text in ucs as top view\] \[image\] \[image: text in ucs as front view\] \[image\] ### 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) ``` \[image: arc in ucs as top view\] \[image\] \[image: arc in ucs as front view\] \[image\] ### 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) ``` \[image\] \[image\] 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) ``` \[image\] \[image\] 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) ``` \[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. 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) ``` \[image\] \[image\] ### 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:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. Text rendering is another problem, because *ezdxf* has no real rendering engine. Some font properties, like the real text width, which is only available to *ezdxf* if the *Matplotlib* package is installed and 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:** - • Graphical reference of many DIMVARS and some advanced information: *DIMSTYLE Table* - • Source code file *standards.py* shows how to create your own DIMSTYLES. - • The Script *dimension\_linear.py* shows examples for linear dimensions. ### 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: - • 1 drawing unit = 1m - • measurement text height = 0.25 (drawing scale = 1:100) - • the length factor **dimlfac** = 100, which creates a measurement text in cm. - • arrow is “ARCHTICK”, arrow size **dimasz** = 0.175 Every dimension style which does not exist will be replaced by the dimension style “Standard” at DXF export by **save()** or **saveas()** (e.g. dimension style setup was not initiated). The *base* point defines the location of the dimension line, *ezdxf* accepts any point on the dimension line, the point *p1* defines the start point of the first extension line, which also defines the first measurement point and the point *p2* defines the start point of the second extension line, which also defines the second measurement point. The return value *dim* is **not** a dimension entity, instead a *DimStyleOverride* object is returned, the dimension entity is stored as attribute **dim.dimension**. ### Vertical and Rotated Dimension Argument *angle* defines the angle of the dimension line in relation to the x-axis of the WCS or UCS, measurement is the distance between first and second measurement point in direction of *angle*. ``` # assignment to dim is not necessary, if no additional processing happens msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0), angle=-30).render() doc.saveas("dim_linear_rotated.dxf") ``` \[image\] 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") ``` \[image\] ### Dimension Style Override Many dimension styling options are defined by the associated *DimStyle* entity. But often you wanna change just a few settings without creating a new dimension style, therefore the DXF format has a protocol to store this changed settings in the dimension entity itself. This protocol is supported by *ezdxf* and every factory function which creates dimension entities supports the *override* argument. This *override* argument is a simple Python dictionary (e.g. **override = {"dimtad": 4}**, place measurement text below dimension line). The overriding protocol is managed by the *DimStyleOverride* object, which is returned by the most dimension factory functions. ### Placing Measurement Text The default location of the measurement text depends on various *DimStyle* parameters and is applied if no user defined text location is defined. ### Default Text Locations “Horizontal direction” means in direction of the dimension line and “vertical direction” means perpendicular to the dimension line direction. The **“horizontal”** location of the measurement text is defined by *dimjust*: | | | | --- | --- | | 0 | Center of dimension line | | 1 | Left side of the dimension line, near first extension line | | 2 | Right side of the dimension line, near second extension line | | 3 | Over first extension line | | 4 | Over second extension line | ``` msp.add_linear_dim( base=(3, 2), p1=(0, 0), p2=(3, 0), override={"dimjust": 1} ).render() ``` \[image\] The **“vertical”** location of the measurement text relative to the dimension line is defined by *dimtad*: | | | | --- | --- | | 0 | Center, it is possible to adjust the vertical location by *dimtvp* | | 1 | Above | | 2 | Outside, handled like *Above* by *ezdxf* | | 3 | JIS, handled like *Above* by *ezdxf* | | 4 | Below | ``` msp.add_linear_dim( base=(3, 2), p1=(0, 0), p2=(3, 0), override={"dimtad": 4} ).render() ``` \[image\] The distance between text and dimension line is defined by *dimgap*. The *DimStyleOverride* object has a method *set\_text\_align()* to set the default text location in an easy way, this is also the reason for the 2 step creation process of dimension entities: ``` dim = msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0)) dim.set_text_align(halign="left", valign="center") dim.render() ``` | | | | --- | --- | | halign | “left”, “right”, “center”, “above1”, “above2” | | valign | “above”, “center”, “below” | Run function **example\_for\_all\_text\_placings\_R2007()** in the example script *dimension\_linear.py* to create a DXF file with all text placings supported by *ezdxf*. ### User Defined Text Locations Beside the default location, it is possible to locate the measurement text freely. ### Location Relative to Origin The user defined text location can be set by the argument *location* in most dimension factory functions and always references the midpoint of the measurement text: ``` msp.add_linear_dim( base=(3, 2), p1=(3, 0), p2=(6, 0), location=(4, 4) ).render() ``` \[image\] 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() ``` \[image\] ### 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() ``` \[image\] ### Overriding Text Rotation All factory methods supporting the argument *text\_rotation* can override the measurement text rotation. The user defined rotation is relative to the render UCS x-axis (default is WCS). ### Measurement Text Formatting and Styling ### Text Properties | | | | --- | --- | | DIMVAR | Description | | **dimtxsty** | Specifies the text style of the dimension as *Textstyle* name. | | **dimtxt** | Text height in drawing units. | | **dimclrt** | Measurement text color as *AutoCAD Color Index (ACI)*. | ``` msp.add_linear_dim( base=(3, 2), p1=(3, 0), p2=(6, 0), override={ "dimtxsty": "Standard", "dimtxt": 0.35, "dimclrt": 1, } ).render() ``` \[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. | | | | --- | --- | | DIMVAR | Description | | **dimtfill** | Enables background filling if bigger than 0 | | **dimtfillclr** | Fill color as *AutoCAD Color Index (ACI)*, if **dimtfill** is 2 | | | | | --- | --- | | **dimtfill** | Description | | 0 | disabled | | 1 | canvas color | | 2 | color defined by **dimtfillclr** | ``` msp.add_linear_dim( base=(3, 2), p1=(3, 0), p2=(6, 0), override={ "dimtfill": 2, "dimtfillclr": 1, } ).render() ``` \[image\] ### Text Formatting - • **decimal places**: *dimdec* defines the number of decimal places displayed for the primary units of a dimension. (DXF R2000) - • **decimal point character**: *dimdsep* defines the decimal point as ASCII code, get the ASCII code by **ord('.')** - • **rounding**: *dimrnd*, rounds all dimensioning distances to the specified value, for instance, if **dimrnd** is set to 0.25, all distances round to the nearest 0.25 unit. If **dimrnd** is set to 1.0, all distances round to the nearest integer. For more information look at the documentation of the *ezdxf.math.xround()* function. - • **zero trimming**: *dimzin*, *ezdxf* supports only a subset of values: - • 4 to suppress leading zeros - • 8 to suppress trailing zeros - • 12 as the combination of both - • **measurement factor**: scale measurement by factor *dimlfac*, e.g. to get the dimensioning text in cm for a DXF file where 1 drawing unit represents 1m, set **dimlfac** to 100. - • **text template**: *dimpost*, “\<\>” represents the measurement text, e.g. “~\<\>cm” produces “~300cm” for measurement in previous example. To set this values the *ezdxf.entities.DimStyle.set\_text\_format()* and *ezdxf.entities.DimStyleOverride.set\_text\_format()* methods are very recommended. ### Overriding Measurement Text This feature allows overriding the real measurement text by a custom measurement text, the text is stored as string in the *Dimension* entity as attribute *text*. Special values of the **text** attribute are: one space “ “ to suppress the measurement text at all, an empty string “” or “\<\>” to display the real measurement. All factory functions have an explicit *text* argument, which always replaces the *text* value in the *dxfattribs* dict. ``` msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0), text=">1m").render() ``` \[image\] ### Dimension Line Properties The *dimension line color* is defined by the DIMVAR **dimclrd** as *AutoCAD Color Index (ACI)*, **dimclrd** and also defines the color of the arrows. The *linetype* is defined by **dimltype** and requires DXF R2007. The *lineweight* is defined by **dimlwd** and requires DXF R2000, see also the *lineweight* reference for valid values. The **dimdle** is the extension of the dimension line beyond the extension lines, this dimension line extension is not supported for all arrows. | | | | --- | --- | | DIMVAR | Description | | **dimclrd** | dimension line and arrows color as *AutoCAD Color Index (ACI)* | | **dimltype** | linetype of dimension line | | **dimlwd** | line weight of dimension line | | **dimdle** | extension of dimension line in drawing units | ``` msp.add_linear_dim( base=(3, 2), p1=(3, 0), p2=(6, 0), override={ "dimclrd": 1, # red "dimdle": 0.25, "dimltype": "DASHED2", "dimlwd": 35, # 0.35mm line weight } ).render() ``` \[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. | | | | --- | --- | | DIMVAR | Description | | **dimclre** | extension line color as *AutoCAD Color Index (ACI)* | | **dimltex1** | linetype of first extension line | | **dimltex2** | linetype of second extension line | | **dimlwe** | line weight of extension line | | **dimexe** | extension beyond dimension line in drawing units | | **dimexo** | offset of extension line from measurement point | | **dimfxlon** | set to 1 to enable fixed length extension line | | **dimfxl** | length of fixed length extension line in drawing units | | **dimse1** | suppress first extension line if 1 | | **dimse2** | suppress second extension line if 1 | ``` msp.add_linear_dim( base=(3, 2), p1=(3, 0), p2=(6, 0), override={ "dimclre": 1, # red "dimltex1": "DASHED2", "dimltex2": "CENTER2", "dimlwe": 35, # 0.35mm line weight "dimexe": 0.3, # length above dimension line "dimexo": 0.1, # offset from measurement point } ).render() ``` \[image\] *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() ``` \[image\] *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() ``` \[image\] *DimStyleOverride()* methods: ``` dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) dim.set_arrows(blk=ezdxf.ARROWS.closed_filled) dim.set_extline1(disable=True) dim.set_extline2(disable=True) dim.render() ``` ### Arrows “Arrows” mark then beginning and the end of a dimension line, and most of them do not look like arrows. DXF distinguish between the simple tick (a slanted line) and arrows as blocks. To use a simple tick as “arrow” set *dimtsz* to a value greater than 0, this also disables arrow blocks as side effect: ``` dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) dim.set_tick(size=0.25) dim.render() ``` *Ezdxf* uses the “ARCHTICK” block at double size to render the tick (AutoCAD and BricsCad just draw a simple line), so there is no advantage of using the tick instead of an arrow. Using arrows: ``` dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) dim.set_arrow(blk="OPEN_30", size=0.25) dim.render() ``` | | | | --- | --- | | DIMVAR | Description | | **dimtsz** | tick size in drawing units, set to 0 to use arrows | | **dimblk** | set both arrow block names at once | | **dimblk1** | first arrow block name | | **dimblk2** | second arrow block name | | **dimasz** | arrow size in drawing units | ``` msp.add_linear_dim( base=(3, 2), p1=(3, 0), p2=(6, 0), override={ "dimtsz": 0, # set tick size to 0 to enable arrow usage "dimasz": 0.25, # arrow size in drawing units "dimblk": "OPEN_30", # arrow block name } ).render() ``` The dimension line extension (**dimdle**) works only for a few arrow blocks and the simple tick: - • “ARCHTICK” - • “OBLIQUE” - • “NONE” - • “SMALL” - • “DOTSMALL” - • “INTEGRAL” ### Arrow Shapes \[image\] ### Arrow Names The arrow names are stored as attributes in the **ezdxf.ARROWS** object. | | | | --- | --- | | closed\_filled | “” (empty string) | | dot | “DOT” | | dot\_small | “DOTSMALL” | | dot\_blank | “DOTBLANK” | | origin\_indicator | “ORIGIN” | | origin\_indicator\_2 | “ORIGIN2” | | open | “OPEN” | | right\_angle | “OPEN90” | | open\_30 | “OPEN30” | | closed | “CLOSED” | | dot\_smallblank | “SMALL” | | none | “NONE” | | oblique | “OBLIQUE” | | box\_filled | “BOXFILLED” | | box | “BOXBLANK” | | closed\_blank | “CLOSEDBLANK” | | datum\_triangle\_filled | “DATUMFILLED” | | datum\_triangle | “DATUMBLANK” | | integral | “INTEGRAL” | | architectural\_tick | “ARCHTICK” | | ez\_arrow | “EZ\_ARROW” | | ez\_arrow\_blank | “EZ\_ARROW\_BLANK” | | ez\_arrow\_filled | “EZ\_ARROW\_FILLED” | ### Tolerances and Limits The tolerances and limits features are implemented by using inline codes for the *MText* entity, therefore DXF R2000 is required. It is not possible to use both tolerances and limits at the same time. ### Tolerances Geometrical tolerances are shown as additional text appended to the measurement text. It is recommend to use *set\_tolerance()* method in *DimStyleOverride* or *DimStyle*. The attribute **dimtp** defines the upper tolerance value, **dimtm** defines the lower tolerance value if present, else the lower tolerance value is the same as the upper tolerance value. Tolerance values are shown as given! Same upper and lower tolerance value: ``` dim = msp.add_linear_dim(base=(0, 3), p1=(3, 0), p2=(6.5, 0)) dim.set_tolerance(.1, hfactor=.4, align="top", dec=2) dim.render() ``` \[image\] 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() ``` \[image\] The attribute **dimtfac** specifies a scale factor for the text height of limits and tolerance values relative to the dimension text height, as set by **dimtxt**. For example, if **dimtfac** is set to 1.0, the text height of fractions and tolerances is the same height as the dimension text. If **dimtxt** is set to 0.75, the text height of limits and tolerances is three-quarters the size of dimension text. Vertical justification for tolerances is specified by **dimtolj**: | | | | --- | --- | | **dimtolj** | Description | | 0 | Align with bottom line of dimension text | | 1 | Align vertical centered to dimension text | | 2 | Align with top line of dimension text | | | | | --- | --- | | DIMVAR | Description | | **dimtol** | set to 1 to enable tolerances | | **dimtp** | set the maximum (or upper) tolerance limit for dimension text | | **dimtm** | set the minimum (or lower) tolerance limit for dimension text | | **dimtfac** | specifies a scale factor for the text height of limits and tolerance values relative to the dimension text height, as set by **dimtxt**. | | **dimtzin** | 4 to suppress leading zeros, 8 to suppress trailing zeros or 12 to suppress both, like **dimzin** for dimension text, see also *Text Formatting* | | **dimtolj** | set the vertical justification for tolerance values relative to the nominal dimension text. | | **dimtdec** | set the number of decimal places to display in tolerance values | ### Limits The geometrical limits are shown as upper and lower measurement limit and replaces the usual measurement text. It is recommend to use *set\_limits()* method in *DimStyleOverride* or *DimStyle*. For limits the tolerance values are drawing units scaled by measurement factor **dimlfac**, the upper limit is scaled measurement value + **dimtp** and the lower limit is scaled measurement value - **dimtm**. The attributes **dimtfac**, **dimtzin** and **dimtdec** have the same meaning for limits as for tolerances. ``` dim = msp.add_linear_dim(base=(0, 3), p1=(3, 0), p2=(6.5, 0)) dim.set_limits(upper=.1, lower=.15, hfactor=.4, dec=2) dim.render() ``` \[image\] | | | | --- | --- | | DIMVAR | Description | | **dimlim** | set to 1 to enable limits | ### Alternative Units Alternative units are not supported. ### Tutorial for Radius Dimensions Please read the *Tutorial for Linear Dimensions* before, if you haven’t. **NOTE:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. ``` 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: - • 1 drawing unit = 1m - • scale 1:100 - • the length factor **dimlfac** = 100, which creates a measurement text in cm. - • uses a closed filled arrow, arrow size **dimasz** = 0.25 **NOTE:** Not all possibles features of DIMSTYLE are supported by the *ezdxf* rendering procedure and especially for the radial dimension there are less features implemented than for the linear dimension because of the lack of good documentation. **SEE ALSO:** - • Graphical reference of many DIMVARS and some advanced information: *DIMSTYLE Table* - • Source code file *standards.py* shows how to create your own DIMSTYLES. - • The Script *dimension\_radius.py* shows examples for radius dimensions. ### Default Text Locations Outside Advanced “EZ\_RADIUS” settings for placing the text outside of the circle: | | | | --- | --- | | tmove | 1 = add a leader when dimension text is moved, this is the best setting for text outside to preserve the appearance of the DIMENSION entity, if editing afterwards in a CAD application. | | dimtad | 1 = place the text vertical above the dimension line | ``` 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} ) ``` \[image\] ### 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: - • 1 drawing unit = 1m - • scale 1:100, length\_factor is 100 which creates - • the length factor **dimlfac** = 100, which creates a measurement text in cm. - • uses a closed filled arrow, arrow size **dimasz** = 0.25 Advanced “EZ\_RADIUS\_INSIDE” settings to place (force) the text inside of the circle: | | | | --- | --- | | tmove | 0 = moves the dimension line with dimension text, this is the best setting for text inside to preserve the appearance of the DIMENSION entity, if editing afterwards in a CAD application. | | dimtix | 1 = force text inside | | dimatfit | 0 = force text inside, required by BricsCAD and AutoCAD | | dimtad | 0 = center text vertical, BricsCAD and AutoCAD always create a vertical centered text, *ezdxf* let you choose the vertical placement (above, below, center), but editing the DIMENSION in BricsCAD or AutoCAD will reset text to center placement. | ``` dim = msp.add_radius_dim( center=(0, 0), radius=2.5, angle=45, dimstyle="EZ_RADIUS_INSIDE" ) ``` \[image\] \[image\] 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} ) ``` \[image\] ### 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" ) ``` \[image\] 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} ) ``` \[image\] User defined location inside of the circle: ``` dim = msp.add_radius_dim( center=(0, 0), radius=2.5, location=(1, 1), dimstyle="EZ_RADIUS" ) ``` \[image\] \[image\] 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}, ) ``` \[image\] ### Center Mark/Lines Center mark/lines are controlled by *dimcen*, default value is 0 for predefined dimstyles “EZ\_RADIUS” and “EZ\_RADIUS\_INSIDE”: | | | | --- | --- | | 0 | Center mark is off | | \>0 | Create center mark of given size | | \<0 | Create center lines | ``` 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:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. 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: - • 1 drawing unit = 1m - • scale 1:100 - • the length factor **dimlfac** = 100, which creates a measurement text in cm. - • uses a closed filled arrow, arrow size **dimasz** = 0.25 **NOTE:** Not all possibles features of DIMSTYLE are supported by the *ezdxf* rendering procedure and especially for the diameter dimension there are less features implemented than for the linear dimension because of the lack of good documentation. **SEE ALSO:** - • Graphical reference of many DIMVARS and some advanced information: *DIMSTYLE Table* - • Source code file *standards.py* shows how to create your own DIMSTYLES. - • The Script *dimension\_diameter.py* shows examples for radius dimensions. ### Default Text Locations Outside “EZ\_RADIUS” default settings for to place text outside: | | | | --- | --- | | tmove | 1 = add a leader when dimension text is moved, this is the best setting for text outside to preserve the appearance of the DIMENSION entity, if editing afterwards in a CAD application. | | dimtad | 1 = place the text vertical above the dimension line | ``` 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} ) ``` \[image\] ### 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: - • 1 drawing unit = 1m - • scale 1:100, length\_factor is 100 which creates - • the length factor **dimlfac** = 100, which creates a measurement text in cm. - • uses a closed filled arrow, arrow size **dimasz** = 0.25 Advanced “EZ\_RADIUS\_INSIDE” settings to place (force) the text inside of the circle: | | | | --- | --- | | tmove | 0 = moves the dimension line with dimension text, this is the best setting for text inside to preserve the appearance of the DIMENSION entity, if editing afterwards in a CAD application. | | dimtix | 1 = force text inside | | dimatfit | 0 = force text inside, required by BricsCAD and AutoCAD | | dimtad | 0 = center text vertical, BricsCAD and AutoCAD always create a vertical centered text, *ezdxf* let you choose the vertical placement (above, below, center), but editing the DIMENSION in BricsCAD or AutoCAD will reset text to center placement. | ``` dim = msp.add_diameter_dim( center=(0, 0), radius=2.5, angle=45, dimstyle="EZ_RADIUS_INSIDE" ) ``` \[image\] 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} ) ``` \[image\] ### 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" ) ``` \[image\] 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} ) ``` \[image\] User defined location inside of the circle: ``` dim = msp.add_diameter_dim( center=(0, 0), radius=2.5, location=(1, 1), dimstyle="EZ_RADIUS" ) ``` \[image\] 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}, ) ``` \[image\] ### 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:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. ### 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: - • angle unit is decimal degrees, **dimaunit** = 0 - • measurement text height = 0.25 (drawing scale = 1:100) - • measurement text location is above the dimension line - • closed filled arrow and arrow size **dimasz** = 0.25 - • **dimazin** = 2, suppresses trailing zeros (e.g. 12.5000 becomes 12.5) 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() ``` \[image\] ### 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() ``` \[image\] ### 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:** Not all possibles features of DIMSTYLE are supported by the *ezdxf* rendering procedure and especially for the angular dimension there are less features implemented than for the linear dimension because of the lack of good documentation. **SEE ALSO:** - • Graphical reference of many DIMVARS and some advanced information: *DIMSTYLE Table* - • Source code file *standards.py* shows how to create your own DIMSTYLES. - • The Script *dimension\_angular.py* shows examples for angular dimensions. ### 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*: | | | | --- | --- | | 0 | Center, it is possible to adjust the vertical location by *dimtvp* | | 1 | Above | | 2 | Outside, handled like *Above* by *ezdxf* | | 3 | JIS, handled like *Above* by *ezdxf* | | 4 | Below | ``` msp.add_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() ``` \[image\] 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() ``` \[image\] 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() ``` \[image\] ### 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() ``` \[image\] ### 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() ``` \[image\] 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() ``` \[image\] ### 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() ``` \[image\] ### Angular Units Angular units are set by *dimaunit*: | | | | --- | --- | | 0 | Decimal degrees | | 1 | Degrees/Minutes/Seconds, **dimadec** controls the shown precision dimadec=0: 30° dimadec=2: 30°35’ dimadec=4: 30°35’25” dimadec=7: 30°35’25.15” | | 2 | Grad | | 3 | Radians | ``` 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:** *Ezdxf* does not render the arc dimension like CAD applications and does not consider all DIMSTYLE variables, so the rendering results are **very** different from CAD applications. ### 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: - • angle unit is decimal degrees, **dimaunit** = 0 - • measurement text height = 0.25 (drawing scale = 1:100) - • measurement text location is above the dimension line - • closed filled arrow and arrow size **dimasz** = 0.25 - • **dimzin** = 2, suppresses trailing zeros (e.g. 12.5000 becomes 12.5) - • **dimarcsym** = 2, disables the arc symbol, 0 renders only an open round bracket “(” in front of the text and 1 for arc symbol above the text is not supported, renders like disabled 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() ``` \[image\] ### 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:** Not all possibles features of DIMSTYLE are supported by the *ezdxf* rendering procedure and especially for the arc dimension there are less features implemented than for the linear dimension because of the lack of good documentation. If the arc symbol is enabled (**dimarcsym** = 0) only an open round bracket “(” is rendered in front of the measurement text! **SEE ALSO:** - • Graphical reference of many DIMVARS and some advanced information: *DIMSTYLE Table* - • Source code file *standards.py* shows how to create your own DIMSTYLES. - • The Script *dimension\_arc.py* shows examples for angular dimensions. ### 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:** *Ezdxf* does not consider all DIMSTYLE variables, so the rendering results are different from CAD applications. ### 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") ``` \[image\] ### 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:** - • Graphical reference of many DIMVARS and some advanced information: *DIMSTYLE Table* - • Source code file *standards.py* shows how to create your own DIMSTYLES. - • The Script *dimension\_ordinate.py* shows examples for angular dimensions. ### 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:** TO ALL BEGINNERS! If you are just learning to work with geospatial data, using DXF files is not the way to go! DXF is not the first choice for storing data for spatial data analysts. If you run into problems I cannot help you as I am just learning myself. 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 custom data 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 - • *Autodesk Developer Documentation* - • *AfraLISP* - • *Lee Mac Programming* **WARNING:** I have no experience with AutoLISP so far and I created this scripts for AutoLISP while writing this tutorial. There may be better ways to accomplish these tasks, and feedback on this is very welcome. Everything is tested with BricsCAD and should also work with the full version of AutoCAD. ### 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 Code | Description | | 1000 | Strings up to 255 bytes long | | 1001 | (fixed) Registered application name up to 31 bytes long | | 1002 | (fixed) An extended data control string **'{'** or **'}'** | | 1004 | Binary data | | 1005 | Database Handle of entities in the drawing database | | 1010 | 3D point, in the order X, Y, Z that will not be modified at any transformation of the entity | | 1011 | A WCS point that is moved, scaled, rotated and mirrored along with the entity | | 1012 | A WCS displacement that is scaled, rotated and mirrored along with the entity, but not moved | | 1013 | A WCS direction that is rotated and mirrored along with the entity but not moved and scaled. | | 1040 | A real value | | 1041 | Distance, a real value that is scaled along with the entity | | 1042 | Scale Factor, a real value that is scaled along with the entity | | 1070 | A 16-bit integer (signed or unsigned) | | 1071 | A 32-bit signed (long) integer | 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:** - • *AfraLISP XDATA tutorial* - • *Extended Data (XDATA)* Reference ### 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: | | | | --- | --- | | 1001 | strings (max. 255 chars) | | 1040 | floats | | 1071 | 32-bit ints | | 1010 | Vec3 | 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:** - • *XDataUserList* class - • *XDataUserDict* class ### 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*. - 1\. Get or create the XDICT for an entity: ``` # 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:** - • *AfraLISP Dictionaries and XRecords* Tutorial - • *Extension Dictionary* Reference - • DXF *Dictionary* Reference - • *DictionaryVar* Reference ### 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. | | | | --- | --- | | 1 | strings (max. 2049 chars) | | 2 | structure tags as strings like **"{"** and **"}"** | | 10 | points and vectors | | 40 | floats | | 90 | integers | | 330 | handles | 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:** - • *AfraLISP Dictionaries and XRecords* Tutorial - • *AfraLISP Reactors Tutorial* - • *XRecord* Reference - • helper functions: *ezdxf.lldxf.types.dxftag()* and *ezdxf.lldxf.types.tuples\_to\_tags()* ### XRecord Helper Classes The *UserRecord* and *BinaryRecord* are helper classes to manage XRECORD content in a simple way. The *UserRecord* manages the data as plain Python types: **dict**, **list**, **int**, **float**, **str** and the *ezdxf* types *Vec2* and *Vec3*. The top level type for the **UserRecord.data** attribute has to be a **list**. The *BinaryRecord* stores arbitrary binary data as *BLOB*. These helper classes uses fixed group codes to manage the data in XRECORD, you have no choice to change them. Additional required imports for these examples: ``` from pprint import pprint import ezdxf from ezdxf.math import Vec3 from ezdxf.urecord import UserRecord, BinaryRecord from ezdxf.entities import XRecord import zlib ``` Example 1: Store entity specific data in the *Extension Dictionary*: ``` line = msp.add_line((0, 0), (1, 0)) xdict = line.new_extension_dict() xrecord = xdict.add_xrecord("MyData") with UserRecord(xrecord) as user_record: user_record.data = [ # top level has to be a list! "MyString", 4711, 3.1415, Vec3(1, 2, 3), { "MyIntList": [1, 2, 3], "MyFloatList": [4.5, 5.6, 7.8], }, ] ``` Example 1: Get entity specific data back from the *Extension Dictionary*: ``` if line.has_extension_dict: xdict = line.get_extension_dict() xrecord = xdict.get("MyData") if isinstance(xrecord, XRecord): user_record = UserRecord(xrecord) pprint(user_record.data) ``` If you modify the content of **UserRecord.data** without using the context manager, you have to call *commit()* by yourself, to store the modified data back into the XRECORD. Example 2: Store arbitrary data in DICTIONARY objects. The XRECORD is stored in the named DICTIONARY, called **rootdict** in *ezdxf*. This DICTIONARY is the root entity for the tree-like data structure stored in the OBJECTS section, see also the documentation of the *ezdxf.sections.objects* module. ``` # Get the existing DICTIONARY object or create a new DICTIONARY object: my_dict = doc.objects.rootdict.get_required_dict("MyDict") # Create a new XRECORD object, the DICTIONARY object is the owner of this # new XRECORD: xrecord = my_dict.add_xrecord("MyData") # This example creates the user record without the context manager. user_record = UserRecord(xrecord) # Store user data: user_record.data = [ "Just another user record", 4711, 3.1415, ] # Store user data in associated XRECORD: user_record.commit() ``` Example 2: Get user data back from the DICTIONARY object ``` my_dict = doc.rootdict.get_required_dict("MyDict") entity = my_dict["MyData"] if isinstance(entity, XRecord): user_record = UserRecord(entity) pprint(user_record.data) ``` Example 3: Store arbitrary binary data ``` my_dict = doc.rootdict.get_required_dict("MyDict") xrecord = my_dict.add_xrecord("MyBinaryData") with BinaryRecord(xrecord) as binary_record: # The content is stored as hex strings (e.g. ABBAFEFE...) in one or more # group code 310 tags. # A preceding group code 160 tag stores the data size in bytes. data = b"Store any binary data, even line breaks\r\n" * 20 # compress data if required binary_record.data = zlib.compress(data, level=9) ``` Example 3: Get binary data back from the DICTIONARY object ``` entity = my_dict["MyBinaryData"] if isinstance(entity, XRecord): binary_record = BinaryRecord(entity) print("\ncompressed data:") pprint(binary_record.data) print("\nuncompressed data:") pprint(zlib.decompress(binary_record.data)) ``` **HINT:** Don’t be fooled, the ability to save any binary data such as images, office documents, etc. in the DXF file doesn’t impress AutoCAD, it simply ignores this data, this data only has a meaning for your application! **SEE ALSO:** - • *urecord* module - • *UserRecord* class - • *BinaryRecord* class ### AppData *Application-Defined Data (AppData)* was introduced in DXF R13/14 and is used by AutoCAD internally to store the handle to the *Extension Dictionary* and the *Reactors* in DXF entities. *Ezdxf* supports these kind of data storage for any AppID and the data is preserved by AutoCAD and BricsCAD, but I haven’t found a way to access this data by AutoLISP or even the SDK. So I don’t recommend this feature to store application defined data, because *Extended Data (XDATA)* and the *Extension Dictionary* are well documented and safe ways to attach custom data to entities. ``` # register your appid APPID = "YOUR_UNIQUE_ID" doc.appids.add(APPID) # create a DXF entity line = msp.add_line((0, 0), (1, 0)) # setting the data line.set_app_data(APPID, [(300, "custom text"), (370, 4711), (460, 3.141592)]) # getting the data if line.has_app_data(APPID): tags = line.get_app_data(APPID) print(f"{str(line)} has {len(tags)} tags of AppData for AppID {APPID!r}") for tag in tags: print(tag) ``` Printed output: ``` LINE(#30) has 3 tags of AppData for AppID 'YOUR_UNIQUE_ID' (300, 'custom text') (370, 4711) (460, 3.141592) ``` ### Tutorial for External References - • *Introduction* - • *Supported Entities* - • *Environment Setup* - • *Attach a DXF File* - • *Attach a DWG File* - • *Detach an XREF* - • *Embed an XREF* - • *Load Modelspace* - • *Load Paperspace* - • *Write Block* - • *Conflict Policies* - • *ConflictPolicy.KEEP* - • *ConflictPolicy.XREF\_PREFIX* - • *ConflictPolicy.NUM\_PREFIX* - • *Load Table Resources* ### Introduction This tutorial uses the *ezdxf.xref* module to work with external references (XREF). Attached XREFs are links to the modelspace of a specified drawing file. Changes made to the referenced drawing are automatically reflected in the current drawing when it’s opened or if the XREF is reloaded. **IMPORTANT:** **AutoCAD can only display DWG files as attached XREFs.** Any DXF file attached as an XREF to a DXF document must be converted to DWG in order to be viewed in AutoCAD. Fortunately, other CAD applications are more cooperative, BricsCAD has no problem displaying DXF files as XREFs. The *drawing* add-on included in *ezdxf* **does not display external** **references at all!** There are some example files included in the *examples/xref* folder of the repository: - • attach\_dxf\_dwg\_xref.py - • detach\_block\_as\_xref.py - • embed\_dxf\_dwg\_xref.py - • load\_table\_resources.py ### Supported Entities All operations which move entities between layouts and XREFs copy these entities, therefore only entities which are copyable can be transferred. The following entities are not copyable: - • All entities which are not documented by the DXF reference. - • ACAD\_TABLE - • ACAD\_PROXY\_ENTITY - • OLE2FRAME - • ACIS based entities: BODY, 3DSOLID, REGION, … - • Custom entities from applications on top of AutoCAD like Map 3D, Civil 3D or Architecture. The vertical integration stack is not documented by the DXF reference. Unsupported entities are ignored and do not raise exceptions. ### Environment Setup Required imports to follow this tutorial: ``` import ezdxf from ezdxf.addons import odafc from ezdxf.document import Drawing from ezdxf import xref, units, colors from ezdxf.render import forms DXFVERSION = "R2013" ``` Function to create a simple DXF file as XREF, the insertion point of the XREF is set to (5, 5): ``` def make_dxf_xref_document(name: str) -> Drawing: ref_doc = ezdxf.new(DXFVERSION, units=units.M) ref_doc.layers.add("GEAR", color=colors.YELLOW) msp = ref_doc.modelspace() gear = forms.gear( 16, top_width=0.25, bottom_width=0.75, height=0.5, outside_radius=2.5 ) msp.add_lwpolyline( forms.translate(gear, (5, 5)), close=True, dxfattribs={"layer": "GEAR"} ) ref_doc.header["$INSBASE"] = (5, 5, 0) ref_doc.saveas(name) return ref_doc ``` Create the DXF file: ``` make_dxf_xref_document("xref.dxf") ``` The XREF looks like this: \[image\] ### Attach a DXF File Create a host document to which the XREF will be attached: ``` host_doc = ezdxf.new(DXFVERSION, units=units.M) ``` Attach the XREF by the *ezdxf.xref.attach()* function and save the host DXF file: ``` xref.attach(host_doc, block_name="dxf_xref", insert=(0, 0), filename="attached_xref.dxf") host_doc.set_modelspace_vport(height=10, center=(0, 0)) host_doc.saveas("attach_host_dxf.dxf") ``` The **attach()** function is meant to simply attach an XREF once without any overhead, therefore the **attach()** function creates the required block definition automatically and raises an **XrefDefinitionError** exception if the block definition already exist. To attach additional XREF references use the method *add\_blockref()*: ``` msp.add_blockref("dxf_xref", insert=another_location) ``` The attached DXF file in BricsCAD: \[image\] **IMPORTANT:** AutoCAD can not display DXF files as attached XREFs. ### Attach a DWG File Export the DXF file as DWG by the *odafc* add-on: ``` # It's not required to save the DXF file! doc = make_dxf_xref_document("attached_xref.dxf") try: odafc.export_dwg(doc, "attached_xref.dwg", replace=True) except odafc.ODAFCError as e: print(str(e)) ``` Attach the DWG file by the *ezdxf.xref.attach()* function and save the host DXF file: ``` host_doc = ezdxf.new(DXFVERSION, units=units.M) xref.attach(host_doc, block_name="dwg_xref", filename="attached_xref.dwg", insert=(0, 0)) host_doc.set_modelspace_vport(height=10, center=(0, 0)) host_doc.saveas("attached_dwg.dxf") ``` Attached DWG file in Autodesk DWG TrueView 2023: \[image\] ### Detach an XREF The *detach()* function writes the content of a block definition into the modelspace of a new DXF document and convert the block to an external reference (XREF). The new DXF document has to be written/exported by the caller. The function does not create any block references. These references should already exist and do not need to be changed since references to blocks and XREFs are the same. ``` host_doc = ezdxf.new() make_block(host_doc, "GEAR") block_layout = host_doc.blocks.get("GEAR") detached_block_doc = xref.detach(block_layout, xref_filename="detached_gear.dxf") detached_block_doc.saveas("detached_gear.dxf") host_doc.set_modelspace_vport(height=10, center=(0, 0)) host_doc.saveas("detach_host_dxf_xref.dxf") ``` **IMPORTANT:** Save the host document after detaching the block! Detaching a block definition modifies the host document. The **detach()** function returns a **Drawing** instance, so it’s possible to convert the DXF document to DWG by the *odafc* add-on if necessary (e.g. for Autodesk products). It’s important that the argument **xref\_filename** match the filename of the exported DWG file: ``` host_doc = ezdxf.new() make_block(host_doc, "GEAR") block_layout = host_doc.blocks.get("GEAR") detached_block_doc = xref.detach(block_layout, xref_filename="detached_gear.dwg") try: odafc.export_dwg(detached_block_doc, "detached_gear.dwg", replace=True) except odafc.ODAFCError as e: print(str(e)) host_doc.set_modelspace_vport(height=10, center=(0, 0)) host_doc.saveas("detach_host_dwg_xref.dxf") ``` It’s recommended to clean up the entity database of the host document afterwards: ``` host_doc.entitydb.purge() ``` For understanding, this is the **make\_block()** function: ``` def make_block(doc: Drawing, name: str) -> None: blk = doc.blocks.new(name, base_point=(5, 5, 0)) doc.layers.add("GEAR", color=colors.YELLOW) gear = forms.gear( 16, top_width=0.25, bottom_width=0.75, height=0.5, outside_radius=2.5 ) blk.add_lwpolyline( forms.translate(gear, (5, 5)), close=True, dxfattribs={"layer": "GEAR"} ) doc.modelspace().add_blockref(name, (0, 0)) ``` ### Embed an XREF The **embed()** function loads the content of the XREF into the block definition, this is the reverse operation of detaching an XREF. For loading the content of DWG files is a loading function required, which loads the DWG file as **Drawing** document. The *odafc* add-on module provides such a function: *readfile()*. This example embeds the XREF “attached\_xref.dwg” of the first example as content of the block definition “GEAR”, the “attach\_host\_dwg.dxf” file is the host DXF document: ``` import ezdxf from ezdxf.addons import odafc doc = ezdxf.readfile("attach_host_dwg.dxf") gear_xref = doc.blocks.get("GEAR") try: xref.embed(gear_xref, load_fn=odafc.readfile) except FileNotFoundError as e: print(str(e)) ``` The default loading function for DXF files is the *ezdxf.readfile()* function and doesn’t have to be specified. For the loading function from the *recover* module use a lambda function: ``` import ezdxf from ezdxf import recover doc = ezdxf.readfile("attach_host_dxf.dxf") gear_xref = doc.blocks.get("GEAR") try: xref.embed(gear_xref, load_fn=lambda f: recover.readfile(f)[0]) except FileNotFoundError as e: print(str(e)) ``` ### Load Modelspace The *ezdxf.xref.load\_modelspace()* function loads the content of the modelspace of the source document into a layout of the target document, the modelspace of the target document is the default target layout. **HINT:** Use this function to combine multiple existing DXF files. If the goal is just to add new entities to an existing document, rather load the source document as a template by *ezdxf.readfile()*, add your content and save the document as a new DXF file with the **saveas()** method. Merge multiple DXF files: ``` import ezdxf from ezdxf import colors, transform, xref from ezdxf.math import Matrix44 from ezdxf.render import forms def make_gear(name: str) -> None: doc = ezdxf.new() doc.layers.add("GEAR", color=colors.YELLOW) msp = doc.modelspace() gear = forms.gear( 16, top_width=0.25, bottom_width=0.75, height=0.5, outside_radius=2.5 ) msp.add_lwpolyline(gear, close=True, dxfattribs={"layer": "GEAR"}) doc.saveas(name) make_gear("gear.dxf") merged_doc = ezdxf.new() for index in range(3): sdoc = ezdxf.readfile("gear.dxf") # this could be different DXF files transform.inplace(sdoc.modelspace(), Matrix44.translate(index * 10, 0, 0)) xref.load_modelspace(sdoc, merged_doc) merged_doc.saveas("merged.dxf") ``` \[image\] ### Load Paperspace The function *ezdxf.xref.load\_paperspace()* loads a paperspace layout as a new paperspace layout into the target document. To be clear this function loads **only** the content of the paperspace layout, the content of the modelspace isn’t loaded, therefore the loaded VIEWPORT entities show the content of the target modelspace. ### Write Block The function *ezdxf.xref.write\_block()* writes the given entities into the modelspace of a new DXF document, this document can be, but doesn’t have to be used as an external referenced block. ### Conflict Policies Resources are definitions of layers, linetypes, text-, dimension-, mline- and mleader styles, materials and blocks. A resource conflict occurs when the source and target documents contain elements such as layers, linetypes, text styles and so on that share the same name. Many of the functions shown above support an argument to define the *ezdxf.xref.ConflictPolicy*, that gives you the choice how to handle resource name conflicts. ### ConflictPolicy.KEEP Keeps the existing resource name of the target document and ignore the resource from the source document. The loaded entities from the source document use the resources defined in the target document and may alter their visual appearance, when the resources are different. ### ConflictPolicy.XREF\_PREFIX This policy handles the resource import like CAD applications by **always** renaming the loaded resources to *\$0$\*, where *xref* is the name of source document, the *$0$* part is a number to create a unique resource name and *\* is the name of the resource itself. **IMPORTANT:** This policy ALWAYS renames the resource, even if the loaded resource doesn’t have a conflict in the target document. ### ConflictPolicy.NUM\_PREFIX This policy renames the loaded resources to *$0$\* only if the resource *\* already exists. The *$0$* prefix is a number to create a unique resource name and *\* is the name of the resource itself. **IMPORTANT:** This policy renames the resource ONLY when the loaded resource has a conflict in the target document. ### Load Table Resources Resources are definitions of layers, linetypes, text-, dimension-, mline- and mleader styles, materials and blocks. The **Loader** class is the low level tool to build a loading operation from simple loading commands. Study the *source code* of the **xref** module, most of loading commands used above are build upon the **Loader** class. This example shows how to import layer, linetype, text- and dimension style definitions: ``` import ezdxf from ezdxf import xref sdoc = ezdxf.new(setup=True) tdoc = ezdxf.new() # The default conflict policy is ConflictPolicy.KEEP loader = xref.Loader(sdoc, tdoc) # Load all layers: loader.load_layers([layer.dxf.name for layer in sdoc.layers]) # Load specific linetypes: loader.load_linetypes(["CENTER", "DASHED", "DASHDOT"]) # Load specific text style: loader.load_text_styles(["OpenSans", "LiberationMono"]) # Load all DIMENSION styles, this command loads also the dependent text styles: loader.load_dim_styles([dimstyle.dxf.name for dimstyle in sdoc.dimstyles]) # execute all loading commands: loader.execute() tdoc.saveas("target.dxf") ``` **NOTE:** Loading a layer does not load the entities which do reference this layer, a layer is not an entity container, it’s just an DXF attribute, see also Basic Concepts: *Layers*. ### Tutorial for Image Export - • *Introduction* - • *Common Basics* - • *Frontend Configuration* - • *Page Layout* - • *Autodetect Page Size* - • *Scaling Content* - • *Limit Page Size* - • *SVG Export* - • *PDF Export* - • *PNG Export* - • *PLT/HPGL2 Export* - • *DXF Export* - • *Recorder Backend* ### Introduction This tutorial shows how to export DXF content of the modelspace or a paperspace as images by the *drawing* add-on. The tutorial covers the new added backends in *ezdxf* version 1.1: - • *ezdxf.addons.drawing.svg.SVGBackend* class for SVG export - • *ezdxf.addons.drawing.pymupdf.PyMuPdfBackend* class for PDF and PNG export - • *ezdxf.addons.drawing.hpgl2.PlotterBackend* class for PLT/HPGL2 export - • *ezdxf.addons.drawing.dxf.DXFBackend* class for flattened DXF export The tutorial **does not cover** the **MatplotlibBackend** and *PyQtBackend*, for information about these backends see: - • Howtos for the *Drawing Add-on* - • FAQs at github: *https://github.com/mozman/ezdxf/discussions/550* ### Common Basics The rendering process is divided into multiple steps. The frontend resolves the DXF properties and breaks down complex DXF entities into simple drawing primitives which are send to the backend that renders the output format. ``` import ezdxf from ezdxf.addons.drawing import Frontend, RenderContext, svg, layout def example_doc(): doc = ezdxf.new() msp = doc.modelspace() x0, y0, x1, y1 = 0, 0, 10, 10 start = (x0, y0) end = (x0 + 1, y0) for color in range(1, 6): msp.add_lwpolyline( [start, (x0, y1), (x1, y1), (x1, y0), end], dxfattribs={"color": color} ) x0 += 1 x1 -= 1 y0 += 1 y1 -= 1 start = end end = (x0 + 1, y0) return doc def export(doc): msp = doc.modelspace() # 1. create the render context context = RenderContext(doc) # 2. create the backend backend = svg.SVGBackend() # 3. create the frontend frontend = Frontend(context, backend) # 4. draw the modelspace frontend.draw_layout(msp) # 5. create an A4 page layout, not required for all backends page = layout.Page(210, 297, layout.Units.mm, margins=layout.Margins.all(20)) # 6. get the SVG rendering as string - this step is backend dependent svg_string = backend.get_string(page) with open("output.svg", "wt", encoding="utf8") as fp: fp.write(svg_string) if __name__ == "__main__": export(example_doc()) ``` The exported SVG shows a spiral centered on an A4 page with a margin of 20mm, notice the background has a dark color like the usual background of the modelspace: \[image\] ### Frontend Configuration The *Configuration* object configures the rendering process. This example changes the background color from dark grey to white and renders all lines black. Add the **config** module to imports: ``` from ezdxf.addons.drawing import Frontend, RenderContext, svg, layout, config ``` Create a new configuration and override the background and color policy between the 2nd and the 3rd step: ``` # 2. create the backend backend = svg.SVGBackend() # create a new configuration for a white background and and a black foreground color cfg = config.Configuration( background_policy=config.BackgroundPolicy.WHITE, color_policy=config.ColorPolicy.BLACK, ) # 3. create the frontend frontend = Frontend(context, backend, config=cfg) ``` The new exported SVG has a white background and all lines are black: \[image\] There are many configuration options: - • *LineweightPolicy* - relative, absolute or relative fixed lineweight - • *LinePolicy* - solid or accurate linetypes - • *HatchPolicy* - normal, ignore, only outlines or always solid fill - • *ColorPolicy* - color, black, white, monochrome, … - • *BackgroundPolicy* - default, black, white, off (transparent) and custom - • *TextPolicy* - filling, outline, ignore, … - • *ProxyGraphicPolicy* - ignore, show, prefer - • lineweight scaling factor - • minimal lineweight - • *max\_flattening\_distance* for curve approximation - • and more … All configuration options are documented here: *Configuration*. ### Page Layout The *Page* object defines the output page for some backends (SVG, PDF, PNG, PLT). A page is defined by width and height in a given length unit. The supported length units are millimeters (mm), inch (in), point (1 pt is 1/72 in) and pixels (1 px is 1/96 in). It’s possible to autodetect the page size from the content or fit the content onto the page. In both cases the margin values are used to create space between the content and the page borders. The content is centered in the remaining space without margins. **IMPORTANT:** None of the backends crop the content automatically, the margin values are just calculation values! ### Autodetect Page Size The required page size is auto-detected by setting the width and/or height to 0. By default the scaling factor is 1, so 1 drawing unit is 1 page unit. The content is fit to page by default and the outcome is shown in the previous examples. This example shows the output when the scale should be 1:1, 1 drawing unit is 1 page unit (mm): ``` # auto-detect page size and 2mm margins on all sides page = layout.Page(0, 0, layout.Units.mm, margins=layout.Margins.all(2)) # scale content by 1, do not fit content to page svg_string = backend.get_string( page, settings=layout.Settings(scale=1, fit_page=False) ) ``` The page has a size of 14x14mm, a content size of 10x10mm and 2mm margins on all sides. \[image\] ### Scaling Content Scaling the content by factor 10 means, 10 page units represent 1 drawing unit, which is a scale of 10:1 and only uniform scaling is supported. ``` def export_2(doc): backend = make_backend(doc) # auto-detect page size and 2mm margins on all sides page = layout.Page(0, 0, layout.Units.mm, margins=layout.Margins.all(2)) # scale content by 10, do not fit content to page svg_string = backend.get_string( ``` The page has a size of 104x104mm, a content size of 100x100mm and 2mm margins on all sides. \[image\] ### Limit Page Size The page arguments *max\_width* and *max\_height* can limit the page size in auto-detection mode, e.g. most plotter devices can only print upto a width of 900mm. **SEE ALSO:** - • *Page* class - • *Margins* class - • *Settings* class ### SVG Export The steps to export a SVG by the *SVGBackend* are show in the first example, the configuration of the frontend and the page setup are shown in the previous sections. - 1\. Create the render context - 2\. Create the backend - 3\. Create and configure the frontend - 4\. Draw the content - 5\. Setup the page layout - 6\. Create the SVG output string This is the same code as for the first example: ``` def export(doc): msp = doc.modelspace() # 1. create the render context context = RenderContext(doc) # 2. create the backend backend = svg.SVGBackend() # 3. create the frontend frontend = Frontend(context, backend) # 4. draw the modelspace frontend.draw_layout(msp) # 5. create an A4 page layout, not required for all backends page = layout.Page(210, 297, layout.Units.mm, margins=layout.Margins.all(20)) # 6. get the SVG rendering as string - this step is backend dependent svg_string = backend.get_string(page) with open("output.svg", "wt", encoding="utf8") as fp: fp.write(svg_string) ``` The SVG backend flips the coordinates along the y-axis and transforms the content into a compact integer coordinate space and produces therefore a small file size but therefore the output coordinates are different to the DXF coordinates. ### PDF Export The PDF export requires the the *PyMuPdf* package to be installed. The steps to export a PDF are very similar to SVG, except for the *PyMuPdfBackend* class and the backend returns bytes and not a string: - 1\. Create the render context - 2\. Create the backend - 3\. Create and configure the frontend - 4\. Draw the content - 5\. Setup the page layout - 6\. Create the SVG output string Import the **pymupdf** backend module: ``` from ezdxf.addons.drawing import Frontend, RenderContext, pymupdf, layout, config ``` The export function: ``` def export_dark_bg(doc): msp = doc.modelspace() # 1. create the render context context = RenderContext(doc) # 2. create the backend backend = pymupdf.PyMuPdfBackend() # 3. create the frontend frontend = Frontend(context, backend) # 4. draw the modelspace frontend.draw_layout(msp) # 5. create an A4 page layout page = layout.Page(210, 297, layout.Units.mm, margins=layout.Margins.all(20)) # 6. get the PDF rendering as bytes pdf_bytes = backend.get_pdf_bytes(page) with open("pdf_dark_bg.pdf", "wb") as fp: fp.write(pdf_bytes) ``` \[image\] The PDF has is dark background for the modelspace by default and color index 7 is white. Create a frontend configuration and override the **BackgroundPolicy** to get a white background: ``` # 3. create and configure the frontend cfg = config.Configuration(background_policy=config.BackgroundPolicy.WHITE) frontend = Frontend(context, backend, config=cfg) ``` Now the exported PDF has a white background and color index 7 is black: \[image\] ### PNG Export The PNG export is done by the *PyMuPdfBackend* class and differs only in the method to get the PNG data bytes: ``` # 6. get the PNG rendering as bytes png_bytes = backend.get_pixmap_bytes(page, fmt="png", dpi=96) with open("png_white_bg.png", "wb") as fp: fp.write(png_bytes) ``` The **pymupdf** backend supports multiple image formats: | | | | --- | --- | | png | Portable Network Graphics | | ppm | Portable Pixmap (no alpha channel) | | pbm | Portable Bitmap (no alpha channel) | ### PLT/HPGL2 Export The *PlotterBackend* creates HPGL/2 plot files for output on raster plotters. The **PlotterBackend** is designed to print on white paper, so the background color is always white and color index 7 is black by default. **WARNING:** The plot files are only tested by the plot file viewer *ViewCompanion Standard* but not on real hardware - please use with care and give feedback. The PLT/HPGL2 export is very similar to the SVG export: ``` from ezdxf.addons.drawing import Frontend, RenderContext, hpgl2, layout def export(doc): msp = doc.modelspace() # 1. create the render context context = RenderContext(doc) # 2. create the backend backend = hpgl2.PlotterBackend() # 3. create the frontend frontend = Frontend(context, backend) # 4. draw the modelspace frontend.draw_layout(msp) # 5. create an A4 page layout page = layout.Page(210, 297, layout.Units.mm, margins=layout.Margins.all(20)) # 6. get the HPGL2 rendering as bytes plt_bytes = backend.get_bytes(page) with open("output_01.plt", "wb") as fp: fp.write(plt_bytes) ``` \[image\] The HPGL/2 viewer does not show the margins around the content, but most construction drawings draw the page borders around the content. The **PlotterBackend** has some quality preset methods to get the HPGL/2 data: - • *compatible()* - • *low\_quality()* - • *normal\_quality()* (default) - • *high\_quality()* The difference are mostly the floating point precision and the usage of Bézier curves, but the Bézier curves are approximated by plotter drivers (even by HP drivers), so there is no real quality improvement, but curves need less space than approximated polylines so the file size is smaller. Very old plotter may not support Bézier curves and floating point coordinates, for these plotters the **compatible()** method exports only polylines and integer coordinates. Usage: ``` # 6. get the HPGL2 rendering as bytes plt_bytes = backend.high_quality(page) ``` ### DXF Export The *DXFBackend* exports the content as DXF primitives: POINT, LINE, LWPOLYLINE, SPLINE and HATCH. All blocks are exploded, text is rendered as filled polygons represented by the HATCH entity and arcs are represented by SPLINE entities (internal Bèzier curve representation). This backend was added to convert HPGL/2 files to DXF files, because the **hpgl2** add-on reuses the backends of the **drawing** add-on for export. Maybe it is useful for other tasks too. This backend works different than the previous. There is no page setup and everything is rendered into a given layout of a DXF document: ``` from ezdxf.addons.drawing import Frontend, RenderContext, dxf def export(doc): export_doc = ezdxf.new() msp = doc.modelspace() # 1. create the render context context = RenderContext(doc) # 2. create the backend backend = dxf.DXFBackend(export_doc.modelspace()) # 3. create the frontend frontend = Frontend(context, backend) # 4. draw the modelspace frontend.draw_layout(msp) # 5. save or return DXF document export_doc.saveas("output_01.dxf") ``` ### Recorder Backend The *Recorder* backend is an intermediate layer to record the drawing commands of the *Frontend* class. The *Player* object can replay this records on any other backend class but also provides some additional features like bounding box detection, content transformation and cropping. The SVG/PDF/PLT backends use this intermediate layer internally to transform and place the content. ### Tutorial for Finding Chains and Loops Added in version 1.4. This tutorial shows how to find connected structures like open or closed polylines by the *ezdxf.edgeminer* and the *ezdxf.edgesmith* modules. ### Introduction The main goal of the *ezdxf.edgeminer* module is to find connected edges in a heap of unordered edges. The module is designed to work with anything that has a start- and end point and knows nothing about the edge itself except for the optional length. Therefore intersection points between edges are not known. ### 1. Step: Create Edges The companion module *ezdxf.edgesmith* creates the required edges from DXF primitives like LINE, ARC, ELLIPSE, SPLINE and POLYLINE. - • *ezdxf.edgesmith.make\_edge\_2d()* - • *ezdxf.edgesmith.edges\_from\_entities\_2d()* The current implementation of the *edgesmith* module is restricted to work with 2D structures. Every edge is projected onto the xy-plane of the *WCS*. ### 2. Step: Find Chains and Loops The *edgeminer* module provides functions to search for open chains and closed loops: - • *ezdxf.edgeminer.find\_sequential\_chain()* - • *ezdxf.edgeminer.find\_all\_sequential\_chains()* - • *ezdxf.edgeminer.find\_simple\_chain()* - • *ezdxf.edgeminer.find\_all\_simple\_chains()* - • *ezdxf.edgeminer.find\_all\_open\_chains()* - • *ezdxf.edgeminer.find\_loop()* - • *ezdxf.edgeminer.find\_loop\_by\_edge()* - • *ezdxf.edgeminer.find\_all\_loops()* ### 3. Step: Build Polylines and Paths From the chains and loops found, you can build new polylines and boundary paths for hatches: - • *ezdxf.edgesmith.lwpolyline\_from\_chain()* - • *ezdxf.edgesmith.polyline2d\_from\_chain()* - • *ezdxf.edgesmith.polyline\_path\_from\_chain()* - • *ezdxf.edgesmith.edge\_path\_from\_chain()* - • *ezdxf.edgesmith.path2d\_from\_chain()* ### Terminology This is a short summary, for more information see: *ezdxf.edgeminer* - **Edge** A linear connection between two points. - **Leaf** A leaf is a loose end of an edge, which is not connected to other edges. - **Junction** A junction has more than two adjacent edges. - **Chain** A chain has sequential connected edges. The end point of an edge is connected to the start point of the following edge. - **Simple Chain** A simple chain starts and ends with a leaf or a junction. - **Open Chain** An open chain starts and ends with a leaf. - **Loop** A loop is a simple chain with connected start- and end vertices. ### Join Ordered Entities to Polylines The first example uses an exploded polyline to show how to search for connected edges, when the edges are ordered. ``` import random import ezdxf from ezdxf import edgeminer, edgesmith doc = ezdxf.new() doc.header["$LWDISPLAY"] = 1 msp = doc.modelspace() lwp = msp.add_lwpolyline( [(0, 0), (5, 0, -0.5), (5, 5), (0, 5)], format="xyb", close=True, dxfattribs={"layer": "SOURCE", "color": 2, "lineweight": 30}, ) # create lines and arcs from LWPOLYLINE entities = lwp.explode() ``` The orientation of the entities looks like this: \[image\] ARC entities are always counter-clockwise oriented, so the start- and end points of the adjacent lines are not connected in start/end order. The *ezdxf.edgeminer.find\_sequential\_chain()* function is the right tool for this task. It searches sequential ordered edges and reverses those, where the start- and end point doesn’t match. The search stops at the first edge that doesn’t have a matching start- or end point or a closed loop was found. - 1\. create edges from DXF entities - 2\. find connected edges - 3\. create LWPOLYLINE from connected edges ``` # 1. create edges from DXF entities edges = list(edgesmith.edges_from_entities_2d(entities)) # 2. search for connected edges chain = edgeminer.find_sequential_chain(edges) # 3. create a LWPOLYLINE from connected edges lwp2 = edgesmith.lwpolyline_from_chain( chain, dxfattribs={"layer": "LWPOLYLINE", "color": 1, "lineweight": 30} ) msp.add_entity(lwp2) doc.saveas("result1.dxf") ``` The new created LWPOLYLINE in BricsCAD: \[image\] ### Join Unordered Entities to Polylines For the search in a heap of unordered edges is an additional object required. A *ezdxf.edgeminer.Deposit* has a spatial search tree to optimize the search for unordered edges. The *ezdxf.edgeminer.find\_simple\_chain()* function starts at an edge and searches in both directions via the spatial search tree for connected edges. The search stops at a leaf, a junction or when a closed loop was found. ``` # create a new doc doc = ezdxf.new() doc.header["$LWDISPLAY"] = 1 msp = doc.modelspace() # reuse same entities from previous example edges = list(edgesmith.edges_from_entities_2d(entities)) # shuffle the ordered edges random.shuffle(edges) # a deposit optimizes the search for unordered edges deposit = edgeminer.Deposit(edges) # start the search at an arbitrary edge start = edges[0] chain = edgeminer.find_simple_chain(deposit, start) lwp3 = edgesmith.lwpolyline_from_chain( chain, dxfattribs={"color": 1, "lineweight": 30} ) msp.add_entity(lwp3) doc.saveas("result2.dxf") ``` The result is the same as in “result1.dxf”. The following functions are for situations when you don’t know where to start. - • *ezdxf.edgeminer.find\_all\_simple\_chains()*: returns all chains that start and end with a leaf or a junction - • *ezdxf.edgeminer.find\_all\_open\_chains()*: returns all chains from the deposit that start and end with a leaf. Warning: recursive backtracking! - • *ezdxf.edgeminer.find\_loop()*: returns the first loop found in the deposit. Warning: recursive backtracking! - • *ezdxf.edgeminer.find\_all\_loops()*: returns all possible loops found in the deposit. Warning: recursive backtracking! ### Join Entities to Hatches Creating hatches from edges is similar to creating polylines. - 1\. create a *Hatch* - 2\. find connected edges - 3\. create boundary paths from connected edges - 4\. add boundary paths to *Hatch* ``` # create a new doc doc = ezdxf.new() doc.header["$LWDISPLAY"] = 1 msp = doc.modelspace() # 1. create a HATCH hatch = msp.add_hatch(color=2) # reuse same entities from previous example edges = list(edgesmith.edges_from_entities_2d(entities)) # shuffle the ordered edges random.shuffle(edges) # a deposit optimizes the search for unordered edges deposit = edgeminer.Deposit(edges) # start the search at an arbitrary edge start = edges[0] # 2. find edges chain = edgeminer.find_simple_chain(deposit, start) # 3. create a polyline boundary path from edges boundary_path = edgesmith.polyline_path_from_chain(chain) # 4.add boundary path to HATCH hatch.paths.append(boundary_path) doc.saveas("hatch1.dxf") ``` The new created HATCH in BricsCAD: \[image\] ### How Are 3D Entities Handled? The *ezdxf.edgeminer* module is designed to be as versatile as possible and uses 3D coordinates for all vertices. So edges are only connected when the x-, y- and z-coordinates of their vertices are close together. The *ezdxf.edgesmith* module is designed to avoid the complexity of 3D entities and handles only 2D entities by setting all z-coordinates to 0. Therefore all vertices are projected onto the xy-plane of the WCS and if an entity can not represent such a projection the entity will be flattened into line segments. This example includes an ARC and a SPLINE in 3D space: \[image\] \[image\] ``` doc = ezdxf.readfile("edges_3d.dxf") msp = doc.modelspace() # create edges and search index edges = list(edgesmith.edges_from_entities_2d(msp)) deposit = edgeminer.Deposit(edges) # find a chain chain = edgeminer.find_simple_chain(deposit, edges[0]) # add a hatch and add the boundary path hatch = msp.add_hatch(color=5) boundary_path = edgesmith.polyline_path_from_chain(chain, max_sagitta=0.01) hatch.paths.append(boundary_path) doc.saveas("flattened_hatch.dxf") ``` The hatch is projected onto the xy-plane of the WCS: \[image\] To process only 2D entities us the *filter\_2d\_entities()* function that returns only pure 2D entities and ignores all entities placed outside or extending beyond the xy-plane. ### Junctions A junction is a vertex with a degree of 3 or more and adds complexity to the task of finding geometry. There is not a single solution that fits all needs and some goals are not achievable by the *ezdxf.edgeminer* module. This is the starting point for the following examples, each red circle marks a junction: \[image\] You can check the complexity of your problem by printing the degree-counter: ``` print(deposit.degree_counter()) ``` Output: ``` Counter({2: 15, 3: 4}) ``` There a 15 vertices of degree 2 (good) and 4 vertices of degree 3 (bad). ### Find All Simple Chains A simple chain starts and ends with a leaf or a junction, hence there are no decisions to make and and finding them is also fast by using a spatial search index. ``` # load data doc = ezdxf.readfile("junctions.dxf") msp = doc.modelspace() lines = msp.query("LINE") # create edges and search index edges = list(edgesmith.edges_from_entities_2d(lines)) deposit = edgeminer.Deposit(edges) # find chains chains = edgeminer.find_all_simple_chains(deposit) # create a new output document out = ezdxf.new() msp = out.modelspace() color = 1 for chain in chains: polyline = edgesmith.lwpolyline_from_chain( chain, dxfattribs={"color": color} ) msp.add_entity(polyline) color += 1 out.saveas("simple_chains.dxf") ``` Each color represents a separated LWPOLYLINE: \[image\] ### Find All Loops This task is harder and an edge can be part of multiple solutions: ``` # same code as in the previous example til here # find chains loops = edgeminer.find_all_loops(deposit) # create a new output document out = ezdxf.new() msp = out.modelspace() color = 1 for loop in loops: layer = f"LOOP_{color}" polyline = edgesmith.lwpolyline_from_chain( loop, dxfattribs={"color": color, "layer": layer} ) msp.add_entity(polyline) color += 1 out.saveas("loops.dxf") ``` These are 6 of the 7 solutions, the 7th solution is the dashed line: \[image\] The *find\_all\_loops()* function is a recursive backtracking algorithm and has a complexity of O(n!), therefore all recursive search functions have a timeout argument to finish the task before the universe ends. These helper functions may help you to choose a solution, but the default length calculation for edges is not precise! - • *ezdxf.edgeminer.longest\_chain()* - • *ezdxf.edgeminer.shortest\_chain()* ### Find One Loop For a Given Edge The *find\_loop\_by\_edge()* function starts at a given edge and has a preferred *clockwise* or *counter-clockwise* search order. The algorithm chooses the next edge at a junction in *clockwise* order if the argument **clockwise** is **True** otherwise the first *counter-clockwise* edge. This is a fast non-recursive algorithm. ``` edges = list(edgesmith.edges_from_entities_2d(lines)) deposit = edgeminer.Deposit(edges) # choose an edge to start with start = edges[0] loop1 = edgeminer.find_loop_by_edge(deposit, start, clockwise=True) loop2 = edgeminer.find_loop_by_edge(deposit, start, clockwise=False) ``` \[image\] Red is the *clockwise* solution and yellow is the *counter-clockwise* solution: \[image\] ### Find Loop by Pick-Point The CAD functionality to select a HATCH boundary path by picking a point inside the boundary is a bit tricky, but can be achieved by combining some tools. - 1\. find a starting edge near the pick-point - 2\. find candidates by the **find\_loop\_by\_edge()** function for both search orders - 3\. sort candidates by area - 4\. take the smallest loop which contains the pick-point \[image\] The function *intersecting\_edges\_2d()* tests all edges for an intersection with a line starting at the pick-point and ending outside the bounding box of all vertices. Any loop containing the pick-point has at least one edge that intersects this line. ``` doc = ezdxf.readfile("junctions.dxf") msp = doc.modelspace() lines = msp.query("LINE") edges = list(edgesmith.edges_from_entities_2d(lines)) pick_point = (110, 50) # 1. find a starting edge near the pick-point intersecting_edges = edgesmith.intersecting_edges_2d(edges, pick_point) if not len(intersecting_edges): print("no intersection found") return hatch = msp.add_hatch(color=2) # The intersecting edges are sorted by ascending distance to the pick-point # take the closest edge as starting edge: start = intersecting_edges[0].edge # 2. find the best loop candidates deposit = edgeminer.Deposit(edges) candidates = [ edgeminer.find_loop_by_edge(deposit, start, clockwise=True), edgeminer.find_loop_by_edge(deposit, start, clockwise=False), ] # 3. sort candidates by area candidates.sort(key=edgesmith.loop_area) for loop in candidates: # 4. take the smallest loop which contains the pick-point if edgesmith.is_inside_polygon_2d(loop, pick_point): hatch.paths.append(edgesmith.polyline_path_from_chain(loop)) break else: # for loop ended without break print("no loop found") return doc.saveas("find_loop_by_pick_point.dxf") ``` I am not convinced that this is the best solution or that this solution works for all use cases, therefore this is not (yet) a helper function in the **edgesmith** module. ### Gaps and Design Inaccuracies Most real-world DXF drawings have design inaccuracies, that means, there are gaps between the endpoints of entities. All search and test functions have an optional argument **gap\_tol** or the gap tolerance is stored in the **Deposit** class. The gap tolerance is the maximum distance between two edge vertices to consider them as connected. It is important to use the same tolerance throughout a task, from creating the edges til building new DXF entities from chains and loops. ### Specialty Edge Paths AutoCAD is very picky about edge paths in HATCH entities when it comes to considering them as closed. Therefore the **edge\_path\_from\_chain()** function adds additional line segments between edges when the gap is larger than **LEN\_TOL**, **LEN\_TOL** is a constant value of 1e-9. ### Coincident Edges Coincident edges in the context of **edgeminer** are edges where the start- and the end vertex are coincident, remember: the shape of the edge is not known. This is the reason why such edges are not removed automatically, e.g. two arcs can create a closed loop as coincident edges: \[image\] Coincident edges are a major nuisance and should be avoided at all costs. They create ambiguity and can be the reason why the expected results are not found. The *filter\_coincident\_edges()* function removes coincident edges. It takes a function to test if two edges are coincident and the default function tests only if the end points are coincident, but you can pass a more sophisticated function. ### Set Operations The *ezdxf.edgeminer.Edge* class implements the **\_\_hash\_\_()** method and can be used in sets, this allows set operations like subtracting a found loop from the source edges: ``` edges = list(edgesmith.edges_from_entities_2d(lines)) deposit = edgeminer.Deposit(edges) # returns the first loop found first_loop = edgeminer.find_loop(deposit) edges = list(set(edges) - set(first_loop)) # or use this helper function: edges = edgeminer.subtract_edges(edges, first_loop) ``` The **Deposit** has to be recreated for the new list of edges! ## HOWTO The Howto section show how to accomplish specific tasks with *ezdxf* in a straight forward way without teaching basics or internals, if you are looking for more information about the ezdxf internals look at the *Reference* section or if you want to learn how to use *ezdxf* go to the *Tutorials* section or to the *Basic Concepts* section. ### General Document General preconditions: ``` import sys import ezdxf try: doc = ezdxf.readfile("your_dxf_file.dxf") except IOError: print(f"Not a DXF file or a generic I/O error.") sys.exit(1) except ezdxf.DXFStructureError: print(f"Invalid or corrupted DXF file.") sys.exit(2) msp = doc.modelspace() ``` This works well with DXF files from trusted sources like AutoCAD or BricsCAD, for loading DXF files with minor or major flaws look at the *ezdxf.recover* module. ### Load DXF Files with Structure Errors If you know the files you will process have most likely minor or major flaws, use the *ezdxf.recover* module: ``` import sys from ezdxf import recover try: # low level structure repair: doc, auditor = recover.readfile(name) except IOError: print(f"Not a DXF file or a generic I/O error.") sys.exit(1) except ezdxf.DXFStructureError: print(f"Invalid or corrupted DXF file: {name}.") sys.exit(2) # DXF file can still have unrecoverable errors, but this is maybe # just a problem when saving the recovered DXF file. if auditor.has_errors: print(f"Found unrecoverable errors in DXF file: {name}.") auditor.print_error_report() ``` For more loading scenarios follow the link: *ezdxf.recover* ### Set/Get Header Variables *ezdxf* has an interface to get and set HEADER variables: ``` doc.header["VarName"] = value value = doc.header["VarName"] ``` **SEE ALSO:** *HeaderSection* and online documentation from Autodesk for available *header variables*. ### Set DXF Drawing Units The header variable $INSUNITS defines the drawing units for the modelspace and therefore for the DXF document if no further settings are applied. The most common units are 6 for meters and 1 for inches. Use this HEADER variables to setup the default units for CAD applications opening the DXF file. This setting is not relevant for *ezdxf* API calls, which are unitless for length values and coordinates and decimal degrees for angles (in most cases). Sets drawing units: ``` doc.header["$INSUNITS"] = 6 ``` For more information see section *DXF Units*. ### Explore the DXF File Structure DXF files are plain text files, you can open this files with every text editor which handles bigger files. But it is not really easy to get quick the information you want. Use the DXF structure browser: ``` # Call as executable script from the command line: ezdxf browse FILE # Call as module on Windows: py -m ezdxf browse FILE # Call as module on Linux/Mac python3 -m ezdxf browse FILE ``` This command requires *PySide6* or *PyQt5* to be installed. It opens a desktop window with a selection panel for all DXF entities in the document, and handles int the entity view are links between DXF entities, this simplifies the navigation between the DXF entities. Read the docs for the *Browse* command for more information. \[image\] ### Calculate Extents for the Modelspace Since *ezdxf* v0.16 exist a *ezdxf.bbox* module to calculate bounding boxes for DXF entities. This module makes the extents calculation very easy, but read the documentation for the *bbox* module to understand its limitations. ``` import ezdxf from ezdxf import bbox doc = ezdxf.readfile("your.dxf") msp = doc.modelspace() extents = bbox.extents(msp) ``` The returned *extents* is a *ezdxf.math.BoundingBox* object. ### Set Initial View/Zoom for the Modelspace To show an arbitrary location of the modelspace centered in the CAD application window, set the **'\*Active'** VPORT to this location. The DXF attribute **dxf.center** defines the location in the modelspace, and the **dxf.height** specifies the area of the modelspace to view. Shortcut function: ``` doc.set_modelspace_vport(height=10, center=(10, 10)) ``` **SEE ALSO:** The *ezdxf.zoom* module is another way to set the initial modelspace view. Setting the initial view to the extents of all entities in the modelspace: ``` import ezdxf from ezdxf import zoom doc = ezdxf.readfile("your.dxf") msp = doc.modelspace() zoom.extents(msp) ``` Setting the initial view to the extents of just some entities: ``` lines = msp.query("LINES") zoom.objects(lines) ``` The *zoom* module also works for paperspace layouts. **IMPORTANT:** The *zoom* module uses the *bbox* module to calculate the bounding boxes for DXF entities. Read the documentation for the *bbox* module to understand its limitations and the bounding box calculation for large documents can take a while! ### Hide the UCS Icon The visibility of the UCS icon is controlled by the DXF *ucs\_icon* attribute of the *VPort* entity: - • bit 0: 0=hide, 1=show - • bit 1: 0=display in lower left corner, 1=display at origin The state of the UCS icon can be set in conjunction with the initial *VPort* of the model space, this code turns off the UCS icon: ``` doc.set_modelspace_vport(10, center=(10, 10), dxfattribs={"ucs_icon": 0}) ``` Alternative: turn off UCS icons for all **VPort** entries in the active viewport configuration: ``` for vport in doc.viewports.get_config("*Active"): vport.dxf.ucs_icon = 0 ``` ### Show Lineweights in DXF Viewers By default lines and curves are shown without lineweights in DXF viewers. By setting the header variable $LWDISPLAY to 1 the DXF viewer should display lineweights, if supported by the viewer. ``` doc.header["$LWDISPLAY"] = 1 ``` ### Add *ezdxf* Resources to Existing DXF Document Add all *ezdxf* specific resources (line types, text- and dimension styles) to an existing DXF document: ``` import ezdxf from ezdxf.tools.standards import setup_drawing doc = ezdxf.readfile("your.dxf") setup_drawing(doc, topics="all") ``` ### Set Logging Level of *ezdxf* Set the logging level of the *ezdxf* package to a higher level to minimize logging messages from ezdxf. At level **ERROR** only severe errors will be logged and **WARNING**, **INFO** and **DEBUG** messages will be suppressed: ``` import logging logging.getLogger("ezdxf").setLevel(logging.ERROR) ``` ### DXF Viewer ### A360 Viewer Problems AutoDesk web service *A360* seems to be more picky than the AutoCAD desktop applications, may be it helps to use the latest DXF version supported by ezdxf, which is DXF R2018 (AC1032) in the year of writing this lines (2018). ### DXF Entities Are Not Displayed in the Viewer *ezdxf* does not automatically locate the main viewport of the modelspace at the entities, you have to perform the “Zoom to Extends” command, here in TrueView 2020: \[image\] And here in the Autodesk Online Viewer: \[image\] Add this line to your code to relocate the main viewport, adjust the *center* (in modelspace coordinates) and the *height* (in drawing units) arguments to your needs: ``` doc.set_modelspace_vport(height=10, center=(0, 0)) ``` ### Show IMAGES/XREFS on Loading in AutoCAD If you are adding XREFS and IMAGES with relative paths to existing drawings and they do not show up in AutoCAD immediately, change the HEADER variable **$PROJECTNAME=''** to *(not really)* solve this problem. The ezdxf templates for DXF R2004 and later have **$PROJECTNAME=''** as default value. Thanks to *David Booth*: If the filename in the IMAGEDEF contains the full path (absolute in AutoCAD) then it shows on loading, otherwise it won’t display (reports as unreadable) until you manually reload using XREF manager. A workaround (to show IMAGES on loading) appears to be to save the full file path in the DXF or save it as a DWG. Thanks to *Zac Luzader*: Has anyone else noticed that very short simple image file names seem to avoid this problem? Once I ensured that the image file’s name was short and had no special characters (letters, numbers and underscores only) the problem seemed to go away. I didn’t rigorously analyze the behavior as its very time consuming. Also: You can safely put the image in a subdirectory and use a relative path. The name of the subdirectory does not seem to trigger this problem, provided that the image file name itself is very short and simple. Also pro tip: The XRef manager exists in DWG TrueView 2023, but access to it is only possible if you have a completely broken reference. Create a DXF with a reference to a non-existent file, then the error dialog will let you open the XRef Manager. Once it is open you can pin it and it will be open next time, even if you have no broken references. **SEE ALSO:** Discussion on github: *Images don’t show in AutoCAD until …* ### Set Initial View/Zoom for the Modelspace See section “General Document”: *Set Initial View/Zoom for the Modelspace* ### Show Lineweights in DXF Viewers By default lines and curves are shown without lineweights in DXF viewers. By setting the header variable $LWDISPLAY to 1 the DXF viewer should display lineweights, if supported by the viewer. ``` doc.header["$LWDISPLAY"] = 1 ``` ### DXF Content General preconditions: ``` import sys import ezdxf try: doc = ezdxf.readfile("your_dxf_file.dxf") except IOError: print(f'Not a DXF file or a generic I/O error.') sys.exit(1) except ezdxf.DXFStructureError: print(f'Invalid or corrupted DXF file.') sys.exit(2) msp = doc.modelspace() ``` ### Get/Set Entity Color The entity color is stored as *ACI* (AutoCAD Color Index): ``` aci = entity.dxf.color ``` Default value is 256 which means BYLAYER: ``` layer = doc.layers.get(entity.dxf.layer) aci = layer.get_color() ``` The special *get\_color()* method is required, because the color attribute **Layer.dxf.color** is misused as layer on/off flag, a negative color value means the layer is off. ACI value 0 means BYBLOCK, which means the color from the block reference (INSERT entity). Set color as ACI value as int in range \[0, 256\]: ``` entity.dxf.color = 1 ``` The ACI value 7 has a special meaning, it is white on dark backgrounds and white on light backgrounds. ### Get/Set Entity RGB Color RGB true color values are supported since DXF R13 (AC1012), the 24-bit RGB value is stored as integer in the DXF attribute *true\_color*: ``` # 24 bit binary value: 0bRRRRRRRRGGGGGGGGBBBBBBBB or hex value: 0xRRGGBB # set true color value to red entity.dxf.true_color = 0xFF0000 ``` Use the helper functions from the *ezdxf.colors* module for RGB integer value handling: ``` from ezdxf import colors entity.dxf.true_color = colors.rgb2int((0xFF, 0, 0)) r, g, b = colors.int2rgb(entity.dxf.true_color) ``` The RGB values of the AutoCAD default colors are not officially documented, but an accurate translation table is included in *ezdxf*: ``` # Warning: ACI value 256 (BYLAYER) raises an IndexError! rgb24 = colors.DXF_DEFAULT_COLORS[aci] print(f"RGB Hex Value: #{rgb24:06X}") r, g, b = colors.int2rgb(rgb24) print(f"RGB Channel Values: R={r:02X} G={g:02X} b={b:02X}") ``` If **color** and **true\_color** values are set, BricsCAD and AutoCAD use the **true\_color** value as display color for the entity. ### Get/Set True Color as RGB-Tuple Get/Set the true color value as (r, g, b)-tuple by the *rgb* property of the *DXFGraphic* entity: ``` # set true color value to red entity.rgb = (0xFF, 0, 0) # get true color values r, g, b = entity.rgb ``` ### Get/Set Block Reference Attributes Block references (*Insert*) can have attached attributes (*Attrib*), these are simple text annotations with an associated tag appended to the block reference. Iterate over all appended attributes: ``` # get all INSERT entities with entity.dxf.name == "Part12" blockrefs = msp.query('INSERT[name=="Part12"]') if len(blockrefs): entity = blockrefs[0] # process first entity found for attrib in entity.attribs: if attrib.dxf.tag == "diameter": # identify attribute by tag attrib.dxf.text = "17mm" # change attribute content ``` Get attribute by tag: ``` diameter = entity.get_attrib('diameter') if diameter is not None: diameter.dxf.text = "17mm" ``` ### Adding XDATA to Entities Adding XDATA as list of tuples (group code, value) by *set\_xdata()*, overwrites data if already present: ``` doc.appids.new('YOUR_APPID') # IMPORTANT: create an APP ID entry circle = msp.add_circle((10, 10), 100) circle.set_xdata( 'YOUR_APPID', [ (1000, 'your_web_link.org'), (1002, '{'), (1000, 'some text'), (1002, '{'), (1071, 1), (1002, '}'), (1002, '}') ]) ``` For group code meaning see DXF reference section *DXF Group Codes in Numerical Order Reference*, valid group codes are in the range 1000 - 1071. Method *get\_xdata()* returns the extended data for an entity as *Tags* object. **SEE ALSO:** Tutorial: *Storing Custom Data in DXF Files* ### Get Overridden DIMSTYLE Values from DIMENSION In general the *Dimension* styling and config attributes are stored in the **Dimstyle** entity, but every attribute can be overridden for each DIMENSION entity individually, get overwritten values by the **DimstyleOverride** object as shown in the following example: ``` for dimension in msp.query('DIMENSION'): dimstyle_override = dimension.override() # requires v0.12 dimtol = dimstyle_override['dimtol'] if dimtol: print(f'{str(dimension)} has tolerance values:') dimtp = dimstyle_override['dimtp'] dimtm = dimstyle_override['dimtm'] print(f'Upper tolerance: {dimtp}') print(f'Lower tolerance: {dimtm}') ``` The **DimstyleOverride** object returns the value of the underlying DIMSTYLE objects if the value in DIMENSION was not overwritten, or **None** if the value was neither defined in DIMSTYLE nor in DIMENSION. ### Override DIMSTYLE Values for DIMENSION Same as above, the **DimstyleOverride** object supports also overriding DIMSTYLE values. But just overriding this values have no effect on the graphical representation of the DIMENSION entity, because CAD applications just show the associated anonymous block which contains the graphical representation on the DIMENSION entity as simple DXF entities. Call the **render** method of the **DimstyleOverride** object to recreate this graphical representation by *ezdxf*, but *ezdxf* **does not** support all DIMENSION types and DIMVARS yet, and results **will differ** from AutoCAD or BricsCAD renderings. ``` dimstyle_override = dimension.override() dimstyle_override.set_tolerance(0.1) # delete associated geometry block del doc.blocks[dimension.dxf.geometry] # recreate geometry block dimstyle_override.render() ``` ### How to Change the HATCH Pattern Origin Point This code sets the origin of the first pattern line to the given *origin* and the origins of all remaining pattern lines relative to the first pattern line origin. ``` from ezdxf.entities import Hatch, Pattern from ezdxf.math import Vec2 def shift_pattern_origin(hatch: Hatch, offset: Vec2): if isinstance(hatch.pattern, Pattern): for pattern_line in hatch.pattern.lines: pattern_line.base_point += offset def reset_pattern_origin_of_first_pattern_line(hatch: Hatch, origin: Vec2): if isinstance(hatch.pattern, Pattern) and len(hatch.pattern.lines): first_pattern_line = hatch.pattern.lines[0] offset = origin - first_pattern_line.base_point shift_pattern_origin(hatch, offset) ``` **SEE ALSO:** - • Discussion *#769* ### How to Get the Length of a Spline or Polyline There exist no analytical function to calculate the length of a *B-spline*, you have to approximate the curve and calculate the length of the polyline. The construction tool *ezdxf.math.ConstructionPolyline* is may be useful for that. ``` import ezdxf from ezdxf.math import ConstructionPolyline doc = ezdxf.new() msp = doc.modelspace() fit_points = [(0, 0, 0), (750, 500, 0), (1750, 500, 0), (2250, 1250, 0)] spline = msp.add_spline(fit_points) # Adjust the max. sagitta distance to your needs or run the calculation in a loop # reducing the distance until the difference to the previous run is smaller # than your expected precision: polyline = ConstructionPolyline(spline.flattening(distance=0.1)) print(f"approximated length = {polyline.length:.2f}") ``` ### How to Resolve DXF Properties Graphical properties of DXF entities (color, lineweight, …) are sometimes hard to resolve because of the complex possibilities to inherit properties from layers or blocks, or overriding them by *ctb* files. The *drawing* add-on provides the *RenderContext* class that can be used to resolve properties of entities in the context of their use: ``` import ezdxf from ezdxf.addons.drawing.properties import RenderContext doc = ezdxf.new() doc.layers.add("LINE", color=ezdxf.colors.RED) msp = doc.modelspace() line = msp.add_line((0, 0), (1, 0), dxfattribs={"layer": "LINE"}) ctx = RenderContext(doc) ctx.set_current_layout(msp) print(f"resolved RGB value: {ctx.resolve_color(line)}") ``` Output: ``` resolved RGB value: #ff0000 ``` This works in most simple cases, resolving properties of objects in viewports or nested blocks requires additional information that is beyond the scope of a simple guide. ### How to Find XREF Definitions XREFs are normal block definitions and can be found in the BLOCKS section: ``` for block_layout in doc.blocks: block = block_layout.block # the BLOCK entity if block.is_xref: handle_xref(block_layout) elif block.is_xref_overlay: handle_xref_overlay(block_layout) ``` **SEE ALSO:** - • documentation of the *ezdxf.xref* module - • *ezdxf.layouts.BlockLayout* ### How to Find XREF References An XREF reference is a block reference (INSERT entity) to the block definition of the XREF: ``` for insert in msp.query("INSERT"): if insert.is_xref: handle_xref_reference(insert) # ... or get the XREF definition block_layout = insert.block() if block_layout is not None: block = block_layout.block if block.is_xref: handle_xref(block_layout) elif block.is_xref_overlay: handle_xref_overlay(block_layout) ``` Like any normal block, an XREF can be inserted multiple times. **SEE ALSO:** - • documentation of the *ezdxf.xref* module - • *ezdxf.layouts.BlockLayout* ### Fonts ### Rendering SHX Fonts The SHX font format is not documented nor supported by many libraries/packages like *Matplotlib* and *Qt*, therefore only SHX fonts which have corresponding TTF-fonts can be rendered by these backends. The mapping from/to SHX/TTF fonts is hard coded in the source code file: *fonts.py* Since *ezdxf* v1.1 is the rendering of SHX fonts supported if the path to these fonts is added to the **support\_dirs** in the *Config Files*. ### Adding New Font Directories When you add new directories to the **support\_dirs** in your config file, you have to rebuild the font cache to use these fonts with *ezdxf*, see section *Rebuild Font Manager Cache* ### Adding New Fonts When you add new fonts to any of the support directories, you have to rebuild the font cache to use these fonts with *ezdxf*, see section *Rebuild Font Manager Cache* ### Rebuild Font Manager Cache If you want to use new installed fonts or fonts from a new added font directory which is not included in the current cache file of *ezdxf* you have to rebuild the cache file: ``` import ezdxf from ezdxf.fonts import fonts fonts.build_system_font_cache() ``` or call the *ezdxf* launcher to do that: ``` ezdxf --fonts ``` ### Drawing Add-on This section consolidates the *FAQ* about the drawing add-on from the github forum. ### All Backends ### How to Set Background and Foreground Colors Override the default background and foreground colors. The foreground color is the *AutoCAD Color Index (ACI)* 7, which is white/black depending on the background color. If the foreground color is not specified, the foreground color is white for dark backgrounds and black for light backgrounds. The required color format is a hex string “#RRGGBBAA”. ``` from ezdxf.addons.drawing.properties import LayoutProperties # -x-x-x snip -x-x-x- fig: plt.Figure = plt.figure() ax: plt.Axes = fig.add_axes((0, 0, 1, 1)) ctx = RenderContext(doc) # get the modelspace properties msp_properties = LayoutProperties.from_layout(msp) # set light gray background color and black foreground color msp_properties.set_colors("#eaeaea") out = MatplotlibBackend(ax) # override the layout properties and render the modelspace Frontend(ctx, out).draw_layout( msp, finalize=True, layout_properties=msp_properties, ) fig.savefig("image.png") ``` A light background “#eaeaea” has a black foreground color by default: \[image\] A dark background “#0a0a0a” has a white foreground color by default: ``` # -x-x-x snip -x-x-x- msp_properties.set_colors("#0a0a0a") # -x-x-x snip -x-x-x- ``` \[image\] ### How to Set a Transparent Background Color The override color include an alpha transparency “#RRGGBBAA” value. An alpha value of “00” is opaque and “ff” is fully transparent. A transparent background color still defines the foreground color! **HINT:** The **savefig()** function of the matplotlib backend requires the *transparent* argument to be set to **True** to support transparency. A light and fully transparent background “#eaeaeaff” has a black foreground color by default: ``` # -x-x-x snip -x-x-x- msp_properties.set_colors("#eaeaeaff") # -x-x-x snip -x-x-x- fig.savefig("image.png", transparent=True) ``` \[image\] A dark and fully transparent background “#0a0a0aff” has a **white** foreground color by default: ``` # -x-x-x snip -x-x-x- msp_properties.set_colors("#0a0a0aff") # -x-x-x snip -x-x-x- fig.savefig("image.png", transparent=True) ``` \[image\] ### How to Exclude DXF Entities from Rendering - • If all unwanted entities are on the same layer switch off the layer. - • If the document is not saved later, you can delete the entities or set them invisible. - • Filter the unwanted entities by a filter function. The argument *filter\_func* of the **Frontend.draw\_layout()** method expects a function which takes a graphical DXF entity as input and returns **True** if the entity should be rendered or **False** to exclude the entity from rendering. This filter function excludes all DXF entities with an ACI color value of 2: ``` from ezdxf.entities import DXFGraphic def my_filter(e: DXFGraphic) -> bool: return e.dxf.color != 2 # -x-x-x snip -x-x-x- Frontend(ctx, out).draw_layout(msp, finalize=True, filter_func=my_filter) ``` **IMPORTANT:** Not all attributes have a default value if the attribute does not exist. If you are not sure about this, use the **get()** method: ``` def my_filter(e: DXFGraphic) -> bool: return e.dxf.get("color", 7) != 2 ``` ### How to Override Properties of DXF Entities Create a custom **Frontend** class and override the the **override\_properties()** method: ``` class MyFrontend(Frontend): def override_properties(self, entity: DXFGraphic, properties: Properties) -> None: # remove alpha channel from all entities, "#RRGGBBAA" properties.color = properties.color[:7] # -x-x-x snip -x-x-x- MyFrontend(ctx, out).draw_layout(msp, finalize=True) ``` **SEE ALSO:** - • *ezdxf.addons.drawing.properties.Properties* ### Matplotlib Backend **SEE ALSO:** - • Matplotlib package: *https://matplotlib.org/stable/api/matplotlib\_configuration\_api.html* - • **Figure** API: *https://matplotlib.org/stable/api/figure\_api.html* - • **Axes** API: *https://matplotlib.org/stable/api/axis\_api.html* ### How to Get the Pixel Coordinates of DXF Entities **SEE ALSO:** - • Source: *https://github.com/mozman/ezdxf/discussions/219* Transformation from modelspace coordinates to image coordinates: ``` import matplotlib.pyplot as plt from PIL import Image, ImageDraw import ezdxf from ezdxf.math import Matrix44 from ezdxf.addons.drawing import RenderContext, Frontend from ezdxf.addons.drawing.matplotlib import MatplotlibBackend def get_wcs_to_image_transform( ax: plt.Axes, image_size: tuple[int, int] ) -> Matrix44: """Returns the transformation matrix from modelspace coordinates to image coordinates. """ x1, x2 = ax.get_xlim() y1, y2 = ax.get_ylim() data_width, data_height = x2 - x1, y2 - y1 image_width, image_height = image_size return ( Matrix44.translate(-x1, -y1, 0) @ Matrix44.scale( image_width / data_width, -image_height / data_height, 1.0 ) # +1 to counteract the effect of the pixels being flipped in y @ Matrix44.translate(0, image_height + 1, 0) ) # create the DXF document doc = ezdxf.new() msp = doc.modelspace() msp.add_lwpolyline([(0, 0), (1, 0), (1, 1), (0, 1)], close=True) msp.add_line((0, 0), (1, 1)) # export the pixel image fig: plt.Figure = plt.figure() ax: plt.Axes = fig.add_axes([0, 0, 1, 1]) ctx = RenderContext(doc) out = MatplotlibBackend(ax) Frontend(ctx, out).draw_layout(msp, finalize=True) fig.savefig("cad.png") plt.close(fig) # reload the pixel image by Pillow (PIL) img = Image.open("cad.png") draw = ImageDraw.Draw(img) # add some annotations to the pixel image by using modelspace coordinates m = get_wcs_to_image_transform(ax, img.size) a, b, c = ( (v.x, v.y) # draw.line() expects tuple[float, float] as coordinates # transform modelspace coordinates to image coordinates for v in m.transform_vertices([(0.25, 0.75), (0.75, 0.25), (1, 1)]) ) draw.line([a, b, c, a], fill=(255, 0, 0)) # show the image by the default image viewer img.show() ``` ### How to Get Modelspace Coordinates from Pixel Coordinates This is the reverse operation of the previous how-to: *How to Get the Pixel Coordinates of DXF Entities* **SEE ALSO:** - • Full example script: *wcs\_to\_image\_coordinates.py* - • Source: *https://github.com/mozman/ezdxf/discussions/269* ``` def get_image_to_wcs_transform( ax: plt.Axes, image_size: tuple[int, int] ) -> Matrix44: m = get_wcs_to_image_transform(ax, image_size) m.inverse() return m # -x-x-x snip -x-x-x- img2wcs = get_image_to_wcs_transform(ax, img.size) print(f"0.25, 0.75 == {img2wcs.transform(a).round(2)}") print(f"0.75, 0.25 == {img2wcs.transform(b).round(2)}") print(f"1.00, 1.00 == {img2wcs.transform(c).round(2)}") ``` ### How to Export a Specific Area of the Modelspace This code exports the specified modelspace area from (5, 3) to (7, 8) as a 2x5 inch PNG image to maintain the aspect ratio of the source area. Use case: render only a specific area of the modelspace. **SEE ALSO:** - • Full example script: *export\_specific\_area.py* - • Source: *https://github.com/mozman/ezdxf/discussions/451* ``` # -x-x-x snip -x-x-x- # export the pixel image fig: plt.Figure = plt.figure() ax: plt.Axes = fig.add_axes([0, 0, 1, 1]) ctx = RenderContext(doc) out = MatplotlibBackend(ax) Frontend(ctx, out).draw_layout(msp, finalize=True) # setting the export area: xmin, xmax = 5, 7 ymin, ymax = 3, 8 ax.set_xlim(xmin, xmax) ax.set_ylim(ymin, ymax) # set the output size to get the expected aspect ratio: fig.set_size_inches(xmax - xmin, ymax - ymin) fig.savefig("x5y3_to_x7y8.png") plt.close(fig) ``` ### How to Render Without Margins To remove the empty space at the image borders set the margins of the **Axes** object to zero: ``` ax.margins(0) fig.savefig("image_without_margins.png") plt.close(fig) ``` **SEE ALSO:** - • Matplotlib docs about *margins* ### How to Set the Pixel Count per Drawing Unit This code exports the modelspace with an extent of 5 x 3 drawing units with 100 pixels per drawing unit as a 500 x 300 pixel image. Use case: render the content with a fixed number of pixels for a drawing unit, e.g. a drawing unit of 1 inch should be rendered by 100 pixels. **SEE ALSO:** - • Full example script: *export\_image\_pixel\_size.py* - • Source: *https://github.com/mozman/ezdxf/discussions/357* ``` # -x-x-x snip -x-x-x- def set_pixel_density(fig: plt.Figure, ax: plt.Axes, ppu: int): """Argument `ppu` is pixels per drawing unit.""" xmin, xmax = ax.get_xlim() width = xmax - xmin ymin, ymax = ax.get_ylim() height = ymax - ymin dpi = fig.dpi width_inch = width * ppu / dpi height_inch = height * ppu / dpi fig.set_size_inches(width_inch, height_inch) # -x-x-x snip -x-x-x- # export image with 100 pixels per drawing unit = 500x300 pixels set_pixel_density(fig, ax, 100) fig.savefig("box_500x300.png") plt.close(fig) ``` ### How to Export a Specific Image Size in Pixels This code exports the modelspace with an extent of 5 x 3 drawing units as a 1000 x 600 pixel Image. Use case: render the content with a fixed image size in pixels. **SEE ALSO:** - • Full example script: *export\_image\_pixel\_size.py* - • Source: *https://github.com/mozman/ezdxf/discussions/357* ``` # -x-x-x snip -x-x-x- def set_pixel_size(fig: plt.Figure, size: tuple[int, int]): x, y = size fig.set_size_inches(x / fig.dpi, y / fig.dpi) # -x-x-x snip -x-x-x- # export image with a size of 1000x600 pixels set_pixel_size(fig, (1000, 600)) fig.savefig("box_1000x600.png") plt.close(fig) ``` ### How to Set the Page Size in Inches The page- or image size in inches is set by the **set\_size\_inches()** method of the **Figure** class. The content within the **Axes** limits will be scaled to fill the page. Use case: render the whole content to a PDF document with a specific paper size without worrying about scale. ``` fig.set_size_inches(8, 11) ``` ### How to Render at a Specific Scale This code exports the modelspace at a specific scale and paper size. Use case: render the content to a PDF document with a specific paper size and scale, but not all content may be rendered. **SEE ALSO:** - • Full example script: *render\_to\_scale.py* - • Source: *https://github.com/mozman/ezdxf/discussions/665* ``` # -x-x-x snip -x-x-x- def render_limits( origin: tuple[float, float], size_in_inches: tuple[float, float], scale: float, ) -> tuple[float, float, float, float]: """Returns the final render limits in drawing units. Args: origin: lower left corner of the modelspace area to render size_in_inches: paper size in inches scale: render scale, e.g. scale=100 means 1:100, 1m is rendered as 0.01m or 1cm on paper """ min_x, min_y = origin max_x = min_x + size_in_inches[0] * scale max_y = min_y + size_in_inches[1] * scale return min_x, min_y, max_x, max_y def export_to_scale( paper_size: tuple[float, float] = (8.5, 11), origin: tuple[float, float] = (0, 0), scale: float = 1, dpi: int = 300, ): """Render the modelspace content with to a specific paper size and scale. Args: paper_size: paper size in inches origin: lower left corner of the modelspace area to render scale: render scale, e.g. scale=100 means 1:100, 1m is rendered as 0.01m or 1cm on paper dpi: pixel density on paper as dots per inch """ # -x-x-x snip -x-x-x- ctx = RenderContext(doc) fig: plt.Figure = plt.figure(dpi=dpi) ax: plt.Axes = fig.add_axes([0, 0, 1, 1]) # disable all margins ax.margins(0) # get the final render limits in drawing units: min_x, min_y, max_x, max_y = render_limits( origin, paper_size, scale ) ax.set_xlim(min_x, max_x) ax.set_ylim(min_y, max_y) out = MatplotlibBackend(ax) # finalizing invokes auto-scaling by default! Frontend(ctx, out).draw_layout(msp, finalize=False) # set output size in inches: fig.set_size_inches(paper_size[0], paper_size[1], forward=True) fig.savefig(f"image_scale_1_{scale}.pdf", dpi=dpi) plt.close(fig) ``` ### How to Control the Line Width The DXF **lineweight** attribute defines the line width as absolute width on the output medium (e.g. 25 = 0.25mm) and therefore depends only on the DPI (dots per inch) setting of the **Figure** class and the **savefig()** method. There are two additional settings in the *Configuration* class which influences the line width: - • *min\_lineweight* sets the minimum line width in 1/300 inch - a value of 300 is a line width of 1 inch - • *lineweight\_scaling*, multiply the line width by a this factor The following table shows the line width in pixels for all valid DXF lineweights for a resolution of 72, 100, 200 and 300 dpi: \[image\] **SEE ALSO:** Discussion: *https://github.com/mozman/ezdxf/discussions/797* ## FAQ These are the old FAQ until late 2023, new FAQs will only be added to the *Knowledge Graph*. ### What is the Relationship between ezdxf, dxfwrite and dxfgrabber? In 2010 I started my first Python package for creating DXF documents called *dxfwrite*, this package can’t read DXF files and writes only the DXF R12 (AC1009) version. While *dxfwrite* works fine, I wanted a more versatile package, that can read and write DXF files and maybe also supports newer DXF formats than DXF R12. This was the start of the *ezdxf* package in 2011, but the progress was so slow, that I created a spin off in 2012 called *dxfgrabber*, which implements only the reading part of *ezdxf*, which I needed for my work and I wasn’t sure if *ezdxf* will ever be usable. Luckily in 2014 the first usable version of *ezdxf* could be released. The *ezdxf* package has all the features of *dxfwrite* and *dxfgrabber* and much more, but with a different API. So *ezdxf* is not a drop-in replacement for *dxfgrabber* or *dxfwrite*. Since *ezdxf* can do all the things that *dxfwrite* and *dxfgrabber* can do, I focused on the development of *ezdxf*, *dxfwrite* and *dxfgrabber* are in maintenance-only mode and will not get any new features, just bugfixes. There are no advantages of *dxfwrite* over *ezdxf*, *dxfwrite* has a smaller memory footprint, but the **r12writer** add-on does the same job as *dxfwrite* without any in-memory structures by writing direct to a stream or file and there is also no advantage of *dxfgrabber* over *ezdxf* for ordinary DXF files, the smaller memory footprint of *dxfgrabber* is not noticeable and for really big files the **iterdxf** add-on does a better job. ### Imported ezdxf package has no content. (readfile, new) - 1\. AttributeError: partially initialized module ‘ezdxf’ has no attribute ‘readfile’ (most likely due to a circular import) Did you name your file/script “ezdxf.py”? This causes problems with circular imports. Renaming your file/script should solve this issue. - 2\. AttributeError: module ‘ezdxf’ has no attribute ‘readfile’ This could be a hidden permission error, for more information about this issue read Petr Zemeks article: *https://blog.petrzemek.net/2020/11/17/when-you-import-a-python-package-and-it-is-empty/* ### How to add/edit ACIS based entities like 3DSOLID, REGION or SURFACE? The BODY, 3DSOLID, SURFACE, REGION and so on, are stored as ACIS data embedded in the DXF file. The ACIS data is stored as SAT (text) format in the entity itself for DXF R2000-R2010 and as SAB (binary) format in the ACDSDATA section for DXF R2013+. *Ezdxf* can read SAT and SAB data, but only write SAT data. The ACIS data is a proprietary format from *Spatial Inc.*, and there exist no free available documentation or open source libraries to create or edit SAT or SAB data, and also *ezdxf* provides no functionality for creating or editing ACIS data. The ACIS support provided by *ezdxf* is only useful for users which have access to the ACIS SDK from *Spatial Inc.*. ### Are OLE/OLE2 entities supported? TLDR; NO! The Wikipedia definition of *OLE*: Object Linking & Embedding (OLE) is a proprietary technology developed by Microsoft that allows embedding and linking to documents and other objects. For developers, it brought OLE Control Extension (OCX), a way to develop and use custom user interface elements. On a technical level, an OLE object is any object that implements the **IOleObject** interface, possibly along with a wide range of other interfaces, depending on the object’s needs. Therefore *ezdxf* does not support this entities in any way, this only work on Windows and with the required editing application installed. The binary data stored in the OLE objects cannot be used without the editing application. In my opinion, using OLE objects in a CAD drawing is a very bad design decision that can and will cause problems opening these files in the future, even in AutoCAD on Windows when the required editing application is no longer available or the underlying technology is no longer supported. All of this is unacceptable for a data storage format that should be accessed for many years or decades (e.g. construction drawings for buildings or bridges). ### Rendering SHX fonts The SHX font format is not documented nor supported by many libraries/packages like *Matplotlib* and *Qt*, therefore only SHX fonts which have corresponding TTF-fonts can be rendered by these backends. See also how-tos about *Fonts* ### Drawing Add-on There is a dedicated how-to section for the *Drawing Add-on*. ### Is the AutoCAD command XYZ available? TLDR; Would you expect Photoshop features from a JPG library? The package is designed as an interface to the DXF format and therefore does not offer any advanced features of interactive CAD applications. First, some tasks are difficult to perform without human guidance, and second, in complex situations, it’s not that easy to tell a “headless” system what exactly to do, so it’s very likely that not many users would ever use these features, despite the fact that a lot of time and effort would have to be spent on development, testing and long-term support. ### Recognize New Installed Fonts - • *Knowledge Graph* ### Why are ARC coordinates wrong? - • *Knowledge Graph* - • *Github FAQ #1266* ## GLOSSARY - **ACI** *AutoCAD Color Index (ACI)* - **ACIS** The 3D ACIS Modeler (*ACIS*) is a geometric modeling kernel developed by *Spatial Corp.* ® (formerly *Spatial Technology*) and now part of *Dassault Systems*. All ACIS based DXF entities store their geometry as *SAT* or *SAB* data. These are not open data formats and a license has to be purchased to get access to their SDK, therefore *ezdxf* can not provide any support for creating, processing or transforming of ACIS based DXF entities. - **bulge** The *Bulge value* is used to create arc shaped line segments in *Polyline* and *LWPolyline* entities. - **CAD** Computer-Assisted Drafting or Computer-Aided Design - **CTB** Color dependent plot style table (**ColorDependentPlotStyles**) - **DWG** Proprietary file format of *AutoCAD* ®. Documentation for this format is available from the Open Design Alliance (*ODA*) at their *Downloads* section. This documentation is created by reverse engineering therefore not perfect nor complete. - **DXF** Drawing eXchange Format is a file format used by *AutoCAD* ® to interchange data with other *CAD* applications. *DXF* is a trademark of *Autodesk* ®. See also *What is DXF?* - **proxy-graphic** The proxy-graphic is an internal data format to add a graphical representation to DXF entities which are unknown (custom DXF entities), not documented or very complex so CAD applications can display them without knowledge about the internal structure of these entities. - **raw-color** Raw color value as stored in DWG files, this integer value can represent *ACI* values as well as and *true-color* values - **reliable CAD application** CAD applications which create valid DXF documents in the meaning and interpretation of *Autodesk*. See also *What is DXF?* - **SAB** ACIS file format (Standard ACIS Binary), binary stored data - **SAT** ACIS file format (Standard ACIS Text), data stored as ASCII text - **STB** Named plot style table (**NamedPlotStyles**) - **true-color** RGB color representation, a combination red, green and blue values to define a color. ## KNOWLEDGE GRAPH I have started managing notes and documents that are not included in the *ezdxf* documentation in *Logseq* in late 2023. It works like a wiki but does not require a backend server. The Information is edited as Markdown files, which is much more intuitive than reStructured Text, and the content is stored in local files. The notes are included in the source code repository on Github in the *notes folder*. A published edition of this Knowledge Graph is included on the *ezdxf* website and is accessible by the link *https://ezdxf.mozman.at/notes*. The Knowledge Graph includes: - • *Release Notes* of future releases and some versions back - • *CHANGELOG* - • *IDEAS* for future releases - • *FAQ* and the *HOWTO* sections from this documentation - • all my notes to *ezdxf* - • In the future the *DXF Internals* section from this documentation may also move to the Knowledge Graph. Logseq’s outline structure is not ideal for all the documents I want to include, but I chose *Logseq* over *Obsidian.md* because it is open source and can publish the knowledge graph as a static website, static in the sense of no server-side code execution. This feature is important to me for hosting the content of the Knowledge Graph on the *ezdxf\`* website and cannot be achieved for free with *Obsidian.md*. *Logseq* is an *Electron* application that runs on all platforms, with the disadvantage: it’s an *Electron* application. ## INDICES AND TABLES - • *Index* - • *Search Page* ## AUTHOR Manfred Moitzi ## COPYRIGHT 2011-2025, Manfred Moitzi