import { AcGeBox3d, AcGeMatrix3d, AcGePoint3d, AcGePoint3dLike, AcGeVector3d, AcGeVector3dLike } from '@mlightcad/geometry-engine';
import { AcGiEntity, AcGiRenderer } from '@mlightcad/graphic-interface';
import { AcDbDxfFiler, AcDbObjectId } from '../base';
import { AcDbObjectIterator, AcDbOsnapMode } from '../misc';
import { AcDbAttribute } from './AcDbAttribute';
import { AcDbEntity } from './AcDbEntity';
import { AcDbEntityProperties } from './AcDbEntityProperties';
/**
 * 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
 * ```typescript
 * // 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}`);
 * ```
 */
export declare class AcDbBlockReference extends AcDbEntity {
    /** The entity type name */
    static typeName: string;
    get dxfTypeName(): string;
    /** The WCS position point (insertion point) of the block reference */
    private _position;
    /** The rotation value in radians */
    private _rotation;
    /** The X, Y, and Z scale factors for the block reference */
    private _scaleFactors;
    /** The normal vector of the plane containing the block reference */
    private _normal;
    /** The name of the referenced block */
    private _blockName;
    /** Attributes associated with this block reference */
    private _attribs;
    /**
     * 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.
     *
     * @param blockName - The name of the block table record to reference
     *
     * @example
     * ```typescript
     * const blockRef = new AcDbBlockReference("MyBlock");
     * blockRef.position = new AcGePoint3d(5, 10, 0);
     * blockRef.rotation = Math.PI / 6; // 30 degrees
     * ```
     */
    constructor(blockName: string);
    /**
     * Gets the WCS position point (insertion point) of the block reference.
     *
     * @returns The position point in WCS coordinates
     *
     * @example
     * ```typescript
     * const position = blockRef.position;
     * console.log(`Block position: ${position.x}, ${position.y}, ${position.z}`);
     * ```
     */
    get position(): AcGePoint3d;
    /**
     * Sets the WCS position point (insertion point) of the block reference.
     *
     * @param value - The new position point
     *
     * @example
     * ```typescript
     * blockRef.position = new AcGePoint3d(15, 25, 0);
     * ```
     */
    set position(value: AcGePoint3dLike);
    /**
     * 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 The rotation value in radians
     *
     * @example
     * ```typescript
     * const rotation = blockRef.rotation;
     * console.log(`Rotation: ${rotation} radians (${rotation * 180 / Math.PI} degrees)`);
     * ```
     */
    get rotation(): number;
    /**
     * Sets the rotation value of the block reference.
     *
     * @param value - The new rotation value in radians
     *
     * @example
     * ```typescript
     * blockRef.rotation = Math.PI / 4; // 45 degrees
     * ```
     */
    set rotation(value: number);
    /**
     * Gets the X, Y, and Z scale factors for the block reference.
     *
     * @returns The scale factors as a 3D point
     *
     * @example
     * ```typescript
     * const scaleFactors = blockRef.scaleFactors;
     * console.log(`Scale factors: ${scaleFactors.x}, ${scaleFactors.y}, ${scaleFactors.z}`);
     * ```
     */
    get scaleFactors(): AcGePoint3d;
    /**
     * Sets the X, Y, and Z scale factors for the block reference.
     *
     * @param value - The new scale factors
     *
     * @example
     * ```typescript
     * blockRef.scaleFactors = new AcGePoint3d(2, 1.5, 1); // 2x X scale, 1.5x Y scale
     * ```
     */
    set scaleFactors(value: AcGePoint3dLike);
    /**
     * Gets the normal vector of the plane containing the block reference.
     *
     * @returns The normal vector
     *
     * @example
     * ```typescript
     * const normal = blockRef.normal;
     * console.log(`Normal: ${normal.x}, ${normal.y}, ${normal.z}`);
     * ```
     */
    get normal(): AcGeVector3d;
    /**
     * Sets the normal vector of the plane containing the block reference.
     *
     * @param value - The new normal vector
     *
     * @example
     * ```typescript
     * blockRef.normal = new AcGeVector3d(0, 0, 1);
     * ```
     */
    set normal(value: AcGeVector3dLike);
    /**
     * Gets the name of the block definition referenced by this INSERT entity.
     *
     * The returned value is the block table record key used to resolve
     * {@link blockTableRecord} from the current database.
     *
     * @returns The referenced block name.
     */
    get blockName(): string;
    /**
     * 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 The block table record, or undefined if not found
     *
     * @example
     * ```typescript
     * const blockRecord = blockRef.blockTableRecord;
     * if (blockRecord) {
     *   console.log(`Block name: ${blockRecord.name}`);
     * }
     * ```
     */
    get blockTableRecord(): import("..").AcDbBlockTableRecord | undefined;
    /**
     * 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.
     * @param attrib - The attribute to be appended to the attribute list of the block reference.
     */
    appendAttributes(attrib: AcDbAttribute): void;
    /**
     * Creates an iterator object that can be used to iterate over the attributes associated
     * with the block reference.
     *
     * @returns An iterator object that can be used to iterate over the attributes
     */
    attributeIterator(): AcDbObjectIterator<AcDbAttribute>;
    /**
     * 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 {@link 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 {@link 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
     * - {@link normal} is applied later as a final orientation step
     * - This mirrors the internal behavior of `AcDbBlockReference` in ObjectARX
     *
     * @returns A transformation matrix representing the block-local INSERT transform
     *          in OCS, excluding extrusion.
     */
    get blockTransform(): AcGeMatrix3d;
    /**
     * Gets the object snap points for this block reference.
     *
     * 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.
     *
     * @param osnapMode - The object snap mode
     * @param pickPoint - The point where the user picked
     * @param lastPoint - The last point
     * @param snapPoints - Array to populate with snap points
     * @param gsMark - 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.
     * @param insertionMat - Cumulative insertion transform matrix from parent
     * block references.
     */
    subGetOsnapPoints(osnapMode: AcDbOsnapMode, pickPoint: AcGePoint3dLike, lastPoint: AcGePoint3dLike, snapPoints: AcGePoint3dLike[], gsMark?: AcDbObjectId, insertionMat?: AcGeMatrix3d): void;
    /**
     * Transforms this block reference by an arbitrary world-space matrix.
     *
     * Unlike simple entities that can transform raw geometry directly, an INSERT
     * stores placement as decomposed parameters (`position`, `rotation`,
     * `scaleFactors`, and `normal`). This method applies the input matrix to a
     * derived local frame, then reconstructs those parameters from the transformed
     * frame so the reference remains representable as an INSERT.
     *
     * Recomposition pipeline:
     *
     * 1. Build local axes from current `rotation`, `normal`, and `scaleFactors`
     * 2. Transform axis endpoints and origin by `matrix`
     * 3. Recompute normal from transformed X/Y axes (with a degenerate fallback)
     * 4. Project transformed X axis into the new OCS to recover `rotation`
     * 5. Recover axis lengths as new `scaleFactors`
     * 6. Transform all attached attributes with the same matrix
     *
     * @param matrix - Transformation matrix in WCS.
     * @returns The current block reference instance.
     */
    transformBy(matrix: AcGeMatrix3d): this;
    /**
     * Returns the full property definition for this block reference entity, including
     * general group and geometry group.
     *
     * The geometry group exposes editable properties via {@link AcDbPropertyAccessor}
     * so the property palette can update the block reference in real-time.
     *
     * Each property is an {@link AcDbEntityRuntimeProperty}.
     */
    get properties(): AcDbEntityProperties;
    /**
     * 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 The bounding box that encompasses the entire block reference
     *
     * @example
     * ```typescript
     * const extents = blockRef.geometricExtents;
     * console.log(`Block bounds: ${extents.minPoint} to ${extents.maxPoint}`);
     * ```
     */
    get geometricExtents(): AcGeBox3d;
    /**
     * @inheritdoc
     */
    subWorldDraw(renderer: AcGiRenderer): AcGiEntity | undefined;
    /**
     * Writes this INSERT entity to DXF, including its attribute sequence.
     *
     * The output order follows DXF conventions:
     *
     * 1. Emit INSERT common/object fields via the base implementation
     * 2. Emit one `ATTRIB` section for each attached attribute
     * 3. Emit a terminating `SEQEND` record when attributes were written
     *
     * @param filer - DXF output writer.
     * @param allXdata - When true, emits all XData attached to this entity.
     * @returns The current entity instance.
     */
    dxfOut(filer: AcDbDxfFiler, allXdata?: boolean): this;
    /**
     * Recursively resolves object snap points from nested block references.
     *
     * This helper traverses child entities under the current block reference to
     * locate the sub-entity identified by `gsMark`. When found, it converts
     * pick/last points into the target local space, asks that entity for snap
     * points, then maps results back to the caller space as needed.
     *
     * The method tracks visited block references to prevent infinite recursion in
     * cyclic block graphs.
     *
     * @param osnapMode - Requested osnap mode.
     * @param pickPoint - User pick point in caller space.
     * @param lastPoint - Previous point in caller space.
     * @param snapPoints - Output collection to append resolved snap points into.
     * @param gsMark - Object id of the target sub-entity.
     * @param parentInsertionMat - Cumulative transform from ancestor INSERTs.
     * @param visitedRefs - Internal recursion guard set.
     * @returns `true` when the target sub-entity is found and processed, else `false`.
     */
    private subEntityGetOsnapPoints;
    /**
     * Computes the insertion osnap point in caller space.
     *
     * The insertion point is the block definition base point transformed by the
     * full cumulative insertion transform (ancestor transform + this reference's
     * own full insertion transform including extrusion).
     *
     * @param parentInsertionMat - Cumulative transform from parent block references.
     * @returns The insertion point in the caller coordinate space.
     */
    private getInsertionPoint;
    /**
     * Builds the full INSERT transform for this block reference.
     *
     * {@link blockTransform} contains translation/rotation/scale in OCS only.
     * This method prepends the extrusion transform derived from {@link normal} so
     * the returned matrix maps block-local geometry all the way into WCS.
     *
     * @returns Full block insertion transform including OCS extrusion.
     */
    private getFullInsertionTransform;
    /**
     * Writes DXF fields for this object.
     *
     * @param filer - DXF output writer.
     * @returns The instance (for chaining).
     */
    dxfOutFields(filer: AcDbDxfFiler): this;
}
//# sourceMappingURL=AcDbBlockReference.d.ts.map