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