Class AcDbBlockReference

Represents a block reference entity in AutoCAD.

A block reference is used to place, size, and display an instance of the collection of entities within the block table record that it references. Block references allow you to reuse complex geometry by referencing a block definition multiple times with different positions, rotations, and scales.

Example

// Create a block reference
const blockRef = new AcDbBlockReference("MyBlock");
blockRef.position = new AcGePoint3d(10, 20, 0);
blockRef.rotation = Math.PI / 4; // 45 degrees
blockRef.scaleFactors = new AcGePoint3d(2, 2, 1); // 2x scale

// Access block reference properties
console.log(`Block name: ${blockRef.blockTableRecord?.name}`);
console.log(`Position: ${blockRef.position}`);
console.log(`Rotation: ${blockRef.rotation}`);

Hierarchy (View Summary)

AcDbEntity
- AcDbBlockReference
  - AcDbTable

Constructors

constructor

new AcDbBlockReference(blockName: string): AcDbBlockReference
Creates a new block reference entity.

This constructor initializes a block reference with the specified block name. The position is set to the origin, rotation to 0, normal to Z-axis, and scale factors to 1.
Parameters
- blockName: string
  The name of the block table record to reference
Returns AcDbBlockReference
Example
```
const blockRef = new AcDbBlockReference("MyBlock");
blockRef.position = new AcGePoint3d(5, 10, 0);
blockRef.rotation = Math.PI / 6; // 30 degrees
```
Overrides AcDbEntity.constructor
- Defined in data-model/src/entity/AcDbBlockReference.ts:75

Properties

`Static`typeName

typeName: string = 'BlockReference'

The entity type name

Accessors

attrs

get attrs(): AcCmObject<ATTRS>
Gets the attributes object for this AcDbObject.

Returns AcCmObject<ATTRS>
The AcCmObject instance containing all attributes
Example
```
const attrs = obj.attrs;
const value = attrs.get('someAttribute');
```
Inherited from AcDbEntity.attrs
- Defined in data-model/src/base/AcDbObject.ts:80

blockTableRecord

get blockTableRecord(): undefined | AcDbBlockTableRecord
Gets the block table record referenced by this block reference.

The referenced block table record contains the entities that the block reference will display.

Returns undefined | AcDbBlockTableRecord
The block table record, or undefined if not found
Example
```
const blockRecord = blockRef.blockTableRecord;
if (blockRecord) {
  console.log(`Block name: ${blockRecord.name}`);
}
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:221

blockTransform

get blockTransform(): AcGeMatrix3d
Gets the block-local transformation matrix of this block reference.

This matrix represents the INSERT entity transform in Object Coordinate System (OCS), excluding the extrusion / normal transformation.

In AutoCAD, a block reference transform is conceptually applied in the following order:
1. Translate geometry by the negative block base point
2. Apply non-uniform scaling
3. Apply rotation about the block Z axis (OCS Z)
4. Translate to the insertion point
5. Finally, transform from OCS to WCS using the entity normal (extrusion)
This property returns the matrix for steps 1–4 only.

The OCS → WCS transformation derived from normal must NOT be included here, because:
- The rotation angle of an INSERT is defined in OCS
- Applying OCS earlier would rotate around an incorrect axis
- Cached block geometry must remain reusable for different normals
Therefore, the extrusion transformation is applied after rendering (see AcDbRenderingCache.draw), matching AutoCAD / RealDWG behavior.

Matrix composition (right-multiply convention)
```
blockTransform =
  T(position)
· R(rotation about OCS Z)
· S(scaleFactors)
· T(-blockBasePoint)
```
Notes
- The returned matrix operates in OCS space
- Rotation is always about the OCS Z axis
- normal is applied later as a final orientation step
- This mirrors the internal behavior of AcDbBlockReference in ObjectARX
Returns AcGeMatrix3d
A transformation matrix representing the block-local INSERT transform in OCS, excluding extrusion.
- Defined in data-model/src/entity/AcDbBlockReference.ts:293

color

get color(): AcCmColor
Gets the color information of this entity.

Returns AcCmColor
The color object for this entity
Example
```
const color = entity.color;
```
Inherited from AcDbEntity.color
- Defined in data-model/src/entity/AcDbEntity.ts:120
set color(value: AcCmColor): void
Sets the color information for this entity.
Parameters
- value: AcCmColor
  The new color object
Returns void
Example
```
entity.color = new AcCmColor(0xFF0000);
```
Inherited from AcDbEntity.color
- Defined in data-model/src/entity/AcDbEntity.ts:140

database

get database(): AcDbDatabase
Gets the database in which this object is resident.

When an object isn't added to a database, this property returns the current working database. After it is added to a database, it will be set automatically. You should never set this value manually.

Returns AcDbDatabase
The database this object belongs to
Example
```
const db = obj.database;
```
Inherited from AcDbEntity.database
- Defined in data-model/src/base/AcDbObject.ts:223
set database(db: AcDbDatabase): void
Sets the database for this object.

This is typically set automatically when the object is added to a database. Manual setting should be avoided unless you know what you're doing.
Parameters
- db: AcDbDatabase
  The database to associate with this object
Returns void
Example
```
obj.database = myDatabase;
```
Inherited from AcDbEntity.database
- Defined in data-model/src/base/AcDbObject.ts:242

geometricExtents

get geometricExtents(): AcGeBox3d
Gets the geometric extents (bounding box) of this block reference.

This method calculates the bounding box by transforming the geometric extents of all entities in the referenced block according to the block reference's position, rotation, and scale factors.

Returns AcGeBox3d
The bounding box that encompasses the entire block reference
Example
```
const extents = blockRef.geometricExtents;
console.log(`Block bounds: ${extents.minPoint} to ${extents.maxPoint}`);
```
Overrides AcDbEntity.geometricExtents
- Defined in data-model/src/entity/AcDbBlockReference.ts:594

layer

get layer(): string
Gets the name of the layer referenced by this entity.

Returns string
The layer name
Example
```
const layerName = entity.layer;
```
Inherited from AcDbEntity.layer
- Defined in data-model/src/entity/AcDbEntity.ts:89
set layer(value: string): void
Sets the name of the layer for this entity.
Parameters
- value: string
  The new layer name
Returns void
Example
```
entity.layer = 'MyLayer';
```
Inherited from AcDbEntity.layer
- Defined in data-model/src/entity/AcDbEntity.ts:106

lineStyle

get lineStyle(): AcGiLineStyle
Gets the line style for this entity.

This method returns the line style based on the entity's linetype and other properties.

Returns AcGiLineStyle
The line style object
Example
```
const lineStyle = entity.lineStyle;
```
Inherited from AcDbEntity.lineStyle
- Defined in data-model/src/entity/AcDbEntity.ts:613

lineType

get lineType(): string
Gets the name of the line type referenced by this entity.

Returns string
The linetype name
Example
```
const lineType = entity.lineType;
```
Inherited from AcDbEntity.lineType
- Defined in data-model/src/entity/AcDbEntity.ts:185
set lineType(value: string): void
Sets the name of the line type for this entity.
Parameters
- value: string
  The new linetype name
Returns void
Example
```
entity.lineType = 'DASHED';
```
Inherited from AcDbEntity.lineType
- Defined in data-model/src/entity/AcDbEntity.ts:199

linetypeScale

get linetypeScale(): number
Gets the line type scale factor of this entity.

When an entity is first instantiated, its line type scale is initialized to an invalid value. When the entity is added to the database, if a linetype scale has not been specified for the entity, it is set to the database's current line type scale value.

Returns number
The linetype scale factor
Example
```
const scale = entity.linetypeScale;
```
Inherited from AcDbEntity.linetypeScale
- Defined in data-model/src/entity/AcDbEntity.ts:236
set linetypeScale(value: number): void
Sets the line type scale factor for this entity.
Parameters
- value: number
  The new linetype scale factor
Returns void
Example
```
entity.linetypeScale = 2.0;
```
Inherited from AcDbEntity.linetypeScale
- Defined in data-model/src/entity/AcDbEntity.ts:250

lineWeight

get lineWeight(): AcGiLineWeight
Gets the line weight used by this entity.

Returns AcGiLineWeight
The line weight value
Inherited from AcDbEntity.lineWeight
- Defined in data-model/src/entity/AcDbEntity.ts:208
set lineWeight(value: AcGiLineWeight): void
Sets the line weight for this entity.
Parameters
- value: AcGiLineWeight
  The new line weight value
Returns void
Inherited from AcDbEntity.lineWeight
- Defined in data-model/src/entity/AcDbEntity.ts:217

normal

get normal(): AcGeVector3d
Gets the normal vector of the plane containing the block reference.

Returns AcGeVector3d
The normal vector
Example
```
const normal = blockRef.normal;
console.log(`Normal: ${normal.x}, ${normal.y}, ${normal.z}`);
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:188
set normal(value: AcGeVector3dLike): void
Sets the normal vector of the plane containing the block reference.
Parameters
- value: AcGeVector3dLike
  The new normal vector
Returns void
Example
```
blockRef.normal = new AcGeVector3d(0, 0, 1);
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:202

objectId

get objectId(): string
Gets the object ID.

AutoCAD uses 64-bit integers to represent handles, which exceed the maximum integer value of JavaScript. Therefore, strings are used to represent object handles.

Returns string
The object ID as a string
Example
```
const id = obj.objectId;
console.log(`Object ID: ${id}`);
```
Inherited from AcDbEntity.objectId
- Defined in data-model/src/base/AcDbObject.ts:163
set objectId(value: string): void
Sets the object ID.
Parameters
- value: string
  The new object ID
Returns void
Example
```
obj.objectId = 'new-object-id';
```
Inherited from AcDbEntity.objectId
- Defined in data-model/src/base/AcDbObject.ts:177

ownerId

get ownerId(): string
Gets the object ID of the owner of this object.

Returns string
The owner object ID
Example
```
const ownerId = obj.ownerId;
```
Inherited from AcDbEntity.ownerId
- Defined in data-model/src/base/AcDbObject.ts:191
set ownerId(value: string): void
Sets the object ID of the owner of this object.
Parameters
- value: string
  The new owner object ID
Returns void
Example
```
obj.ownerId = 'parent-object-id';
```
Inherited from AcDbEntity.ownerId
- Defined in data-model/src/base/AcDbObject.ts:205

position

get position(): AcGePoint3d
Gets the WCS position point (insertion point) of the block reference.

Returns AcGePoint3d
The position point in WCS coordinates
Example
```
const position = blockRef.position;
console.log(`Block position: ${position.x}, ${position.y}, ${position.z}`);
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:96
set position(value: AcGeVector3dLike): void
Sets the WCS position point (insertion point) of the block reference.
Parameters
- value: AcGeVector3dLike
  The new position point
Returns void
Example
```
blockRef.position = new AcGePoint3d(15, 25, 0);
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:110

properties

get properties(): AcDbEntityProperties
Returns the full property definition for this block reference entity, including general group and geometry group.

The geometry group exposes editable properties via AcDbPropertyAccessor so the property palette can update the block reference in real-time.

Each property is an AcDbEntityRuntimeProperty.

Returns AcDbEntityProperties
Overrides AcDbEntity.properties
- Defined in data-model/src/entity/AcDbBlockReference.ts:425

rgbColor

get rgbColor(): number
Gets the RGB color of this entity.

This method handles the conversion of color indices (including ByLayer and ByBlock) to actual RGB colors. It resolves layer colors and block colors as needed.

Returns number
The RGB color value as a number
Example
```
const rgbColor = entity.rgbColor;
console.log(`RGB: ${rgbColor.toString(16)}`);
```
Inherited from AcDbEntity.rgbColor
- Defined in data-model/src/entity/AcDbEntity.ts:159

rotation

get rotation(): number
Gets the rotation value of the block reference.

The rotation value is relative to the X axis of a coordinate system that is parallel to the OCS of the block reference, but has its origin at the position point of the block reference. The rotation axis is the Z axis of this coordinate system with positive rotations going counterclockwise when looking down the Z axis towards the origin.

Returns number
The rotation value in radians
Example
```
const rotation = blockRef.rotation;
console.log(`Rotation: ${rotation} radians (${rotation * 180 / Math.PI} degrees)`);
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:130
set rotation(value: number): void
Sets the rotation value of the block reference.
Parameters
- value: number
  The new rotation value in radians
Returns void
Example
```
blockRef.rotation = Math.PI / 4; // 45 degrees
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:144

scaleFactors

get scaleFactors(): AcGePoint3d
Gets the X, Y, and Z scale factors for the block reference.

Returns AcGePoint3d
The scale factors as a 3D point
Example
```
const scaleFactors = blockRef.scaleFactors;
console.log(`Scale factors: ${scaleFactors.x}, ${scaleFactors.y}, ${scaleFactors.z}`);
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:159
set scaleFactors(value: AcGeVector3dLike): void
Sets the X, Y, and Z scale factors for the block reference.
Parameters
- value: AcGeVector3dLike
  The new scale factors
Returns void
Example
```
blockRef.scaleFactors = new AcGePoint3d(2, 1.5, 1); // 2x X scale, 1.5x Y scale
```
- Defined in data-model/src/entity/AcDbBlockReference.ts:173

transparency

get transparency(): AcCmTransparency
Gets the transparency level of this entity.

Returns AcCmTransparency
The transparency value.
Example
```
const transparency = entity.transparency;
```
Inherited from AcDbEntity.transparency
- Defined in data-model/src/entity/AcDbEntity.ts:292
set transparency(value: AcCmTransparency): void
Sets the transparency level of this entity.
Parameters
- value: AcCmTransparency
  The transparency value.
Returns void
Example
```
entity.transparency = 0.5; // 50% transparent
```
Inherited from AcDbEntity.transparency
- Defined in data-model/src/entity/AcDbEntity.ts:306

type

get type(): string
Gets the type name of this entity.

This method returns the entity type by removing the "AcDb" prefix from the constructor name.

Returns string
The entity type name
Example
```
const entity = new AcDbLine();
console.log(entity.type); // "Line"
```
Inherited from AcDbEntity.type
- Defined in data-model/src/entity/AcDbEntity.ts:75

visibility

get visibility(): boolean
Gets whether this entity is visible.

Returns boolean
True if the entity is visible, false otherwise
Example
```
const isVisible = entity.visibility;
```
Inherited from AcDbEntity.visibility
- Defined in data-model/src/entity/AcDbEntity.ts:264
set visibility(value: boolean): void
Sets whether this entity is visible.
Parameters
- value: boolean
  True to make the entity visible, false to hide it
Returns void
Example
```
entity.visibility = false; // Hide the entity
```
Inherited from AcDbEntity.visibility
- Defined in data-model/src/entity/AcDbEntity.ts:278

Methods

appendAttributes

appendAttributes(attrib: AcDbAttribute): void
Appends the specified AcDbAttribute object to the attribute list of the block reference, establishes the block reference as the attribute's owner, and adds the attribute to the AcDbDatabase that contains the block reference.
Parameters
- attrib: AcDbAttribute
  The attribute to be appended to the attribute list of the block reference.
Returns void
- Defined in data-model/src/entity/AcDbBlockReference.ts:231

attributeIterator

attributeIterator(): AcDbObjectIterator<AcDbAttribute>
Creates an iterator object that can be used to iterate over the attributes associated with the block reference.

Returns AcDbObjectIterator<AcDbAttribute>
An iterator object that can be used to iterate over the attributes
- Defined in data-model/src/entity/AcDbBlockReference.ts:242

close

close(): void
Closes the object.

All changes made to the object since it was opened are committed to the database, and a "closed" notification is sent. This method can be overridden by subclasses to provide specific cleanup behavior.

Returns void
Example
```
obj.close();
```
Inherited from AcDbEntity.close
- Defined in data-model/src/base/AcDbObject.ts:258

erase

erase(): boolean
Erase the current entity from the associated database.

Returns boolean
— true if an entity in the database existed and has been removed, or false if the entity does not exist.
Inherited from AcDbEntity.erase
- Defined in data-model/src/entity/AcDbEntity.ts:433

getAttr

getAttr(attrName: string): any
Gets the value of the specified attribute.

This method will throw an exception if the specified attribute doesn't exist. Use getAttrWithoutException() if you want to handle missing attributes gracefully.
Parameters
- attrName: string
  The name of the attribute to retrieve
Returns any
The value of the specified attribute
Throws
When the specified attribute doesn't exist
Example
```
try {
  const value = obj.getAttr('objectId');
} catch (error) {
  console.error('Attribute not found');
}
```
Inherited from AcDbEntity.getAttr
- Defined in data-model/src/base/AcDbObject.ts:103

getAttrWithoutException

getAttrWithoutException(attrName: string): any
Gets the value of the specified attribute without throwing an exception.

This method returns undefined if the specified attribute doesn't exist, making it safer for optional attributes.
Parameters
- attrName: string
  The name of the attribute to retrieve
Returns any
The value of the specified attribute, or undefined if it doesn't exist
Example
```
const value = obj.getAttrWithoutException('optionalAttribute');
if (value !== undefined) {
  // Use the value
}
```
Inherited from AcDbEntity.getAttrWithoutException
- Defined in data-model/src/base/AcDbObject.ts:130

`Protected`getGeneralProperties

getGeneralProperties(): AcDbEntityPropertyGroup
Creates the "General" property group for this entity.

This group contains common metadata attributes shared by all CAD entities (e.g., handle, layer). Each property includes a runtime AcDbPropertyAccessor allowing the property inspector to read and update live values.

Subclasses may override this method to append additional general-purpose properties while still preserving this base set.

Returns AcDbEntityPropertyGroup
A fully resolved property group containing runtime-accessible properties.
Inherited from AcDbEntity.getGeneralProperties
- Defined in data-model/src/entity/AcDbEntity.ts:517

`Protected`getLayerColor

getLayerColor(): null | AcCmColor
Gets the color of the layer this entity belongs to.

This method retrieves the color from the layer table for the layer this entity belongs to.

Returns null | AcCmColor
The layer color, or undefined if the layer doesn't exist
Example
```
const layerColor = entity.getLayerColor();
```
Inherited from AcDbEntity.getLayerColor
- Defined in data-model/src/entity/AcDbEntity.ts:682

setAttr

setAttr<A extends string>(attrName: A, val?: AcDbObjectAttrs[A]): void
Sets the value of an attribute.
Type Parameters
- A extends string
Parameters
- attrName: A
  The name of the attribute to set
- Optionalval: AcDbObjectAttrs[A]
  The value to assign to the attribute
Returns void
Example
```
obj.setAttr('objectId', 'new-id-123');
```
Inherited from AcDbEntity.setAttr
- Defined in data-model/src/base/AcDbObject.ts:145

subGetGripPoints

subGetGripPoints(): AcGePoint3d[]
Gets the grip points for this entity.

Grip points are the control points that can be used to modify the entity. This method should be overridden by subclasses to provide entity-specific grip points.

Returns AcGePoint3d[]
Array of grip points as 3D points
Example
```
const gripPoints = entity.subGetGripPoints();
```
Inherited from AcDbEntity.subGetGripPoints
- Defined in data-model/src/entity/AcDbEntity.ts:349

subGetOsnapPoints

subGetOsnapPoints(
    osnapMode: AcDbOsnapMode,
    pickPoint: AcGeVector3dLike,
    lastPoint: AcGeVector3dLike,
    snapPoints: AcGeVector3dLike[],
    gsMark?: string,
): void
Gets the object snap points for this mtext.

Object snap points are precise points that can be used for positioning when drawing or editing. This method provides snap points based on the specified snap mode.
Parameters
- osnapMode: AcDbOsnapMode
  The object snap mode
- pickPoint: AcGeVector3dLike
  The point where the user picked
- lastPoint: AcGeVector3dLike
  The last point
- snapPoints: AcGeVector3dLike[]
  Array to populate with snap points
- OptionalgsMark: string
  The object id of subentity. For now, it is used by INSERT entity only. In AutoCAD, it uses AcGiSubEntityTraits::setSelectionMarkerInput to set GS marker of the subentity involved in the object snap operation. For now, we don't provide such a GS marker mechanism yet. So passed id of subentity as GS marker. Maybe this behavior will change in the future.
Returns void
Overrides AcDbEntity.subGetOsnapPoints
- Defined in data-model/src/entity/AcDbBlockReference.ts:396

subWorldDraw

subWorldDraw(renderer: AcGiRenderer<AcGiEntity>): undefined | AcGiEntity
Draws this entity using the specified renderer.

This method should be implemented by subclasses to provide entity-specific drawing behavior.
Parameters
- renderer: AcGiRenderer<AcGiEntity>
  The renderer to use for drawing
Returns undefined | AcGiEntity
The rendered entity, or undefined if drawing failed
Overrides AcDbEntity.subWorldDraw
- Defined in data-model/src/entity/AcDbBlockReference.ts:612

transformBy

transformBy(matrix: AcGeMatrix3d): this
Transforms this entity by the specified matrix.

This method applies a geometric transformation to the entity. Subclasses should override this method to provide entity-specific transformation behavior.
Parameters
- matrix: AcGeMatrix3d
  The transformation matrix to apply
Returns this
This entity after transformation
Example
```
const matrix = AcGeMatrix3d.translation(10, 0, 0);
entity.transformBy(matrix);
```
Inherited from AcDbEntity.transformBy
- Defined in data-model/src/entity/AcDbEntity.ts:407

triggerModifiedEvent

triggerModifiedEvent(): void
Triggers a modified event for this entity.

This method notifies listeners that the entity has been modified.

Returns void
Example
```
entity.triggerModifiedEvent();
```
Inherited from AcDbEntity.triggerModifiedEvent
- Defined in data-model/src/entity/AcDbEntity.ts:498

worldDraw

worldDraw(
renderer: AcGiRenderer<AcGiEntity>,
delay?: boolean,
): undefined | AcGiEntity
Called by cad application when it wants the entity to draw itself in WCS (World Coordinate System) and acts as a wrapper / dispatcher around subWorldDraw(). The children class should never overidde this method.

It executes the following logic:
- Handles traits (color, linetype, lineweight, transparency, etc.)
- Calls subWorldDraw() to do the actual geometry output
Parameters
- renderer: AcGiRenderer<AcGiEntity>
  The renderer to use for drawing
- Optionaldelay: boolean
  The flag to delay creating one rendered entity and just create one dummy entity. Renderer can delay heavy calculation operation to avoid blocking UI when this flag is true. For now, text and mtext entity supports this flag only. Other types of entities just ignore this flag.
Returns undefined | AcGiEntity
The rendered entity, or undefined if drawing failed
Inherited from AcDbEntity.worldDraw
- Defined in data-model/src/entity/AcDbEntity.ts:471

Class AcDbBlockReference

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns AcDbBlockReference

Example

Properties

StatictypeName

Accessors

attrs

Returns AcCmObject<ATTRS>

Example

blockTableRecord

Returns undefined | AcDbBlockTableRecord

Example

blockTransform

Matrix composition (right-multiply convention)

Notes

Returns AcGeMatrix3d

color

Returns AcCmColor

Example

Parameters

Returns void

Example

database

Returns AcDbDatabase

Example

Parameters

Returns void

Example

geometricExtents

Returns AcGeBox3d

Example

layer

Returns string

Example

Parameters

Returns void

Example

lineStyle

Returns AcGiLineStyle

Example

lineType

Returns string

Example

Parameters

Returns void

Example

linetypeScale

Returns number

Example

Parameters

Returns void

Example

lineWeight

Returns AcGiLineWeight

Parameters

Returns void

normal

Returns AcGeVector3d

Example

Parameters

Returns void

Example

objectId

Returns string

Example

Parameters

Returns void

Example

ownerId

Returns string

`Static`typeName

`Protected`getGeneralProperties

`Protected`getLayerColor