!!! UNDER CONSTRUCTION !!!

Package Design for Developers

A DXF document is divided into several sections, this sections are managed by the Drawing object. For each section exist a corresponding attribute in the Drawing object:

Section Attribute
HEADER Drawing.header
CLASSES Drawing.classes
TABLES Drawing.tables
BLOCKS Drawing.blocks
ENTITIES Drawing.entities
OBJECTS Drawing.objects

Resource entities (LAYER, STYLE, LTYPE, …) are stored in tables in the TABLES section. A table owns the table entries, the owner handle of table entry is the handle of the table. Each table has a shortcut in the Drawing object:

Table Attribute
APPID Drawing.appids
BLOCK_RECORD Drawing.block_records
DIMSTYLE Drawing.dimstyles
LAYER Drawing.layers
LTYPE Drawing.linetypes
STYLE Drawing.styles
UCS Drawing.ucs
VIEW Drawing.views
VPORT Drawing.viewports

Graphical entities are stored in layouts: Modelspace, Paperspace layouts and BlockLayout. The core management object of this layouts is the BLOCK_RECORD entity (BlockRecord), the BLOCK_RECORD is the real owner of the entities, the owner handle of the entities is the handle of the BLOCK_RECORD and the BLOCK_RECORD also owns and manages the entity space of the layout which contains all entities of the layout.

For more information about layouts see also: Layout Management Structures

For more information about blocks see also: Block Management Structures

Non-graphical entities (objects) are stored in the OBJECTS section. Every object has a parent object in the OBJECTS section, most likely a DICTIONARY object, and is stored in the entity space of the OBJECTS section.

For more information about the OBJECTS section see also: OBJECTS Section

All table entries, DXF entities and DXF objects are stored in the entities database accessible as Drawing.entitydb. The entity database is a simple key, value storage, key is the entity handle, value is the DXF object.

For more information about the DXF data model see also: Data Model

Terminology

States

DXF entities and objects can have different states:

UNBOUND
Entity is not stored in the Drawing entity database and DXF attribute handle is None and attribute doc can be None
BOUND
Entity is stored in the Drawing entity database, attribute doc has a reference to Drawing and DXF attribute handle is not None
UNLINKED
Entity is not linked to a layout/owner, DXF attribute owner is None
LINKED
Entity is linked to a layout/owner, DXF attribute owner is not None
Virtual Entity
State: UNBOUND & UNLINKED
Unlinked Entity
State: BOUND & UNLINKED
Bound Entity
State: BOUND & LINKED

Actions

NEW
Create a new DXF document
LOAD
Load a DXF document from an external source
CREATE
Create DXF structures from NEW or LOAD data
DESTROY
Delete DXF structures
BIND
Bind an entity to a Drawing, set entity state to BOUND & UNLINKED and check or create required resources
UNBIND
unbind …
LINK
Link an entity to an owner/layout. This makes an entity to a real DXF entity, which will be exported at the saving process. Any DXF entity can only be linked to one parent entity like DICTIONARY or BLOCK_RECORD.
UNLINK
unlink …

Loading a DXF Document

Loading a DXF document from an external source, creates a new Drawing object. This loading process has two stages:

First Loading Stage

  • LOAD content from external source as SectionDict: loader.load_dxf_structure()
  • LOAD tag structures as DXFEntity objects: loader.load_dxf_entities()
  • BIND entities: loader.load_and_bind_dxf_content(); Special handling of the BIND process, because the Drawing is not full initialized, a complete validation is not possible at this stage.

Second Loading Stage

Parse SectionDict:

  • CREATE sections: HEADER, CLASSES, TABLES, BLOCKS and OBJECTS
  • CREATE layouts: Blocks, Layouts
  • LINK entities to a owner/layout

The ENTITIES section is a relict from older DXF versions and has to be exported including the modelspace and active paperspace entities, but all entities reside in a BLOCK definition, even modelspace and paperspace layouts are only BLOCK definitions and ezdxf has no explicit ENTITIES section.

Source Code: as developer start your journey at ezdxf.document.Drawing.read(), which has no public documentation, because package-user should use ezdxf.read() and ezdxf.readfile().

New DXF Document

Creating New DXF Entities

The default constructor of each entity type creates a new virtual entity:

  • DXF attribute owner is None
  • DXF attribute handle is None
  • Attribute doc is None

The DXFEntity.new() constructor creates entities with given owner, handle and doc attributes, if doc is not None and entity is not already bound to a document, the new() constructor automatically bind the entity to the given document doc.

There exist only two scenarios:

  1. UNBOUND: doc is None and handle is None
  2. BOUND: doc is not None and handle is not None

Factory functions

  • new(), create a new virtual DXF object/entity
  • load(), load (create) virtual DXF object/entity from DXF tags
  • bind(), bind an entity to a document, create required resources if necessary (e.g. ImageDefReactor, SEQEND) and raise exceptions for non-existing resources.
    • Bind entity loaded from an external source to a document, all referenced resources must exist, but try to repair as many flaws as possible because errors were created by another application and are not the responsibility of the package-user.
    • Bind an entity from another DXF document, all invalid resources will be removed silently or created (e.g. SEQEND). This is a simple import from another document without resource import, for a more advanced import including resources exist the importer add-on.
    • Bootstrap problem for binding loaded table entries and objects in the OBJECTS section! Can’t use Auditor to repair this objects, because the DXF document is not fully initialized.
  • is_bound() returns True if entity is bound to document doc
  • unbind() function to remove an entity from a document and set state to a virtual entity, which should also UNLINK the entity from layout, because an layout can not store a virtual entity.
  • cls(), returns the class
  • register_entity(), registration decorator
  • replace_entity(), registration decorator

Class Interfaces

DXF Entities

  • NEW constructor to create an entity from scratch
  • LOAD constructor to create an entity loaded from an external source
  • DESTROY interface to kill an entity, set entity state to dead, which means entity.is_alive returns False. All entity iterators like EntitySpace, EntityQuery, and EntityDB must filter (ignore) dead entities. Calling DXFEntity.destroy() is a regular way to delete entities.
  • LINK an entity to a layout by BlockRecord.link(), which set the owner handle to BLOCK_RECORD handle (= layout key) and add the entity to the entity space of the BLOCK_RECORD and set/clear the paperspace flag.

DXF Objects

  • NEW, LOAD, DESTROY see DXF entities
  • LINK: Linking an DXF object means adding the entity to a parent object in the OBJECTS section, most likely a DICTIONARY object, and adding the object to the entity space of the OBJECTS section, the root-dict is the only entity in the OBJECTS section which has an invalid owner handle “0”. Any other object with an invalid or destroyed owner is an orphaned entity. The audit process destroys and removes orphaned objects.
  • Extension dictionaries (ACAD_XDICTIONARY) are DICTIONARY objects located in the OBJECTS sections and can reference/own other entities of the OBJECTS section.
  • The root-dictionary is the only entity in the OBJECTS section which has an invalid owner handle “0”. Any other object with an invalid or destroyed owner is an orphaned entity.

Layouts

  • LINK interface to link an entity to a layout
  • UNLINK interface to remove an entity from a layout

Database

  • BIND interface to add an entity to the database of a document
  • delete_entity() interface, same as UNBIND and DESTROY an entity