Units in BMS

Introduction

To create reports on block model data, BMS requires an understanding of the units for each type of data involved, including the following:

• The size unit for the block model.
• Density information about the block model.
• The unit (and unit type) for each column to be reported on.

The API supports retrieving information about available units, and configuring units on the relevant resources.

Units information

The list of supported units can be retrieved from the Request a list of units endpoint. Each unit has the following properties:

• unit_uuid: UUID; BMS internal identifier.
• unit_id: String; identifier used in the API. This will match the geoscience unit schema enumeration where available.
• symbol: String; Unicode display symbol.
• description: String; short description of the unit.
• unit_type: The broad type of unit, indicating its dimensionality (mass, mass per unit volume, etc.)
• conversion_factor: The factor for converting from this unit to the reference unit for this unit type. For example, for grams, this would be 0.001 as 1 gram equals 0.001 kg. This is for internal purposes in reporting, for doing conversions between source and destination units. The reference units are:
  • LENGTH: m (metres)
  • MASS: kg (kilograms)
  • VOLUME: m3 (cubic metres)
  • VALUE: $ (dollars)
  • MASS_PER_VOLUME: kg/m3 (kilograms per cubic metre)
  • VOLUME_PER_VOLUME: m3/m3 (cubic metres per cubic metre, a dimensionless ratio)
  • MASS_PER_MASS: kg/kg (kilograms per kilogram, a dimensionless ratio)
  • VALUE_PER_MASS: $/kg (dollars per kilogram)

GET /blockmodel/orgs/{org_id}/units

[
    ...
    {
        "unit_uuid": "1d0d812f-90f5-4857-b22c-40af40e9e2d2",
        "unit_id": "g/m3",
        "symbol": "g/m³",
        "description": "Grams per cubic metre",
        "unit_type": "MASS_PER_VOLUME",
        "conversion_factor": 0.001
    },
    {
        "unit_uuid": "450d812f-90f5-4857-b22c-40af40e9e2d2",
        "unit_id": "cm3",
        "symbol": "cm³",
        "description": "Cubic centimetres",
        "unit_type": "VOLUME",
        "conversion_factor": 0.000001
    },
    {
        "unit_uuid": "330d812f-90f5-4857-b22c-40af40e9e2d2",
        "unit_id": "g/t",
        "symbol": "g/t",
        "description": "Grams per tonne",
        "unit_type": "MASS_PER_MASS",
        "conversion_factor": 0.000000001
    }
    ...
]

Block model size units

The BMS API supports an optional property on block models, size_unit_id. This indicates the unit for the block size. The value should be the unit_id of the relevant unit, and should be of unit_type LENGTH. For existing versions, size_unit_id will default to null.

The size_unit_id property is settable via the following endpoints:

• Create a block model
• Update a block model's metadata

If set, it is visible in the response of the following endpoints:

• List all block models in a workspace
• List all block models in an organization
• Get a block model's metadata

Column units

The BMS API supports an optional property when configuring version columns, unit_id, indicating the unit for the column's data. The value should be the unit_id of the relevant unit. For existing columns, this will default to null.

The property is settable via the Start a block model data update endpoint.

New columns

For new columns, as a new optional property unit_id in the column definition.

Column updates

For updating the unit_id and title for existing columns, there is an operation called update_metadata. This operation will accept a list of column changes, containing title and unit_id. Both title and unit_id are optional, and the column property will only be updated if set (i.e. non-null). Versioning and validation rules for updating titles are equivalent to a rename operation. A column cannot be modified by both rename and update_metadata.

PATCH /blockmodel/orgs/{org_id}/workspaces/{workspace_id}/block-models/{bm_uuid}/blocks

{
    "comment": "Rename and update unit for 'existing title'",
    "columns": {
        "new": [],
        "delete": [],
        "update": [],
        "rename": [],
        "update_metadata": [
            {
                "title": "existing_title",
                "values": {
                    "title": "new_title",
                    "unit_id": "g/t"
                }
            }
        ]
    }
}

For details on allowed combinations with update_metadata, please see Allowed combinations of new, update, rename, delete, and update_metadata.

Version responses

Columns in version responses include the unit_id property. In version listing endpoint responses, there is also a top level property referenced_units, which is a list of all unit objects that are referenced by any column (including all the unit properties).

Example response: List version metadata for all versions of a block model

{
    "count": 2,
    "total": 2,
    "limit": 50,
    "offset": 0,
    "referenced_units": [
        {
            "unit_uuid": "1d0d812f-90f5-4857-b22c-40af40e9e2d2",
            "unit_id": "g/m3",
            "symbol": "g/m³",
            "description": "Grams per cubic metre",
            "unit_type": "MASS_PER_VOLUME",
            "conversion_factor": 0.001
        },
        {
            "unit_uuid": "780d812f-90f5-4857-b22c-40af40e9e2d2",
            "unit_id": "ppm",
            "symbol": "ppm[mass]",
            "description": "Parts per million",
            "unit_type": "MASS_PER_MASS",
            "conversion_factor": 0.000001
        }
    ],
    "results": [
        {
            "base_version_id": 1,
            "bbox": {
                "i_minmax": {
                    "max": 16,
                    "min": 2
                },
                "j_minmax": {
                    "max": 22,
                    "min": 2
                },
                "k_minmax": {
                    "max": 28,
                    "min": 2
                }
            },
            "bm_uuid": "1d0d812f-90f5-4857-b22c-40af40e9e2d2",
            "comment": "Example comment for new version of regular block model",
            "created_at": "2023-10-26T03:56:38.320876+00:00",
            "created_by": {
                "email": "joebloggs@example.com",
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Joe Bloggs"
            },
            "mapping": {
                "columns": [
                    {
                        "col_id": "i",
                        "data_type": "UInt32",
                        "title": "i",
                        "unit_id": null
                    },
                    {
                        "col_id": "j",
                        "data_type": "UInt32",
                        "title": "j",
                        "unit_id": null
                    },
                    {
                        "col_id": "k",
                        "data_type": "UInt32",
                        "title": "k",
                        "unit_id": null
                    },
                    {
                        "col_id": "version_id",
                        "data_type": "UInt32",
                        "title": "version_id",
                        "unit_id": null
                    },
                    {
                        "col_id": "a11d504f-db6e-487b-af28-bba73a4e5d4a",
                        "data_type": "Float64",
                        "title": "silver",
                        "unit_id": "ppm"
                    },
                    {
                        "col_id": "e20430af-7d55-49bf-bb37-237202de8e9f",
                        "data_type": "Int64",
                        "title": "gold",
                        "unit_id": "ppm"
                    },
                    {
                        "col_id": "891821a5-2a4f-4e6d-9450-e1772c2baec6",
                        "data_type": "Float64",
                        "title": "platinum",
                        "unit_id": "ppm"
                    },
                    {
                        "col_id": "10c3ba83-b274-4a8f-94c7-62f117f007f7",
                        "data_type": "Float64",
                        "title": "diorite",
                        "unit_id": "g/m3"
                    },
                    {
                        "col_id": "4959037f-5070-4d09-8bfb-82e146a4595e",
                        "data_type": "Utf8",
                        "title": "redstone",
                        "unit_id": "g/m3"
                    }
                ]
            },
            "parent_version_id": 1,
            "version_id": 2,
            "version_uuid": "5bdfb83c-ac40-4b31-a70b-f1f3347c78e3"
        },
        {
            "base_version_id": null,
            "bbox": null,
            "bm_uuid": "1d0d812f-90f5-4857-b22c-40af40e9e2d2",
            "comment": "First revision.",
            "created_at": "2023-10-26T03:55:48.851220+00:00",
            "created_by": {
                "email": "joebloggs@example.com",
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Joe Bloggs"
            },
            "mapping": {
                "columns": [
                    {
                        "col_id": "i",
                        "data_type": "UInt32",
                        "title": "i",
                        "unit_id": null
                    },
                    {
                        "col_id": "j",
                        "data_type": "UInt32",
                        "title": "j",
                        "unit_id": null
                    },
                    {
                        "col_id": "k",
                        "data_type": "UInt32",
                        "title": "k",
                        "unit_id": null
                    },
                    {
                        "col_id": "version_id",
                        "data_type": "UInt32",
                        "title": "version_id",
                        "unit_id": null
                    }
                ]
            },
            "parent_version_id": 0,
            "version_id": 1,
            "version_uuid": "367f5aef-9fda-4cea-9b83-46a3ed0d01e9"
        }
    ]
}