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
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 ( |
required |
Returns:
| Type | Description |
|---|---|
bool
|
False for unitless specs such as integers, text or yes/no |
Source code in pyrevitlib/pyrevit/revit/units.py
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: |
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
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: |
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
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
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
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
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
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
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
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
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
|
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
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
|
|
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.