Custom XRecord

The UserRecord and BinaryRecord classes help to store custom data in DXF files in XRecord objects a simple and safe way. This way requires DXF version R2000 or later, for DXF version R12 the only way to store custom data is Extended Data (XDATA).

The UserRecord stores Python types and nested container types: int, float, str, Vec2, Vec3, list and dict.

Requirements for Python structures:

The top level structure has to be a list.
Strings has to have max. 2049 characters and can not contain line breaks "\\n" or "\\r".
Dict keys have to be simple Python types: int, float, str.

DXF Tag layout for Python types and structures stored in the XRecord object:

Only for the UserRecord the first tag is (2, user record name).

Type	DXF Tag(s)
str	(1, value) string with less than 2050 chars and including no line breaks
int	(90, value) int 32-bit, restricted by the DXF standard not by Python!
float	(40, value) “C” double
Vec2	(10, x), (20, y)
Vec3	(10, x) (20, y) (30, z)
list	starts with (2, “[”) and ends with (2, “]”)
dict	starts with (2, “{”) and ends with (2, “}”)

The BinaryRecord stores arbitrary binary data as BLOB.

Storage size limits of XRECORD according the DXF reference:

“This object is similar in concept to XDATA but is not limited by size or order.”

For usage look at this example at github or go to the tutorial: Storing Custom Data in DXF Files.

UserRecord

class ezdxf.urecord.UserRecord

xrecord: The underlying XRecord instance

name: The name of the UserRecord, an arbitrary string with less than 2050 chars and including no line breaks.

data

The Python data. The top level structure has to be a list (MutableSequence). Inside this container the following Python types are supported: str, int, float, Vec2, Vec3, list, dict

Nested data structures are supported list or/and dict in list or dict. Dict keys have to be simple Python types: int, float, str.

property handle: str | None: DXF handle of the underlying XRecord instance.

__init__(xrecord: XRecord | None = None, *, name: str = DEFAULT_NAME, doc: Drawing | None = None)

Setup a UserRecord with the given name.

The data is stored in the given xrecord object, or in a new created XRecord instance if None. If doc is not None the new xrecord is added to the OBJECTS section of the DXF document.

Changes of the content has to be committed at the end to be stored in the underlying xrecord object.

Parameters:

xrecord (XRecord) – underlying XRecord instance, if None a new one will be created
name (str) – name of the user list
doc (Drawing) – DXF document or None

__str__(): Return str(self).

commit() → XRecord

Store data in the underlying XRecord instance. This call is not required if using the class by the with statement.

Raises:

DXFValueError – invalid chars "\n" or "\r" in a string
DXFTypeError – invalid data type

BinaryRecord

class ezdxf.urecord.BinaryRecord

xrecord: The underlying XRecord instance

data: The binary data as bytes, bytearray or memoryview.

property handle: str | None: DXF handle of the underlying XRecord instance.

__init__(xrecord: XRecord | None = None, *, doc: Drawing | None = None)

Setup a BinaryRecord.

The data is stored in the given xrecord object, or in a new created XRecord instance if None. If doc is not None the new xrecord is added to the OBJECTS section of the DXF document.

Changes of the content has to be committed at the end to be stored in the underlying xrecord object.

Parameters:

xrecord (XRecord) – underlying XRecord instance, if None a new one will be created
doc (Drawing) – DXF document or None

__str__() → str: Return str(self).

commit() → XRecord: Store binary data in the underlying XRecord instance. This call is not required if using the class by the with statement.