Class AcDbDatabase

The AcDbDatabase class represents an AutoCAD drawing file.

Each AcDbDatabase object contains the various header variables, symbol tables, table records, entities, and objects that make up the drawing. The AcDbDatabase class has member functions to allow access to all the symbol tables, to read and write to DWG files, to get or set database defaults, to execute various database-level operations, and to get or set all header variables.

Example

const database = new AcDbDatabase();
await database.read(dxfData, { readOnly: true });
const entities = database.tables.blockTable.modelSpace.entities;

Hierarchy (View Summary)

Constructors

constructor

Properties

events transactionManager

Accessors

angbase angdir attrs aunits auprec cecolor celtscale celtype celweight cetransparency classes clayer cmleaderstyle cmlscale cmlstyle comparehatch comparercmargin comparetext comparetolerance currentSpaceId database dimstyle drawCircleSides drawNoPlotLayers dwgname extensionDictionary extents extmax extmin formatter hpbackgroundcolor hpcolor hplayer hptransparency insunits isTemp lastOpenError layerFilters ltscale lunits luprec lwdisplay measurement objectId objects orthomode osmode ownerId pdmode pdsize psltscale tables textstyle thumbnailImage tilemode unitmode version

Methods

assignDatabase beginEventBatch clone clonePreservingIdentity close createDefaultData createExtensionDictionary dxfIn dxfInControlString dxfInFields dxfInXData dxfOut dxfOutFields dxfOutXData endEventBatch endEventBatchChunked ensureTextStyleDefaults generateHandle getAttr getAttrWithoutException getObjectById getRootDictionaries getXData initializeHandleSeed isEventBatched isLayerDrawable isUndoRecording notifyDictObjectErased notifyDictObjectSet notifyEntityAppended notifyEntityErased openEntityForRead openEntityForWrite openObjectForRead openObjectForWrite openUri read regen removeXData restoreFrom runDatabaseEdit setAttr setDwgName setXData updateMaxHandle

Constructors

constructor

Properties

Readonlyevents

events: {
    dictObjectErased: AcCmEventManager<AcDbDictObjectEventArgs>;
    dictObjetSet: AcCmEventManager<AcDbDictObjectEventArgs>;
    entityAppended: AcCmEventManager<AcDbEntityEventArgs>;
    entityErased: AcCmEventManager<AcDbEntityEventArgs>;
    entityModified: AcCmEventManager<AcDbEntityEventArgs>;
    layerAppended: AcCmEventManager<AcDbLayerEventArgs>;
    layerErased: AcCmEventManager<AcDbLayerEventArgs>;
    layerModified: AcCmEventManager<AcDbLayerModifiedEventArgs>;
    openFailed: AcCmEventManager<AcDbOpenFailedEventArgs>;
    openProgress: AcCmEventManager<AcDbProgressdEventArgs>;
} = ...

Events that can be triggered by the database.

These events allow applications to respond to various database operations such as entity modifications, layer changes, and progress updates.

Type declaration

ReadonlytransactionManager

transactionManager: AcDbDatabaseTransactionManager

Manages transactions and undo/redo for this database.

Accessors

angbase

angdir

attrs

aunits

  • get aunits(): number

  • Angular unit display and entry format for the drawing (AutoCAD system variable AUNITS).

    This does not change how angles are stored internally (radians in geometry); it controls how angles are formatted in the UI and how numeric angle input is interpreted, together with angbase (ANGBASE) and angdir (ANGDIR).

    Returns number

    Integer code matching AcDbAngleUnits:

    Value Meaning
    0 Decimal degrees ??e.g. 45.5
    1 Degrees/minutes/seconds ??e.g. 45d30'15"
    2 Gradians ??e.g. 50g (400 grads = full circle)
    3 Radians ??e.g. 0.785398...
    4 Surveyor's units ??quadrant bearing notation (e.g. N 45d30'15" E)

    Remarks

    Prefer assigning AcDbAngleUnits enum members for readability instead of raw integers.

    See

    Example

    const angleUnits = database.aunits;
  • set aunits(value: number): void

  • Sets AUNITS ??the angular unit display format (see aunits getter for value meanings).

    Parameters

    • value: number

      Integer 0??4per {@link AcDbAngleUnits}, orundefined/nullcoerced to0` by the setter chain.

    Returns void

    Example

    database.aunits = AcDbAngleUnits.DecimalDegrees;

auprec

cecolor

celtscale

celtype

celweight

cetransparency

classes

clayer

cmleaderstyle

cmlscale

cmlstyle

comparehatch

comparercmargin

comparetext

comparetolerance

currentSpaceId

  • get currentSpaceId(): string

  • Gets the object ID of the AcDbBlockTableRecord of the current space.

    The current space can be either model space or paper space.

    Returns string

    The object ID of the current space

    Example

    const currentSpaceId = database.currentSpaceId;
  • set currentSpaceId(value: string): void

  • Sets the current space by object ID.

    Parameters

    • value: string

      The object ID of the block table record to set as current space

    Returns void

    Throws

    When the specified block table record ID doesn't exist

    Example

    database.currentSpaceId = 'some-block-record-id';

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;
  • 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

    Returns void

    Example

    obj.database = myDatabase;

dimstyle

drawCircleSides

drawNoPlotLayers

dwgname

extensionDictionary

  • get extensionDictionary(): undefined | string

  • Gets the objectId of the extension dictionary owned by this object.

    If the object does not have an extension dictionary, this returns undefined.

    In ObjectARX terms, this is equivalent to AcDbObject::extensionDictionary().

    Returns undefined | string

    The extension dictionary objectId, or undefined

    Example

    const dictId = obj.extensionDictionary
    if (dictId) {
      console.log('Has extension dictionary:', dictId)
    }
  • set extensionDictionary(value: undefined | string): void

  • Sets the objectId of the extension dictionary owned by this object.

    This does not create or delete the dictionary object itself ??it only establishes or clears the ownership relationship.

    Passing undefined removes the association.

    Parameters

    • value: undefined | string

      The extension dictionary objectId, or undefined

    Returns void

    Example

    obj.extensionDictionary = dict.objectId

extents

extmax

extmin

formatter

  • get formatter(): AcDbFormatter

  • Formatter for linear distances, point coordinates, and angles using this database's LUNITS, AUNITS, and related system variables.

    Returns AcDbFormatter

    Example

    database.formatter.formatLength(12.3456);
    database.formatter.formatPoint3d(point);
    database.formatter.formatAngle(angleRadians, { showUnits: true });

hpbackgroundcolor

hpcolor

hplayer

hptransparency

insunits

  • get insunits(): number

  • Gets the drawing-units value for automatic scaling of blocks, images, or xrefs.

    This is the current INSUNITS value for the database.

    Returns number

    The insertion units value

    Example

    const insertionUnits = database.insunits;
  • set insunits(value: number): void

  • Sets the drawing-units value for automatic scaling.

    Parameters

    • value: number

      The new insertion units value

    Returns void

    Example

    database.insunits = AcDbUnitsValue.Millimeters;

isTemp

  • get isTemp(): any

  • Returns true if this object is temporary and not yet committed to the database.

    A temporary object is identified by its objectId starting with the TEMP prefix.

    Returns any

lastOpenError

layerFilters

  • get layerFilters(): AcLyLayerFilterTree

  • Gets the Layer Properties Manager filter tree for this database.

    Returns AcLyLayerFilterTree

    The current AcLyLayerFilterTree.

    Remarks

    Mirrors AutoCAD .NET Database.LayerFilters / ObjectARX AcLy* filters. This is the property/group filter tree, not the flat objects.layerFilter dictionary used by AcDbLayerFilter / AcDbLayerIndex.

    Like AutoCAD, treat this value as retrieved by value: mutate the tree, then assign it back via the setter if your workflow expects that pattern.

    Example

    const tree = db.layerFilters;
    const filter = new AcLyLayerFilter();
    filter.name = 'Unlocked Layers';
    filter.setFilterExpression('LOCKED=="False"');
    tree.root.addNested(filter);
    db.layerFilters = tree;
  • set layerFilters(value: AcLyLayerFilterTree): void

  • Sets the Layer Properties Manager filter tree for this database.

    Parameters

    Returns void

ltscale

lunits

luprec

lwdisplay

measurement

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}`);
  • set objectId(value: string): void

  • Sets the object ID.

    Parameters

    • value: string

      The new object ID

    Returns void

    Example

    obj.objectId = 'new-object-id';

objects

orthomode

osmode

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;
  • 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';

pdmode

pdsize

psltscale

tables

textstyle

thumbnailImage

  • get thumbnailImage(): undefined | Uint8Array

  • Gets or sets the drawing thumbnail preview image.

    Corresponds to AutoCAD .NET Database.ThumbnailBitmap, DXF THUMBNAILIMAGE section (group codes 90/310), and the DWG file preview. Stored as raw image bytes (typically BMP/DIB or PNG).

    Returns undefined | Uint8Array

    Thumbnail image bytes, or undefined when none exist.

  • set thumbnailImage(value: undefined | Uint8Array): void

  • Parameters

    • value: undefined | Uint8Array

    Returns void

tilemode

unitmode

version

Methods

ProtectedassignDatabase

beginEventBatch

clone

clonePreservingIdentity

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();

createDefaultData

createExtensionDictionary

  • createExtensionDictionary(): undefined | string

  • Creates the extension dictionary for this object if it does not already exist.

    This method closely mirrors the behavior of AcDbObject::createExtensionDictionary() in ObjectARX.

    • If the object already owns an extension dictionary, no new dictionary is created and the existing dictionary's objectId is returned.
    • Otherwise, a new AcDbDictionary is created, added to the same database, owned by this object, and its objectId is stored on this object.

    Returns undefined | string

    The objectId of the extension dictionary

    Example

    const dictId = obj.createExtensionDictionary()

dxfIn

  • dxfIn(filer: AcDbDxfFiler): this

  • Reads this object from a DXF filer (ObjectARX dxfIn).

    Reads common handle/owner fields, then delegates to dxfInFields. XData (group 1001+) is consumed when present after object fields.

    Group-102 control strings ({ACAD_XDICTIONARY, {ACAD_REACTORS, …) are consumed here so subclass readers still see handle/owner/subclass markers that follow them. Many real DXF writers emit these blocks on LAYER and entity records; skipping them would leave name/layer unset.

    Parameters

    Returns this

ProtecteddxfInControlString

dxfInFields

  • dxfInFields(_filer: AcDbDxfFiler): this

  • Reads object-specific DXF fields (ObjectARX dxfInFields).

    Subclasses should override, call super.dxfInFields(filer) first when appropriate, then consume their subclass marker and fields in an order-independent loop.

    Per the AutoCAD DXF specification, readers must ignore undefined group codes and must not assume field order. Within a subclass loop the correct unknown-code behavior is break (skip and continue). Use pushBackItem only to hand a group-100 subclass marker (or XData) to another reader — never to abort on an unrecognized optional code.

    Parameters

    Returns this

ProtecteddxfInXData

dxfOut

  • dxfOut(
        _fileName?: string,
        precision?: number,
        version?: string | number | AcDbDwgVersion,
        optionsOrThumbnail?:
            | boolean
            | { format?: "binary"
            | "ascii"; saveThumbnailImage?: boolean },
    ): string | Uint8Array

  • Exports the current database into DXF (ASCII string or binary bytes).

    The fileName parameter is kept for ObjectARX API parity. In this web implementation the method returns the DXF payload instead of writing the filesystem directly.

    Parameters

    • Optional_fileName: string

      Kept for ObjectARX parity. Ignored in this implementation.

    • precision: number = 16

      Numeric precision used by the DXF filer.

    • version: string | number | AcDbDwgVersion = ...

      Target DXF/DWG version name or value.

    • optionsOrThumbnail: boolean | { format?: "binary" | "ascii"; saveThumbnailImage?: boolean } = false

      Legacy boolean thumbnail flag, or options with saveThumbnailImage and format: 'ascii' | 'binary'.

    Returns string | Uint8Array

    ASCII DXF string, or Uint8Array when format is 'binary'.

dxfOutFields

ProtecteddxfOutXData

endEventBatch

endEventBatchChunked

  • endEventBatchChunked(
        chunkSize: number,
        onChunk?: (flushed: number, total: number) => void | Promise<void>,
    ): Promise<void>

  • Ends the outermost event batch, flushing entityAppended notifications in chunks so converters can report ENTITY progress while the viewer adds/renders.

    Nested batches still require matching endEventBatch / endEventBatchChunked calls; only the outermost close flushes.

    Parameters

    • chunkSize: number

      Max entities per entityAppended dispatch

    • OptionalonChunk: (flushed: number, total: number) => void | Promise<void>

      Called after each chunk with (flushed, total)

    Returns Promise<void>

ensureTextStyleDefaults

  • ensureTextStyleDefaults(): void

  • Ensures the default text style exists in the text style table.

    This is invoked while converting STYLE records and again after a drawing is fully opened so TEXT/MTEXT entities can resolve a style during progressive rendering.

    Returns void

generateHandle

  • generateHandle(): string

  • Generates a new unique object ID (handle) for the database. The handle is a hexadecimal string that increments from the current max handle.

    Returns string

    A new unique object ID as a hexadecimal string

    Example

    const newHandle = database.generateHandle();
    console.log(`New handle: ${newHandle}`);

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');
    }

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
    }

getObjectById

getRootDictionaries

getXData

  • getXData(appId: string): undefined | AcDbResultBuffer

  • Retrieves the XData associated with this object for a given application ID.

    Extended Entity Data (XData) allows applications to attach arbitrary, application-specific data to an AcDbObject. Each XData entry is identified by a registered application name (AppId) and stored as an AcDbResultBuffer.

    This method is conceptually equivalent to AcDbObject::xData() in ObjectARX, but simplified to return the entire result buffer for the specified AppId.

    Parameters

    • appId: string

      The application ID (registered AppId name) that owns the XData

    Returns undefined | AcDbResultBuffer

    The AcDbResultBuffer associated with the AppId, or undefined if no XData exists for that AppId

    Example

    const xdata = obj.getXData('MY_APP')
    if (xdata) {
      // Read values from the result buffer
    }

initializeHandleSeed

  • initializeHandleSeed(seed: string): void

  • Initializes generateHandle from a DXF/DWG $HANDSEED value.

    $HANDSEED is the next handle AutoCAD would assign; internal _maxHandle is kept one below that value.

    Parameters

    • seed: string

      Hexadecimal handle seed from the drawing header

    Returns void

isEventBatched

isLayerDrawable

  • isLayerDrawable(layerName: string): boolean

  • Returns whether entities on the given layer should be drawn under the current drawNoPlotLayers setting.

    Layer off/freeze visibility is handled separately by the viewer; this only reflects the no-plot policy.

    Parameters

    • layerName: string

    Returns boolean

isUndoRecording

notifyDictObjectErased

notifyDictObjectSet

notifyEntityAppended

notifyEntityErased

openEntityForRead

openEntityForWrite

openObjectForRead

openObjectForWrite

openUri

  • openUri(url: string, options: AcDbOpenDatabaseOptions): Promise<void>

  • Read AutoCAD DXF or DWG drawing specified by the URL into the database object. The method automatically detects the file type based on the URL extension:

    • .dxf files are read as text using readAsText()
    • .dwg files are read as binary data using readAsArrayBuffer()

    Parameters

    • url: string

      Input the URL linked to one AutoCAD DXF or DWG file

    • options: AcDbOpenDatabaseOptions

      Input options to read drawing data

    Returns Promise<void>

read

  • read(
        data: ArrayBuffer,
        options: AcDbOpenDatabaseOptions,
        fileType?: string,
    ): Promise<void>

  • Reads drawing data from a string or ArrayBuffer.

    This method parses the provided data and populates the database with the resulting entities, tables, and objects. The method supports both DXF and DWG file formats.

    Parameters

    • data: ArrayBuffer

      The drawing data as a string or ArrayBuffer

      • For DXF files: Pass a string containing the DXF content
      • For DWG files: Pass an ArrayBuffer instance containing the binary DWG data
    • options: AcDbOpenDatabaseOptions

      Options for reading the database

    • fileType: string = AcDbFileType.DXF

      The type of file being read (defaults to DXF)

    Returns Promise<void>

    Example

    // Reading a DXF file (string)
    const database = new AcDbDatabase();
    await database.read(dxfString, { readOnly: true }, AcDbFileType.DXF);

    // Reading a DWG file (ArrayBuffer)
    const database = new AcDbDatabase();
    await database.read(dwgArrayBuffer, { readOnly: true }, AcDbFileType.DWG);

regen

removeXData

  • removeXData(appId: string): void

  • Removes the XData associated with the specified application ID.

    After removal, calls to getXData() for the same AppId will return undefined. If no XData exists for the given AppId, this method has no effect.

    This mirrors the behavior of clearing XData for a specific application in ObjectARX rather than removing all XData from the object.

    Parameters

    • appId: string

      The application ID whose XData should be removed

    Returns void

    Example

    obj.removeXData('MY_APP')

restoreFrom

runDatabaseEdit

setAttr

setDwgName

setXData

  • setXData(resbuf: AcDbResultBuffer): void

  • Attaches or replaces XData for this object.

    If XData already exists for the given AppId, it is replaced by the provided AcDbResultBuffer. The caller is responsible for ensuring that:

    • The AppId is registered in the database's AppId table
    • The result buffer follows valid DXF/XData conventions (e.g. starts with a 1001 group code for the AppId)

    This method is conceptually similar to AcDbObject::setXData() in ObjectARX.

    Parameters

    Returns void

    Example

    const rb = new AcDbResultBuffer([
      { code: AcDbDxfCode.ExtendedDataRegAppName, value: 'MY_APP' },
      { code: AcDbDxfCode.ExtendedDataAsciiString, value: 'custom value' }
    ])

    obj.setXData('MY_APP', rb)

updateMaxHandle

  • updateMaxHandle(handle: string): void

  • Updates the maximum handle value if the provided handle is greater. This is called when setting an object's objectId from external sources (e.g., reading DXF/DWG).

    Parameters

    • handle: string

      The handle to check and potentially update maxHandle with

    Returns void

    Example

    database.updateMaxHandle('1A2B');

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods