External References (XREF)¶

New in version 1.1.

Attached XREFs are links to the modelspace of a specified drawing file. Changes made to the referenced drawing are automatically reflected in the current drawing when it’s opened or if the XREF is reloaded.

XREFs can be nested within other XREFs: that is, you can attach an XREF that contains another XREF. You can attach as many copies of an XREF as you want, and each copy can have a different position, scale, and rotation.

You can also overlay an XREF on your drawing. Unlike an attached XREF, an overlaid XREF is not included when the drawing is itself attached or overlaid as an XREF to another drawing.

DXF Files as Attached XREFs¶

AutoCAD can only display DWG files as attached XREFs, which is a problem since ezdxf can only create DXF files. Consequently, any DXF file attached as XREF to a DXF document has be converted to DWG in order to be viewed in AutoCAD.

Fortunately, other CAD applications are more cooperative, so BricsCAD has no problem displaying DXF files as XREFs, although it is not possible to attach a DXF file as an XREF in the BricsCAD application itself.

The ezdxf.xref module provides an interface for working with XREFs.

attach() - attach a DXF/DWG file as XREF

detach() - detach a BLOCK definition as XREF

embed() - embed an XREF as a BLOCK definition

dxf_info() - scans a DXF file for basic settings and properties

For loading the content of DWG files is a loading function required, which loads the DWG file as Drawing document. The odafc add-on module provides such a function: readfile()

Importing Data and Resources¶

The ezdxf.xref module replaces the Importer add-on.

The basic functionality of the ezdxf.xref module is loading data from external files including their required resources, which is an often requested feature by users for importing data from other DXF files into the current document.

The Importer add-on was very limited and removed many resources, where the ezdxf.xref module tries to preserve as much information as possible.

load_modelspace() - loads the modelspace content from another DXF document

load_paperspace() - loads a paperspace layout from another DXF document

write_block() - writes entities into the modelspace of a new DXF document

Loader - low level loading interface

High Level Functions¶

ezdxf.xref.attach(doc: ezdxf.document.Drawing, *, block_name: str, filename: str, insert: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = (0, 0, 0), scale: float = 1.0, rotation: float = 0.0, overlay=False) → ezdxf.entities.insert.Insert¶

Attach the file filename to the host document as external reference (XREF) and creates a default block reference for the XREF in the modelspace of the document. The function raises a ValueError exception if the block definition already exist, but an XREF can be inserted multiple times by adding additional block references:

msp.add_blockref(block_name, insert=another_location)

Important

If the XREF has different drawing units than the host document, the scale factor between these units must be applied as a uniform scale factor to the block reference! Unfortunately the XREF drawing units can only be detected by scanning the HEADER section of a document by the function dxf_info() and is therefore not done automatically by this function. Advice: always use the same units for all drawings of a project!

Parameters:	doc – host DXF document block_name – name of the XREF definition block filename – file name of the XREF insert – location of the default block reference scale – uniform scaling factor rotation – rotation angle in degrees overlay – creates an XREF overlay if `True` and an XREF attachment otherwise
Returns:	default block reference for the XREF
Return type:	Insert
Raises:	`XrefDefinitionError` – block with same name exist

New in version 1.1.

ezdxf.xref.define(doc: ezdxf.document.Drawing, block_name: str, filename: str, overlay=False) → None¶

Add an external reference (xref) definition to a document.

XREF attachment types:

attached: the XREF that’s inserted into this drawing is also present in a document to which this document is inserted as an XREF.
overlay: the XREF that’s inserted into this document is not present in a document to which this document is inserted as an XREF.

Parameters:	doc – host document block_name – name of the xref block filename – external reference filename overlay – creates an XREF overlay if `True` and an XREF attachment otherwise
Raises:	`XrefDefinitionError` – block with same name exist

New in version 1.1.

ezdxf.xref.detach(block: ezdxf.layouts.blocklayout.BlockLayout, *, xref_filename: str) → ezdxf.document.Drawing¶

Write the content of block into the modelspace of a new DXF document and convert block to an external reference (XREF). The new DXF document has to be written by the caller: xref_doc.saveas(xref_filename). This way it is possible to convert the DXF document to DWG by the odafc add-on if necessary:

xref_doc = xref.detach(my_block, "my_block.dwg")
odafc.export_dwg(xref_doc, "my_block.dwg")

Parameters:	block – block definition to detach xref_filename – name of the external referenced file

New in version 1.1.

ezdxf.xref.dxf_info(filename: str | os.PathLike) → DXFInfo¶

Scans the HEADER section of a DXF document and returns a DXFInfo object, which contains information about the DXF version, text encoding, drawing units and insertion base point.

Raises:	`IOError` – not a DXF file or a generic IO error

ezdxf.xref.embed(xref: BlockLayout, *, load_fn: Optional[LoadFunction] = None, search_paths: Iterable[pathlib.Path | str] = (), conflict_policy=<ConflictPolicy.XREF_PREFIX: 2>) → None¶

Loads the modelspace of the XREF as content into a block layout.

The loader function loads the XREF as Drawing object, by default the function ezdxf.readfile() is used to load DXF files. To load DWG files use the readfile() function from the ezdxf.addons.odafc add-on. The ezdxf.recover.readfile() function is very robust for reading DXF files with errors.

If the XREF path isn’t absolute the XREF is searched in the folder of the host DXF document and in the search_path folders.

Parameters:	xref – `BlockLayout` of the XREF document load_fn – function to load the content of the XREF as Drawing object search_paths – list of folders to search for XREFS, default is the folder of the host document or the current directory if no filepath is set conflict_policy – how to resolve name conflicts
Raises:	`XrefDefinitionError` – argument xref is not a XREF definition `FileNotFoundError` – XREF file not found `DXFVersionError` – cannot load a XREF with a newer DXF version than the host document, try the `odafc` add-on to downgrade the XREF document or upgrade the host document

New in version 1.1.

ezdxf.xref.load_modelspace(sdoc: ezdxf.document.Drawing, tdoc: ezdxf.document.Drawing, filter_fn: Optional[Callable[[ezdxf.entities.dxfentity.DXFEntity], bool]] = None, conflict_policy=<ConflictPolicy.KEEP: 1>) → None¶

Loads the modelspace content of the source document into the modelspace of the target document. The filter function filter_fn gets every source entity as input and returns True to load the entity or False otherwise.

Parameters:	sdoc – source document tdoc – target document filter_fn – optional function to filter entities from the source modelspace conflict_policy – how to resolve name conflicts

ezdxf.xref.load_paperspace(psp: ezdxf.layouts.layout.Paperspace, tdoc: ezdxf.document.Drawing, filter_fn: Optional[Callable[[ezdxf.entities.dxfentity.DXFEntity], bool]] = None, conflict_policy=<ConflictPolicy.KEEP: 1>) → None¶

Loads the paperspace layout psp into the target document. The filter function filter_fn gets every source entity as input and returns True to load the entity or False otherwise.

Parameters:	psp – paperspace layout to load tdoc – target document filter_fn – optional function to filter entities from the source paperspace layout conflict_policy – how to resolve name conflicts

ezdxf.xref.write_block(entities: Sequence[ezdxf.entities.dxfentity.DXFEntity], *, origin: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = (0, 0, 0)) → ezdxf.document.Drawing¶

Write entities into the modelspace of a new DXF document.

This function is called “write_block” because the new DXF document can be used as an external referenced block. This function is similar to the WBLOCK command in CAD applications.

Virtual entities are not supported, because each entity needs a real database- and owner handle.

Parameters:	entities – DXF entities to write origin – block origin, defines the point in the modelspace which will be inserted at the insert location of the block reference
Raises:	`EntityError` – virtual entities are not supported

New in version 1.1.

Conflict Policy¶

class ezdxf.xref.ConflictPolicy¶

KEEP¶

XREF_PREFIX¶

NUM_PREFIX¶

Low Level Loading Interface¶

class ezdxf.xref.Loader(sdoc: ezdxf.document.Drawing, tdoc: ezdxf.document.Drawing, conflict_policy=<ConflictPolicy.KEEP: 1>)¶: Load entities and resources from the source DXF document sdoc into a target DXF document.