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

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