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.

High Level Functions

ezdxf.xref.attach(doc: Drawing, *, block_name: str, filename: str, insert: UVec = (0, 0, 0), scale: float = 1.0, rotation: float = 0.0, overlay=False) → 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

ValueError – block with same name exist

New in version 1.1.

ezdxf.xref.define(doc: 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

ValueError – block with same name exist

New in version 1.1.

ezdxf.xref.detach(block: BlockLayout, *, xref_filename: str) → 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[Callable[[str], Drawing]] = None, search_paths: Iterable[pathlib.Path | str] = tuple(), conflict_policy=ConflictPolicy.XREF_PREFIX) → 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

  • ValueError – 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: Drawing, tdoc: Drawing, filter_fn: Optional[Callable[[DXFEntity], bool]] = None, conflict_policy=ConflictPolicy.KEEP) → 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: Paperspace, tdoc: Drawing, filter_fn: Optional[Callable[[DXFEntity], bool]] = None, conflict_policy=ConflictPolicy.KEEP) → 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[DXFEntity], *, origin: UVec = (0, 0, 0)) → 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

ValueError – 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: Drawing, tdoc: Drawing, conflict_policy=ConflictPolicy.KEEP)

Load entities and resources from the source DXF document sdoc into a target DXF document.