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 files from a file:
doc = ezdxf.readfile(filename)
or from a zip-file:
doc = ezdxf.readzip(zipfilename[, filename])
Which loads the DXF file filename from the zip-file zipfilename or the first DXF file in the zip-file if filename is absent.
It is also possible to read a DXF file from a stream by the ezdxf.read()
function, but this is a more advanced feature, because this requires detection
of the file encoding in advance.
This works well with DXF files from trusted sources like AutoCAD or BricsCAD,
for loading DXF files with minor or major flaws look at the
ezdxf.recover
module.
See also
Documentation for ezdxf.readfile()
, ezdxf.readzip()
and
ezdxf.read()
, for more information about file
management go to the Document Management section. For loading DXF files
with structural errors look at the ezdxf.recover
module.
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 a New DXF File¶
Create new file for the latest supported DXF version:
doc = ezdxf.new()
Create a new DXF file for a specific DXF version, e.g for DXF R12:
doc = ezdxf.new("R12")
To setup some basic DXF resources use the setup argument:
doc = ezdxf.new(setup=True)
See also
Documentation for ezdxf.new()
, for more information about file
management go to the Document Management section.
Layouts and Blocks¶
Layouts are containers for DXF entities like LINE or CIRCLE. The most important layout is the modelspace labeled as “Model” in CAD applications which represents the “world” work space. Paperspace layouts represents plottable sheets which contains often the framing and the tile block of a drawing and VIEWPORT entities as scaled and clipped “windows” into the modelspace.
The modelspace is always present and can not be deleted. The active paperspace is also always present in a new DXF document but can be deleted, in that case another paperspace layout gets the new active paperspace, but you can not delete the last paperspace layout.
Getting the modelspace of a DXF document:
msp = doc.modelspace()
Getting a paperspace layout by the name as shown in the tab of a CAD application:
psp = doc.layout("Layout1")
A block is just another kind of entity space, which can be inserted multiple times into other layouts and blocks by the INSERT entity also called block references, this is a very powerful and important concept of the DXF format.
Getting a block layout by the block name:
blk = doc.blocks.get("NAME")
All these layouts have factory functions to create graphical DXF entities for their entity space, for more information about creating entities see section: Create new DXF Entities
Create New Blocks¶
The block definitions of a DXF document are managed by the
BlocksSection
object:
my_block = doc.blocks.new("MyBlock")
See also
Query DXF Entities¶
As said in the Layouts and Blocks section, all graphical DXF entities are
stored in layouts, all these layouts can be iterated and support the index
operator e.g. layout[-1]
returns the last entity.
The main difference between iteration and index access is, that iteration filters
destroyed entities, but the index operator returns also destroyed entities
until these entities are purged by layout.purge()
more about this topic
in section: Delete Entities.
There are two advanced query methods: query()
and groupby()
.
Get all lines of layer "MyLayer"
:
lines = msp.query('LINE[layer=="MyLayer"]')
This returns an EntityQuery
container, which also provides
the same query()
and groupby()
methods.
Get all lines categorized by a DXF attribute like color:
all_lines_by_color = msp.query("LINE").groupby("color")
lines_with_color_1 = all_lines_by_color.get(1, [])
The groupby()
method returns a regular Python dict
with colors as
key and a regular Python list
of entities as values
(not an EntityQuery
container).
See also
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 DXF attributes are only indirect available like the
vertices in the LWPOLYLINE entity. More information about the DXF attributes of
each entity can found in the documentation of the ezdxf.entities
module.
Get some basic DXF attributes:
layer = entity.dxf.layer # default is "0"
color = entity.dxf.color # default is 256 = BYLAYER
Most DXF attributes have a default value, which will be returned if the DXF attribute is not present, for DXF attributes without a default value you can check in the attribute really exist:
entity.dxf.hasattr("true_color")
or use the get()
method and a default value:
entity.dxf.get("true_color", 0)
See also
Create New DXF Entities¶
The factory methods for creating new graphical DXF entities are located in the
BaseLayout
class. This means this factory methods are
available for all entity containers:
The usage is simple:
msp = doc.modelspace()
msp.add_line((0, 0), (1, 0), dxfattribs={"layer": "MyLayer"})
A few important or required DXF attributes are explicit method arguments,
most additional and optional DXF attributes are gives as a regular Python
dict
object.
The supported DXF attributes can be found in the documentation of the
ezdxf.entities
module.
Warning
Do not instantiate DXF entities by yourself and add them to layouts, always use the provided factory function to create new graphical entities, this is the intended way to use ezdxf.
Create Block References¶
A block reference is just another DXF entity called INSERT, but the term
“Block Reference” is a better choice and so the Insert
entity is created by the factory function:
add_blockref()
:
msp.add_blockref("MyBlock", (0, 0))
See also
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 this entity can inherit some properties from this
Layer
object.
Layer objects are stored in the layer table which is available as
attribute doc.layers
.
You can create your own layers:
my_layer = doc.layer.add("MyLayer")
The layer object also controls the visibility of entities which references this
layer, the on/off state of the layer is unfortunately stored as positive or
negative color value which make the raw DXF attribute of layers useless, to
change the color of a layer use the property Layer.color
my_layer.color = 1
To change the state of a layer use the provided methods of the
Layer
object, like
on()
, off()
,
freeze()
or thaw()
:
my_layer.off()
See also
Delete Entities¶
The safest way to delete entities is to delete the entity from the layout containing that entity:
line = msp.add_line((0, 0), (1, 0))
msp.delete_entity(line)
This removes the entity immediately from the layout and destroys the entity.
The property is_alive
returns False
for a
destroyed entity and all Python attributes are deleted, so
line.dxf.color
will raise an AttributeError
exception,
because line
does not have a dxf
attribute anymore.
Ezdxf also supports also destruction of entities
by calling method destroy()
manually:
line.destroy()
Manually destroyed entities are not removed
immediately from entities containers like Modelspace
or
EntityQuery
, but iterating such a container will filter destroyed
entities automatically, so a for e in msp: ...
loop
will never yield destroyed entities. The index operator and the len()
function do not filter deleted entities, to avoid getting deleted entities
call the purge()
method of the container manually to remove deleted
entities.
Further Information¶
Reference documentation
Documentation of package internals: Developer Guides.