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: 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
- 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 theodafc
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 thereadfile()
function from theezdxf.addons.odafc
add-on. Theezdxf.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 documentload_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 orFalse
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 orFalse
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.