Insert¶
Block reference (DXF Reference) with maybe attached attributes (Attrib
).
Subclass of |
|
DXF type |
|
Factory function |
|
Inherited DXF attributes |
See also
Warning
Do not instantiate entity classes by yourself - always use the provided factory functions!
TODO: influence of layer, linetype, color DXF attributes to block entities
- class ezdxf.entities.Insert¶
- dxf.name¶
BLOCK name (str)
- dxf.xscale¶
Scale factor for x direction (float)
- dxf.yscale¶
Scale factor for y direction (float)
Not all CAD applications support non-uniform scaling (e.g. LibreCAD).
- dxf.zscale¶
Scale factor for z direction (float)
Not all CAD applications support non-uniform scaling (e.g. LibreCAD).
- dxf.rotation¶
Rotation angle in degrees (float)
- dxf.row_count¶
Count of repeated insertions in row direction, MINSERT entity if > 1 (int)
- dxf.row_spacing¶
Distance between two insert points (MINSERT) in row direction (float)
- dxf.column_count¶
Count of repeated insertions in column direction, MINSERT entity if > 1 (int)
- dxf.column_spacing¶
Distance between two insert points (MINSERT) in column direction (float)
- has_scaling¶
Returns
True
if any axis scaling is applied.
- has_uniform_scaling¶
Returns
True
if scaling is uniform in x-, y- and z-axis ignoring reflections e.g. (1, 1, -1) is uniform scaling.
- mcount¶
Returns the multi-insert count, MINSERT (multi-insert) processing is required if
mcount
> 1.
- set_scale(factor: float)¶
Set uniform scaling.
- block() Optional[BlockLayout] ¶
Returns associated
BlockLayout
.
- place(insert: Vertex = None, scale: Tuple[float, float, float] = None, rotation: float = None) Insert ¶
Set block reference placing location insert, scaling and rotation attributes. Parameters which are
None
will not be altered.- Parameters
insert – insert location as
(x, y [,z])
tuplescale –
(x-scale, y-scale, z-scale)
tuplerotation – rotation angle in degrees
- grid(size: Tuple[int, int] = (1, 1), spacing: Tuple[float, float] = (1, 1)) Insert ¶
Place block reference in a grid layout, grid size defines the row- and column count, spacing defines the distance between two block references.
- Parameters
size – grid size as
(row_count, column_count)
tuplespacing – distance between placing as
(row_spacing, column_spacing)
tuple
- has_attrib(tag: str, search_const: bool = False) bool ¶
Returns
True
if ATTRIB tag exist, for search_const doc seeget_attrib()
.- Parameters
tag – tag name as string
search_const – search also const ATTDEF entities
- get_attrib(tag: str, search_const: bool = False) Optional[Union[Attrib, AttDef]] ¶
Get attached
Attrib
entity withdxf.tag == tag
, returnsNone
if not found. Some applications may not attach constant ATTRIB entities, set search_const toTrue
, to get at least the associatedAttDef
entity.- Parameters
tag – tag name
search_const – search also const ATTDEF entities
- get_attrib_text(tag: str, default: str = '', search_const: bool = False) str ¶
Get content text of attached
Attrib
entity withdxf.tag == tag
, returns default if not found. Some applications may not attach constant ATTRIB entities, set search_const toTrue
, to get content text of the associatedAttDef
entity.- Parameters
tag – tag name
default – default value if ATTRIB tag is absent
search_const – search also const ATTDEF entities
- add_attrib(tag: str, text: str, insert: UVec = (0, 0), dxfattribs=None) Attrib ¶
Attach an
Attrib
entity to the block reference.Example for appending an attribute to an INSERT entity with none standard alignment:
e.add_attrib('EXAMPLETAG', 'example text').set_placement( (3, 7), align=TextEntityAlignment.MIDDLE_CENTER )
- Parameters
tag – tag name as string
text – content text as string
insert – insert location as tuple
(x, y[, z])
in WCSdxfattribs – additional DXF attributes for the ATTRIB entity
- add_auto_attribs(values: Dict[str, str]) Insert ¶
Attach for each
Attdef
entity, defined in the block definition, automatically anAttrib
entity to the block reference and settag/value
DXF attributes of the ATTRIB entities by thekey/value
pairs (both as strings) of the values dict. The ATTRIB entities are placed relative to the insert location of the block reference, which is identical to the block base point.This method avoids the wrapper block of the
add_auto_blockref()
method, but the visual results may not match the results of CAD applications, especially for non uniform scaling. If the visual result is very important to you, use theadd_auto_blockref()
method.- Parameters
values –
Attrib
tag values astag/value
pairs
- delete_attrib(tag: str, ignore=False) None ¶
Delete an attached
Attrib
entity from INSERT. If ignore isFalse
, anDXFKeyError
exception is raised, if ATTRIB tag does not exist.- Parameters
tag – ATTRIB name
ignore –
False
for raisingDXFKeyError
if ATTRIB tag does not exist.
- Raises
DXFKeyError – if ATTRIB tag does not exist.
- reset_transformation() None ¶
Reset block reference parameters location, rotation and extrusion vector.
- transform(m: Matrix44) Insert ¶
Transform INSERT entity by transformation matrix m inplace.
Unlike the transformation matrix m, the INSERT entity can not represent a non orthogonal target coordinate system, for this case an
InsertTransformationError
will be raised.
- translate(dx: float, dy: float, dz: float) Insert ¶
Optimized INSERT translation about dx in x-axis, dy in y-axis and dz in z-axis.
- virtual_entities(skipped_entity_callback: Optional[Callable[[DXFGraphic, str], None]] = None) Iterable[DXFGraphic] ¶
Yields “virtual” entities of a block reference. This method is meant to examine the block reference entities at the “exploded” location without really “exploding” the block reference. The`skipped_entity_callback()` will be called for all entities which are not processed, signature:
skipped_entity_callback(entity: DXFEntity, reason: str)
, entity is the original (untransformed) DXF entity of the block definition, the reason string is an explanation why the entity was skipped.This entities are not stored in the entity database, have no handle and are not assigned to any layout. It is possible to convert this entities into regular drawing entities by adding the entities to the entities database and a layout of the same DXF document as the block reference:
doc.entitydb.add(entity) msp = doc.modelspace() msp.add_entity(entity)
This method does not resolve the MINSERT attributes, only the sub-entities of the base INSERT will be returned. To resolve MINSERT entities check if multi insert processing is required, that’s the case if property
Insert.mcount
> 1, use theInsert.multi_insert()
method to resolve the MINSERT entity into single INSERT entities.Warning
Non uniform scaling may return incorrect results for text entities (TEXT, MTEXT, ATTRIB) and maybe some other entities.
- Parameters
skipped_entity_callback – called whenever the transformation of an entity is not supported and so was skipped
- multi_insert() Iterable[Insert] ¶
Yields a virtual INSERT entity for each grid element of a MINSERT entity (multi-insert).
- explode(target_layout: BaseLayout = None) EntityQuery ¶
Explode block reference entities into target layout, if target layout is
None
, the target layout is the layout of the block reference. This method destroys the source block reference entity.Transforms the block entities into the required WCS location by applying the block reference attributes insert, extrusion, rotation and the scaling values xscale, yscale and zscale.
Attached ATTRIB entities are converted to TEXT entities, this is the behavior of the BURST command of the AutoCAD Express Tools.
Returns an
EntityQuery
container with all “exploded” DXF entities.Warning
Non uniform scaling may lead to incorrect results for text entities (TEXT, MTEXT, ATTRIB) and maybe some other entities.
- Parameters
target_layout – target layout for exploded entities,
None
for same layout as source entity.
- ucs()¶
Returns the block reference coordinate system as
ezdxf.math.UCS
object.