iTwin model data - element property Unit discovery and conversions

[rhaines57]

A while back I posted a discussion to the iTwins forum about getting UOM for a model.
#7507

The answers given by Colin and Grigas were great and helped me understand what it would take to potentially read UOM/Units at a model level.

Since that post, my project requirements have changed a little. Now, in our system we have a need to run calculations on both metric values (the raw - full precision value we get from iTwins - getElementProperties()) and an imperial (raw value converted to imperial) value for a given model element property. I’m also trying to relate the KindOfQuantity information from the forum discussion, to what we are needing to do when pulling the data.

What I’m hoping for is to end up with a property that has the following:
"Length": {
"type": "primitive",
"displayValue": "119.444003 ft (US Survey)",
"value": "36.40660491862099",
"imperialValue": "119.444003",
"typeName": "double",
“dimension”: “Length”
},

To do these types of conversions at the time we’re reading the data, it seems like we’d need to know dimension (length, volume, weight, etc), which I believe you call phenomenon. Based on dimension we could convert the raw value to an imperial raw value and load both dimension and the new imperialValue into our system for future calculations.

There may be a better way to do all of this, and there may be some built-in functionality in iTwins that we can leverage to get what the result needed.

Can you please give me some guidance and how to achieve what we’re looking to do?
An example would be great if you have something.

Thanks

[hl662]

Hello,

If I got this right, it seems you'd like to go from querying for a KindOfQuantity like Length in your case, and be able to format Length values from metric to imperial (in code)?

Grigas had a good example in this reply, if you are looking to use the Presentation APIs.

I noticed you'd like to also know the phenomenon (what you refer as dimension) of the units associated with the KindOfQuantity? KindOfQuantityInfo contains the EC fullname for the persistence unit. You could then utilize a unitsProvider, like a SchemaUnitsProvider, to lookup that unit, and then retrieve the name for the phenomenon.

I have a quick example here that could show the workflow:

const koq = field.properties[0].property.kindOfQuantity; // a KindOfQuantityInfo, AecUnits.LENGTH for example
const persistenceUnitName = koq.persistenceUnit; // Could be Units.M
const persistenceUnit = await schemaUnitsProvider.findUnitByName(peristenceUnitName);
const phenomenon = persistenceUnit.phenomenon; // it would be Units.LENGTH, other imperial units like Units.US_SURVEY_FT or UNITS.FT will have the same phenomenon too

This link points to our Units schema, which all iModels will have. You can see by the highlighted portions that all of these different units that measure length have the same phenomenon that you would need.

Let me know if this wasn't too clear or doesn't fit what you were looking for.

[rhaines57]

Thanks @grigasp.

In processPrimativeValue the Field object I'm seeing has a single property that contains classInfo (id, label, name) a property name and a type (that we are pulling by extending ElementPropertiesPropertyItemBase). There is no property.kindOfQuantity object available.

Again, am I missing something?

Thanks

[rhaines57]

In digging a little more I found that a Field of type PropertiesField has a properties array and a property with kindOfQuantity.

Thanks again for all of your help @grigasp and @hl662!

[rhaines57]

Hi guys,

I do have one more question. I'm getting KindOfQuantity for a property just fine. I tried to use the KindOfQuanity label in place of using the SchemaUnitProvider to get Unit by name, but it's not the same value.

I'm trying to implement a schemaUnitProvider (as suggested by @hl662), using the following example from the iTwins documentation, but it's not intuitive.
https://www.itwinjs.org/learning/frontend/quantityformatting/

Do you have a better example somewhere?

The KOQ logic I added is in ElementPropertiesBuilder is this:
if (props.field.isPropertiesField()) {
const propertyField = props.field as PropertiesField;
const koq = propertyField.properties[0].property?.kindOfQuantity;
if (koq) {
property.unitType = koq?.label ?? "";
property.persistenceUnit = koq?.persistenceUnit ?? "";
property.unitsName = koq?.activeFormat?.composite?.units[0]?.name ?? "";
}
}

In my example using kog.label for property.unitType is not the same as phenomenon like I had hoped. It would have saved me extra processing by not needing to make the extra schemaUnitProvider call, but it's not the same.

The persistenceUnit and UnitsName are both looking good. With the correct phenomenon I should have everything I need.

Thanks.

[hl662]

The example could be improved, we'll take a 2nd look over that portion of documentation.

A schemaUnitProvider can be created when an iModelConnection is opened. onOpen events are emitted through IModelConnection. If we combine this with IModelApp.quantityFormatter.setUnitsProvider, we can then have a SchemaUnitsProvider that can be used across the app after IModelConnection is open.

Here's an example (before iTwin 5.0):

// This event can be set up at the start of the application
    IModelConnection.onOpen.addListener((imodel: IModelConnection) => {
      if (imodel.isBlankConnection()) return;

      const rpcProps = imodel.getRpcProps();
      const schemaContext = new ECSchemaRpcLocater(rpcProps)
      const schemaUnitsProvider = new SchemaUnitProvider(schemaContext);
      void IModelApp.quantityFormatter.setUnitsProvider(schemaUnitsProvider); // this is an async method, so can pass in 'void' at start, or do typical .then().catch() 
    });


// in another component somewhere else that needs the UnitProps
 ...
 const unitProps = await IModelApp.quantityFormatter.unitsProvider.findUnitByName(property.unitsName);

Starting in iTwin 5.0, it'll be easier to do the workflow above:

    IModelConnection.onOpen.addListener((imodel: IModelConnection) => {
      if (imodel.isBlankConnection()) return;
      const schemaUnitsProvider = new SchemaUnitProvider(imodel.schemaContext);
      void IModelApp.quantityFormatter.setUnitsProvider(schemaUnitsProvider);
    });

If a schemaUnitProvider isn't register onto IModelApp.quantityFormatter, we do have a BasicUnitProvider that is the default in IModelApp.quantityFormatter available before then, but we encourage users to replace it with a SchemaUnitProvider which is fully complete and can work with more Units than the default provided.

[rhaines57]

Thanks again @hl662 and @grigasp. Take care!