!!! UNDER CONSTRUCTION !!!
Package Design for Developers¶
A DXF document is divided into several sections, this sections are managed by
Drawing object. For each section exist a
corresponding attribute in the
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
Graphical entities are stored in layouts:
The core management object of this layouts is the BLOCK_RECORD entity
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
DXF entities and objects can have different states:
- Entity is not stored in the
Drawingentity database and DXF attribute
- Entity is stored in the
Drawingentity database, attribute
dochas a reference to
Drawingand DXF attribute
- Entity is not linked to a layout/owner,
- Entity is linked to a layout/owner,
- Virtual Entity
- State: UNBOUND & UNLINKED
- Unlinked Entity
- State: BOUND & UNLINKED
- Bound Entity
- State: BOUND & LINKED
- Create a new DXF document
- Load a DXF document from an external source
- Create DXF structures from NEW or LOAD data
- Delete DXF structures
- Bind an entity to a
Drawing, set entity state to BOUND & UNLINKED and check or create required resources
- unbind …
- 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 …
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
- LOAD tag structures as
- BIND entities:
loader.load_and_bind_dxf_content(); Special handling of the BIND process, because the
Drawingis not full initialized, a complete validation is not possible at this stage.
Second Loading Stage¶
- 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.
New DXF Document¶
Creating New DXF Entities¶
The default constructor of each entity type creates a new virtual entity:
- DXF attribute owner is
- DXF attribute handle is
- Attribute doc is
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:
- UNBOUND: doc is
Noneand handle is
- BOUND: doc is not
Noneand handle is not
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
- Bootstrap problem for binding loaded table entries and objects in the OBJECTS
section! Can’t use
Auditorto 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
- 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
entity.is_alivereturns False. All entity iterators like
EntityDBmust 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.
- 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.
- LINK interface to link an entity to a layout
- UNLINK interface to remove an entity from a layout
- BIND interface to add an entity to the database of a document
delete_entity()interface, same as UNBIND and DESTROY an entity