Drawing Object

class Drawing

The Drawing class manages all entities and tables related to a DXF drawing. Every drawing has its own character encoding which is only important for saving to disk.

Drawing Attributes


contains the DXF version as string like 'AC1009', set by the new() or the readfile() function. (read only)


contains the AutoCAD release number string like 'R12' or 'R2000' that introduced the DXF version of this drawing. (read only)


DXF drawing text encoding, the default encoding for new drawings is 'cp1252'. Starting with DXF version R2007 (AC1021) DXF files are written as UTF-8 encoded text files, regardless of the attribute Drawing.encoding (read/write) 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

Contains the drawing filename, if the drawing was opened with the readfile() function else set to None. (read/write)


DXF entity creation factory, see also DXFFactory (read only).


Collection of all existing sections of a DXF drawing.


Shortcut for Drawing.sections.header

Reference to the HeaderSection of the drawing, where you can change the drawing settings.


Shortcut for Drawing.sections.entities

Reference to the EntitySection of the drawing, where all graphical entities are stored, but only from model space and the active layout (paper space). Just for your information: Entities of other layouts are stored as blocks in the BlocksSection.


Shortcut for Drawing.sections.blocks

Reference to the blocks section, see also BlocksSection.


Reference to the layout management object, see also Layouts.


requires DXF version R13 or later

Table (dict) of all groups used in this drawing, see also DXFGroupTable.


Shortcut for Drawing.sections.tables.layers

Reference to the layers table, where you can create, get and remove layers, see also Table and Layer


Shortcut for Drawing.sections.tables.styles

Reference to the styles table, see also Style.


Shortcut for Drawing.sections.tables.dimstyles

Reference to the dimstyles table, see also DimStyle.


Shortcut for Drawing.sections.tables.linetypes

Reference to the linetypes table, see also Linetype.


Shortcut for Drawing.sections.tables.views

Reference to the views table, see also View.


Shortcut for Drawing.sections.tables.viewports

Reference to the viewports table, see also Viewport.


Shortcut for Drawing.sections.tables.ucs

Reference to the ucs table, see also UCS.


Shortcut for Drawing.sections.tables.appids

Reference to the appids table, see also AppID.


Indicates if binary data is compressed in memory. see: Drawing.compress_binary_data()

Drawing Methods


Get the model space layout, see also Layout.


Get a paper space layout by name, see also Layout. (DXF version AC1009, supports only one paper space layout, so name is ignored)


Get a list of available paper space layouts.

Drawing.new_layout(name, dxfattribs=None)

Create a new paper space layout name. Returns a Layout object. Available only for DXF version AC1015 or newer, AC1009 supports only one paper space.


Delete paper space layout name and all its entities. Available only for DXF version AC1015 or newer, AC1009 supports only one paper space and you can’t delete it.


Iterate over all layouts (mode space and paper space) and all block definitions.


Chain entity spaces of all layouts and blocks. Yields an iterator for all entities in all layouts and blocks.

Drawing.add_image_def(filename, size_in_pixel, name=None)

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, see Tutorial for Image and ImageDef. name is the internal image name, if set to None, name is auto-generated.

  • filename – image file name
  • size_in_pixel – image size in pixel as (x, y) tuple
  • name – image name for internal use, None for an auto-generated name
Drawing.add_underlay_def(filename, format='pdf', name=None)

Add an UnderlayDef entity to the drawing (objects section). filename is the underlay file name as relative or absolute path and format as string (pdf, dwf, dgn). Returns a UnderlayDef entity which is needed to create an underlay reference, see Tutorial for Underlay and UnderlayDefinition. name defines the page/sheet to display.

  • filename – underlay file name
  • format – file format (pdf, dwf or dgn) or ext=get format from filename extension
  • name – pdf: page number to display; dgn: ‘default’; dwf: ????
Drawing.add_xref_def(filename, name)

Add an external reference (xref) definition to the blocks section.

Add xref to a layout by Layout.add_blockref().

  • filename – external reference filename
  • name – block name for the xref

Write drawing to file-system by using the filename attribute as filename. Overwrite 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:encoding – override file encoding
Drawing.saveas(filename, encoding='auto')

Write drawing to file-system by setting the filename attribute to filename. For argument encoding see: save().

  • filename – file name
  • encoding – override file encoding

Write drawing to a text stream. For DXF version R2004 (AC1018) and prior opened stream with encoding= Drawing.encoding and mode=’wt’. For DXF version R2007 (AC1021) and later use encoding=’utf-8’.


Cleanup drawing. Call it before saving the drawing but only if necessary, the process could take a while.

Parameters:groups – removes deleted and invalid entities from groups

If you don’t need access to binary data of DXF entities, you can compress them in memory for a smaller memory footprint, you can set ezdxf.options.compress_binray_data = True to compress binary data for every drawing you open, but data compression cost time, so this option isn’t active by default.


Entity query over all layouts and blocks. (see also: Name Query String and Retrieve Entities by Query Language)

Excluding the OBJECTS section!

Parameters:query – query string
Returns:EntityQuery container
Drawing.qroupby(dxfattrib="", key=None)

Groups DXF entities of all layouts and blocks by an DXF attribute or a key function. (see also: Retrieve Entities by groupby)

Excluding the OBJECTS section!

  • dxfattrib – grouping DXF attribute 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


Low Level Access to DXF entities


Get entity by handle from entity database. Low level access to DXF entities database. Raises DXFKeyError if handle doesn’t exist. Returns DXFEntity or inherited.

If you just need the raw DXF tags use:

tags = Drawing.entitydb[handle]  # raises DXFKeyError, if handle does not exist
tags = Drawing.entitydb.get(handle)  # returns a default value, if handle does not exist (None by default)

type of tags: ExtendedTags