Drawing Class

The Drawing class is the central management structure of a DXF document.

Access Layouts

Access Resources

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.

get_abs_filepath = <function Drawing.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.