Class AcDbFormatter

Formats linear distances, point coordinates, and angles for display in the UI, matching AutoCAD drawing-unit behavior as closely as the supported system variables allow.

An instance is bound to one AcDbDatabase. On each call it reads the current values of the relevant header/system variables from that database (not a snapshot taken at construction).

Linear distances and coordinates

Variable Role
LUNITS Display format (scientific, decimal, engineering, …); see AcDbDatabase.lunits
LUPREC Precision (decimal places or fractional denominator); see AcDbDatabase.luprec
INSUNITS Unit suffix when AcDbFormatterOptions.showUnits is true; see AcDbDatabase.insunits
UNITMODE Report vs input delimiters for feet-inch and fractions; see AcDbDatabase.unitmode
MEASUREMENT Imperial vs metric suffix when INSUNITS is unitless; see AcDbDatabase.measurement

Engineering (LUNITS = 3) and architectural (LUNITS = 4) formats treat the numeric value as inches, consistent with AutoCAD.

Angles

Input angles are radians in WCS. Before formatting, the value is adjusted by ANGBASE and ANGDIR, then converted per AUNITS and AUPREC.

Out of scope

Dimension entity text uses per-style DIM* variables (for example DIMLUNIT, DIMDEC), not this class. SNAPANG and UCS settings affect snapping/input, not WCS coordinate strings here.

Example

database.lunits = AcDbLinearUnits.Decimal;
database.luprec = 2;

database.formatter.formatLength(12.3456); // "12.35"
database.formatter.formatLength(12.3456, { showUnits: true }); // "12.35 mm" (with INSUNITS = mm)
database.formatter.formatPoint2d(new AcGePoint2d(1, 2)); // "1, 2"
database.formatter.formatAngle(Math.PI / 4, { showUnits: true }); // "45°"

Constructors

constructor

Methods

formatAngle formatLength formatPoint2d formatPoint3d

Constructors

constructor

Methods

formatAngle

  • formatAngle(radians: number, options?: AcDbFormatterOptions): string

  • Formats an angle given in radians (WCS), for display according to the drawing angle units.

    Processing order:

    1. Subtract ANGBASE (zero direction).
    2. Negate if ANGDIR = 1 (clockwise positive).
    3. Normalize to ([0, 2\pi)) via AcGeMathUtil.normalizeAngle.
    4. Format using AUNITS and AUPREC.
    AUNITS Typical output (no unit suffix)
    0 Decimal degrees 45 or 45.5
    1 Degrees/minutes/seconds 45d30'15"
    2 Gradians 50
    3 Radians 0.785
    4 Surveyor's N 45d30'15" E

    Parameters

    Returns string

    Formatted angle string.

    Remarks

    For included or relative angles, pass AcDbFormatterOptions.applyAngbaseAngdir = false. For arc sweep or dimension overrides, supply the appropriate radians value and flags.

    Example

    database.aunits = AcDbAngleUnits.DecimalDegrees;
    database.auprec = 0;
    formatter.formatAngle(Math.PI / 4); // "45"
    formatter.formatAngle(Math.PI / 4, { showUnits: true }); // "45°"

formatLength

  • formatLength(value: number, options?: AcDbFormatterOptions): string

  • Formats a single linear distance in drawing units.

    The output pattern follows LUNITS and LUPREC. When AcDbFormatterOptions.showUnits is true, a suffix may be appended based on INSUNITS and MEASUREMENT.

    LUNITS Typical output (no unit suffix)
    1 Scientific 1.23E+02
    2 Decimal 12.35
    3 Engineering 1'-3.5 (value interpreted as inches)
    4 Architectural 1'-3 1/2
    5 Fractional 15 1/2
    6 Windows desktop Same as decimal

    UNITMODE changes delimiters for engineering, architectural, and fractional modes (for example 1'3-1/2 when UNITMODE = 1).

    Parameters

    Returns string

    Formatted string suitable for status bars, measurement overlays, or tooltips.

    Remarks

    Non-finite values (NaN, ±Infinity) are formatted as "0".

    Example

    database.lunits = AcDbLinearUnits.Architectural;
    database.luprec = 2;
    formatter.formatLength(15.5); // "1'-3 1/2"

formatPoint2d

  • formatPoint2d(point: AcGePoint2d, options?: AcDbFormatterOptions): string

  • Formats a 2D point as "x, y", formatting each component with formatLength.

    Both coordinates use the same LUNITS / LUPREC rules and the same AcDbFormatterOptions for the call. The separator is a comma followed by a space (, ), which matches common Cartesian display in measurement UIs.

    Parameters

    Returns string

    Formatted coordinate pair, for example "1.2, 4.6" or "1'-0, 2'-6" depending on LUNITS.

    Example

    database.lunits = AcDbLinearUnits.Decimal;
    database.luprec = 1;
    formatter.formatPoint2d(new AcGePoint2d(1.23, 4.56)); // "1.2, 4.6"

formatPoint3d

Settings

Member Visibility

On This Page

Linear distances and coordinatesAnglesOut of scope
Constructors
Methods