Skip to content

units

Unit conversion utilities for Revit.

Attributes

Classes

Functions:

get_unit_info(spec_type_id, doc=None)

Return unit information for a spec in document units.

Parameters:

Name Type Description Default
spec_type_id SpecTypeId

spec type identifier

required
doc Document

Revit document, defaults to current

None

Returns:

Type Description
tuple

unit, unit label, symbol, symbol label

Source code in pyrevitlib/pyrevit/revit/units.py
def get_unit_info(spec_type_id, doc=None):
    """Return unit information for a spec in document units.

    Args:
        spec_type_id (DB.SpecTypeId): spec type identifier
        doc (DB.Document, optional): Revit document, defaults to current

    Returns:
        (tuple): unit, unit label, symbol, symbol label
    """
    if HOST_APP.is_older_than(2022):
        raise PyRevitException("get_unit_info() requires Revit 2022 or newer.")

    doc = doc or DOCS.doc

    format_options = doc.GetUnits().GetFormatOptions(spec_type_id)

    unit = format_options.GetUnitTypeId()
    unit_label = DB.LabelUtils.GetLabelForUnit(unit)

    symbol = format_options.GetSymbolTypeId()
    symbol_label = None
    if not symbol.Empty():
        symbol_label = DB.LabelUtils.GetLabelForSymbol(symbol)

    return unit, unit_label, symbol, symbol_label

is_measurable(spec)

Tell whether a parameter spec carries a unit.

Parameters:

Name Type Description Default
spec ForgeTypeId or UnitType

Revit 2022+ takes the parameter data type (Definition.GetDataType()), Revit 2021 takes Definition.UnitType

required

Returns:

Type Description
bool

False for unitless specs such as integers, text or yes/no

Source code in pyrevitlib/pyrevit/revit/units.py
def is_measurable(spec):
    """Tell whether a parameter spec carries a unit.

    Args:
        spec (DB.ForgeTypeId or DB.UnitType): Revit 2022+ takes the parameter
            data type (``Definition.GetDataType()``), Revit 2021 takes
            ``Definition.UnitType``

    Returns:
        (bool): False for unitless specs such as integers, text or yes/no
    """
    if HOST_APP.is_newer_than(2021):
        return DB.UnitUtils.IsMeasurableSpec(spec)
    return spec != DB.UnitType.UT_Undefined

display_unit_label(spec, doc=None)

Return the name of the display unit that a document uses for a spec.

The name is read from the unit and not from the unit symbol, because the symbol can be empty in a project.

Parameters:

Name Type Description Default
spec ForgeTypeId or UnitType

see :func:is_measurable

required
doc Document

Revit document, defaults to current

None

Returns:

Type Description
str

unit name, or an empty string for unitless specs

Source code in pyrevitlib/pyrevit/revit/units.py
def display_unit_label(spec, doc=None):
    """Return the name of the display unit that a document uses for a spec.

    The name is read from the unit and not from the unit symbol, because the
    symbol can be empty in a project.

    Args:
        spec (DB.ForgeTypeId or DB.UnitType): see :func:`is_measurable`
        doc (DB.Document, optional): Revit document, defaults to current

    Returns:
        (str): unit name, or an empty string for unitless specs
    """
    if not is_measurable(spec):
        return ""
    doc = doc or DOCS.doc
    format_options = doc.GetUnits().GetFormatOptions(spec)
    if HOST_APP.is_newer_than(2021):
        return DB.LabelUtils.GetLabelForUnit(format_options.GetUnitTypeId())
    return DB.LabelUtils.GetLabelFor(format_options.DisplayUnits)

format_value(value, spec, doc=None)

Format an internal value in the display units of a document.

Parameters:

Name Type Description Default
value float

internal value

required
spec ForgeTypeId or UnitType

see :func:is_measurable

required
doc Document

Revit document, defaults to current

None

Returns:

Type Description
str

value in display units. Unitless specs are shown as plain numbers, with two decimals unless the value is whole.

Source code in pyrevitlib/pyrevit/revit/units.py
def format_value(value, spec, doc=None):
    """Format an internal value in the display units of a document.

    Args:
        value (float): internal value
        spec (DB.ForgeTypeId or DB.UnitType): see :func:`is_measurable`
        doc (DB.Document, optional): Revit document, defaults to current

    Returns:
        (str): value in display units. Unitless specs are shown as plain
            numbers, with two decimals unless the value is whole.
    """
    if not is_measurable(spec):
        return str(int(value)) if value == int(value) else "{:.2f}".format(value)
    units = (doc or DOCS.doc).GetUnits()
    if HOST_APP.is_newer_than(2021):
        return DB.UnitFormatUtils.Format(
            units=units, specTypeId=spec, value=value, forEditing=False
        )
    return DB.UnitFormatUtils.Format(
        units=units,
        unitType=spec,
        value=value,
        maxAccuracy=False,
        forEditing=False,
    )

format_area(area_value, doc=None, append_symbol=False)

Return formatted area value in document units.

Parameters:

Name Type Description Default
area_value float

area value in Revit internal units (square feet)

required
doc Document

Revit document, defaults to current

None
append_symbol bool

append the unit symbol even when the project's area format does not show one

False

Returns:

Type Description
str

formatted value

Source code in pyrevitlib/pyrevit/revit/units.py
@automation.operation(
    "pyrevit.units.format-area",
    PlainEnglish="Format an internal area value using the project's display units.",
    mode="query",
    effects=("model.read",),
    inputs=("area_value: number", "append_symbol: boolean?"),
)
def format_area(area_value, doc=None, append_symbol=False):
    """Return formatted area value in document units.

    Args:
        area_value (float): area value in Revit internal units (square feet)
        doc (DB.Document, optional): Revit document, defaults to current
        append_symbol (bool, optional): append the unit symbol even when the
            project's area format does not show one

    Returns:
        (str): formatted value
    """
    return _format_in_document_units(area_value, doc, "Area", "UT_Area", append_symbol)

format_length(length_value, doc=None, append_symbol=False)

Return formatted length value in document units.

Parameters:

Name Type Description Default
length_value float

length value in Revit internal units (feet)

required
doc Document

Revit document, defaults to current

None
append_symbol bool

append the unit symbol even when the project's length format does not show one, e.g. "1804 mm" instead of "1804" for a metric project

False

Returns:

Type Description
str

formatted value

Source code in pyrevitlib/pyrevit/revit/units.py
@automation.operation(
    "pyrevit.units.format-length",
    PlainEnglish="Format an internal length value using the project's display units.",
    mode="query",
    effects=("model.read",),
    inputs=("length_value: number", "append_symbol: boolean?"),
)
def format_length(length_value, doc=None, append_symbol=False):
    """Return formatted length value in document units.

    Args:
        length_value (float): length value in Revit internal units (feet)
        doc (DB.Document, optional): Revit document, defaults to current
        append_symbol (bool, optional): append the unit symbol even when the
            project's length format does not show one, e.g. "1804 mm" instead
            of "1804" for a metric project

    Returns:
        (str): formatted value
    """
    return _format_in_document_units(
        length_value, doc, "Length", "UT_Length", append_symbol
    )

format_slope(slope_value, doc=None, append_symbol=False)

Return formatted slope value in document units.

Parameters:

Name Type Description Default
slope_value float

slope value in Revit internal units (rise over run)

required
doc Document

Revit document, defaults to current

None
append_symbol bool

append the unit symbol even when the project's slope format does not show one

False

Returns:

Type Description
str

formatted value

Source code in pyrevitlib/pyrevit/revit/units.py
@automation.operation(
    "pyrevit.units.format-slope",
    PlainEnglish="Format a rise-over-run slope using the project's display units.",
    mode="query",
    effects=("model.read",),
    inputs=("slope_value: number", "append_symbol: boolean?"),
)
def format_slope(slope_value, doc=None, append_symbol=False):
    """Return formatted slope value in document units.

    Args:
        slope_value (float): slope value in Revit internal units (rise over run)
        doc (DB.Document, optional): Revit document, defaults to current
        append_symbol (bool, optional): append the unit symbol even when the
            project's slope format does not show one

    Returns:
        (str): formatted value
    """
    return _format_in_document_units(
        slope_value, doc, "Slope", "UT_Slope", append_symbol
    )

project_to_viewport(xyz, view)

Project a point to viewport coordinates.

Parameters:

Name Type Description Default
xyz XYZ

point to project

required
view View

target view

required

Returns:

Type Description
UV

[description]

Source code in pyrevitlib/pyrevit/revit/units.py
def project_to_viewport(xyz, view):
    """Project a point to viewport coordinates.

    Args:
        xyz (DB.XYZ): point to project
        view (DB.View): target view

    Returns:
        (DB.UV): [description]
    """
    plane = _create_view_plane(view)
    uv, _ = plane.Project(xyz)
    return uv

project_to_world(uv, view)

Get view-based point (UV) back to model coordinates.

Parameters:

Name Type Description Default
uv UV

point on a view

required
view View

view to get coordinates from

required

Returns:

Type Description
XYZ

point in world coordinates

Source code in pyrevitlib/pyrevit/revit/units.py
def project_to_world(uv, view):
    """Get view-based point (UV) back to model coordinates.

    Args:
        uv (DB.UV): point on a view
        view (DB.View): view to get coordinates from

    Returns:
        (DB.XYZ): point in world coordinates
    """
    plane = _create_view_plane(view)
    trf = DB.Transform.Identity
    trf.BasisX = plane.XVec
    trf.BasisY = plane.YVec
    trf.BasisZ = plane.Normal
    trf.Origin = plane.Origin
    return trf.OfPoint(DB.XYZ(uv.U, uv.V, 0))

get_spec_name(forge_id)

Returns the measurable spec name for the given unit id.

Parameters:

Name Type Description Default
forge_id ForgeTypeId

Unit id

required

Returns:

Type Description
str

Spec name

Source code in pyrevitlib/pyrevit/revit/units.py
def get_spec_name(forge_id):
    """Returns the measurable spec name for the given unit id.

    Args:
        forge_id (DB.ForgeTypeId): Unit id

    Returns:
        (str): Spec name
    """
    if HOST_APP.is_newer_than(2021) and DB.UnitUtils.IsMeasurableSpec(forge_id):
        return DB.UnitUtils.GetTypeCatalogStringForSpec(forge_id)
    return ""

get_unit_name(forge_id)

Returns the unit name for the given unit id.

Parameters:

Name Type Description Default
forge_id ForgeTypeId

Unit id

required

Returns:

Type Description
str

Unit name

Source code in pyrevitlib/pyrevit/revit/units.py
def get_unit_name(forge_id):
    """Returns the unit name for the given unit id.

    Args:
        forge_id (DB.ForgeTypeId): Unit id

    Returns:
        (str): Unit name
    """
    if HOST_APP.is_newer_than(2021) and DB.UnitUtils.IsUnit(forge_id):
        return DB.UnitUtils.GetTypeCatalogStringForUnit(forge_id)
    return ""

parse_length(value)

Convert a length written the way drawings write it to Revit internal feet.

Parameters:

Name Type Description Default
value float | int | str

feet as a number, or a string such as 32'-6", 32' 6 1/2", 6", 12', 900mm, 90cm or 2.5m.

required

Returns:

Type Description
float

length in feet, Revit's internal length unit.

Raises:

Type Description
PyRevitException

when the string is not a length in a known format.

Note

Parses text independently of the document's units, then delegates conversion of the parsed double value to DB.UnitUtils.

Source code in pyrevitlib/pyrevit/revit/units.py
@automation.operation(
    "pyrevit.units.parse-length",
    PlainEnglish="Convert a written length to Revit internal feet.",
    mode="pure",
    context="none",
)
def parse_length(value):
    """Convert a length written the way drawings write it to Revit internal feet.

    Args:
        value (float | int | str): feet as a number, or a string such as
            ``32'-6"``, ``32' 6 1/2"``, ``6"``, ``12'``, ``900mm``, ``90cm``
            or ``2.5m``.

    Returns:
        (float): length in feet, Revit's internal length unit.

    Raises:
        PyRevitException: when the string is not a length in a known format.

    Note:
        Parses text independently of the document's units, then delegates
        conversion of the parsed double value to ``DB.UnitUtils``.
    """
    if isinstance(value, (int, float)):
        return _to_internal_length(value, "ft")
    text = str(value).strip()
    metric = _METRIC.match(text)
    if metric:
        return _to_internal_length(metric.group("value"), metric.group("unit"))
    imperial = _FEET_INCHES.match(text)
    if imperial and ("'" in text or '"' in text):
        feet = float(imperial.group("feet") or 0.0)
        inches = float(imperial.group("inches") or 0.0)
        if imperial.group("num"):
            inches += float(imperial.group("num")) / float(imperial.group("den"))
        sign = -1.0 if text.startswith("-") else 1.0
        return sign * (
            _to_internal_length(abs(feet), "ft") + _to_internal_length(inches, "in")
        )
    try:
        return _to_internal_length(text, "ft")
    except ValueError:
        raise PyRevitException(
            "Can't read length {!r}. Use feet as a number, 32'-6\", 6\", "
            "900mm or 2.5m.".format(value)
        )

parse_slope(value)

Convert a roof pitch to rise over run, the value Revit's slope APIs take.

Parameters:

Name Type Description Default
value float | int | str

"8:12", "8/12" or "8 in 12" (0.667), "30deg" (tan of 30 degrees), or a rise/run number.

required

Returns:

Type Description
float

rise over run.

Raises:

Type Description
PyRevitException

when the string is not a pitch in a known format, or its run is zero.

Important

FootPrintRoof.set_SlopeAngle and the ROOF_SLOPE parameter take rise over run, not degrees or radians. Passing 33.69 for an 8:12 roof builds a roof hundreds of feet tall.

Source code in pyrevitlib/pyrevit/revit/units.py
@automation.operation(
    "pyrevit.units.parse-slope",
    PlainEnglish="Convert a written roof pitch to rise over run.",
    mode="pure",
    context="none",
)
def parse_slope(value):
    """Convert a roof pitch to rise over run, the value Revit's slope APIs take.

    Args:
        value (float | int | str): ``"8:12"``, ``"8/12"`` or ``"8 in 12"``
            (0.667), ``"30deg"`` (tan of 30 degrees), or a rise/run number.

    Returns:
        (float): rise over run.

    Raises:
        PyRevitException: when the string is not a pitch in a known format,
            or its run is zero.

    Important:
        ``FootPrintRoof.set_SlopeAngle`` and the ``ROOF_SLOPE`` parameter
        take rise over run, not degrees or radians. Passing 33.69 for an
        8:12 roof builds a roof hundreds of feet tall.
    """
    if isinstance(value, (int, float)):
        return float(value)
    text = str(value).strip()
    try:
        return float(text)
    except ValueError:
        pass
    ratio = _SLOPE_RATIO.match(text)
    if ratio:
        run = float(ratio.group("run"))
        if run == 0:
            raise PyRevitException("Pitch {!r} has a run of zero.".format(value))
        return float(ratio.group("rise")) / run
    degrees = _SLOPE_DEGREES.match(text)
    if degrees:
        return math.tan(math.radians(float(degrees.group("deg"))))
    raise PyRevitException(
        "Can't read pitch {!r}. Use '8:12', '30deg' or a rise/run number.".format(value)
    )