Creating a block model

Introduction

Creating a block model is the foundational step for subsequent update and query operations. In order to do this, you need to hit multiple endpoints to complete the workflow:

The initial create request.
Polling the job URL.

Initial create request

This is done via the Create a block model endpoint. This is the initial request that starts the block model creation workflow, where the server validates the request body.
A successful response from the server contains the details of the block model made in the initial request, as well as a job_url that can be polled to check the status of the creation job.

The following is an example request body for making this initial request.

{   
    "name": "Block model name",
    "description": "Block model description",
    "comment": "Create a block model",
    "model_origin": {
        "x": -5,
        "y": 0,
        "z": 2
    },
    "block_rotation": [
        {
            "axis": "x",
            "angle": 10
        },
        {
            "axis": "z",
            "angle": 5.5
        },
        {
            "axis": "x",
            "angle": 7.5
        }
    ],
    "size_options": {
        "model_type": "regular",
        "block_size": {
            "x": 25,
            "y": 25,
            "z": 25
        },
        "n_blocks": {
            "nx": 48,
            "ny": 68,
            "nz": 40
        }
    },
    "coordinate_reference_system": "EPSG:27200",
    "size_unit_id": "m"
}

Definitions of payload fields as follows:

name (Required)
description (Optional)
comment (Optional)
model_origin (Required)
block_rotation (Required)
size_options (Required)
coordinate_reference_system (Optional)
size_unit_id (Optional)

`name` (Required)

The name field specifies the name of the block model to be created. Block model names must be unique within a workspace.

`description` (Optional)

The description field specifies a basic description of the block model.

`comment` (Optional)

The comment field enables the users to provide additional context or notes regarding the creation operation of the block model.

`model_origin` (Required)

The model_origin field represents the offset of the model relative to the XYZ origin. It is a dictionary containing the model origin in $x$ , $y$ , $z$ coordinates. If the block model has not been rotated, this point would be the minimum $x$ , $y$ , $z$ corner of the block model. The expected format is as follows.

"model_origin": {
    "x": float,
    "y": float,
    "z": float
}

`block_rotation` (Required)

The block_rotation field defines the rotation of the block model through a list of clockwise rotations around given axes. It consists of an array of up to three dictionaries of rotation items, each specifying an angle and axis (x, y, or z). Two rotations around the same axis cannot be consecutive items within the list of rotations. For more details, please see the Rotations page. The expected format is as follows.

"block_rotation": [
    {
        "axis": "axis",
        "angle": float
    },
    {
        "axis": "axis",
        "angle": float
    },
    {
        "axis": "axis",
        "angle": float
    }
],

If no rotation is required for a particular axis, the dictionary for this axis can be ignored.
If no rotation is required for the model, the array itself can be left empty.

`size_options` (Required)

The size_options field is a dictionary containing model size options. The options differ slightly, depending upon the model type selected.

If `model_type` is regular

block_size: The size of blocks in the $x$ , $y$ , and $z$ axes. The values for x, y, and z must be greater than 0 but less than 1,000,000.
n_blocks: The number of blocks in the $x$ , $y$ , and $z$ axes. Note that the total number of blocks must not exceed 500,000,000.
The expected format is as follows.

"size_options": {
    "model_type": "regular",
    "block_size": {
        "x": float,
        "y": float,
        "z": float
    },
    "n_blocks": {
        "nx": int,
        "ny": int,
        "nz": int
    }
}

If `model_type` is variable-octree

n_parent_blocks: The number of parent blocks in the $x$ , $y$ , and $z$ axes. Note that the total number of parent blocks must not exceed 500,000,000.
n_subblocks_per_parent: The number of sub-blocks per parent block in the $x$ , $y$ , and $z$ axes. Accepted values for nx, ny, and nz on each axis are 1, 2, 4, 8, 16, 32, or 64. For more details, see variable octree models.
parent_block_size: The size of parent blocks in the $x$ , $y$ , and $z$ axes. The values for x, y, and z must be greater than 0 but less than 1,000,000.
The expected format is as follows.

"size_options": {
    "model_type": "variable-octree",
    "n_parent_blocks": {
        "nx": int,
        "ny": int,
        "nz": int
    },
    "n_subblocks_per_parent": {
        "nx": int,
        "ny": int,
        "nz": int
    },
    "parent_block_size": {
        "x": float,
        "y": float,
        "z": float
    }
}

If `model_type` is fully-sub-blocked

n_parent_blocks: The number of parent blocks in the $x$ , $y$ , and $z$ axes. Note that the total number of parent blocks must not exceed 500,000,000.
n_subblocks_per_parent: The number of sub-blocks per parent block in the $x$ , $y$ , and $z$ axes. The values for nx, ny, and nz must be integers within the range of 1 to 100.
parent_block_size: The size of parent blocks in the $x$ , $y$ , and $z$ axes. The values for x, y, and z must be greater than 0 but less than 1,000,000.
The expected format is as follows.

"size_options": {
    "model_type": "fully-sub-blocked",
    "n_parent_blocks": {
        "nx": int,
        "ny": int,
        "nz": int
    },
    "n_subblocks_per_parent": {
        "nx": int,
        "ny": int,
        "nz": int
    },
    "parent_block_size": {
        "x": float,
        "y": float,
        "z": float
    }
}

If `model_type` is flexible

n_parent_blocks: The number of parent blocks in the $x$ , $y$ , and $z$ axes. Note that the total number of parent blocks must not exceed 500,000,000.
n_subblocks_per_parent: The number of sub-blocks per parent block in the $x$ , $y$ , and $z$ axes. The values for nx, ny, and nz must be integers within the range of 1 to 100.
parent_block_size: The size of parent blocks in the $x$ , $y$ , and $z$ axes. The values for x, y, and z must be greater than 0 but less than 1,000,000.
The expected format is as follows.

"size_options": {
    "model_type": "flexible",
    "n_parent_blocks": {
        "nx": int,
        "ny": int,
        "nz": int
    },
    "n_subblocks_per_parent": {
        "nx": int,
        "ny": int,
        "nz": int
    },
    "parent_block_size": {
        "x": float,
        "y": float,
        "z": float
    }
}

`coordinate_reference_system` (Optional)

The coordinate_reference_system field specifies the coordinate reference system used for the block model definition (its origin and dimensions). See Coordinate reference systems for more information.

`size_unit_id` (Optional)

The size_unit_id field specifies the ID of the unit that block sizes are measured in. The unit should be of unit_type LENGTH. This is required for reports to be run on the block model. size_unit_id should match the unit of the coordinate reference system, if defined.

Polling the job URL

After the initial request is successfully processed, the server will return the details of the block model to be created, along with a job_url. You may periodically poll the URL via the Request job status/result endpoint to monitor the current status of the creation job until the job_status changes to COMPLETE. Attempting to perform the next operation on the block model before the completion of the current task may lead to errors. The response from the server will vary based on the job_status field, which is further explained below.

Job status: `QUEUED` or `PROCESSING`

QUEUED: This means that the creation job is currently queued and waiting to be picked up for processing.
PROCESSING: This means that a compute node is currently processing the job.

{
    "job_status": "QUEUED" | "PROCESSING" 
}

Job status: `COMPLETE`

This means that the creation job has successfully completed and the block model is fully created and ready for use. The response will also contain the field payload, which will contain the initial Version object created in the server for the block model.

{
    "job_status": "COMPLETE",
    "payload": {
        "bm_uuid": "a5675b96-3818-46f0-9f29-cb33a2c49ccf",
        "comment": "Create a block model",
        "created_at": "2023-10-29T23:16:24.734543+00:00",
        "created_by": {
            "email": "joebloggs@example.com",
            "id": "ed19712e-f420-4003-8e28-8cf0fdf027a8",
            "name": "Joe Bloggs"
        },
        "mapping": {
            "columns": [
                {
                    "col_id": "i",
                    "title": "i",
                    "data_type": "UInt32"
                },
                {
                    "col_id": "j",
                    "title": "j",
                    "data_type": "UInt32"
                },
                {
                    "col_id": "k",
                    "title": "k",
                    "data_type": "UInt32"
                },
                {
                    "col_id": "version_id",
                    "title": "version_id",
                    "data_type": "UInt32"
                }
            ]
        },
        "parent_version_id": 0,
        "version_id": 1,
        "version_uuid": "212849b2-c9cd-41fc-b5b2-139185f23dbc",
        "geoscience_version_id": "1732676747836307217"
    }
}

Job status: `FAILED`

This means that the creation job failed during processing. The response will also contain the field payload, which will contain an error message from the compute service explaining why the block model creation failed. If the failure is due to a 500 error, a support ticket should be raised.

{
    "job_status": "FAILED",
    "payload": {
        "status": 500,
        "title": "Internal Service Error",
        "detail": "A service error occurred when processing this job",
        "type": "https://seequent.com/error-codes/block-model-service/compute-service-error"
    }
}

Introduction​

Initial create request​

name (Required)​

description (Optional)​

comment (Optional)​

model_origin (Required)​

block_rotation (Required)​

size_options (Required)​

If model_type is regular​

If model_type is variable-octree​

If model_type is fully-sub-blocked​

If model_type is flexible​

coordinate_reference_system (Optional)​

size_unit_id (Optional)​

Polling the job URL​

Job status: QUEUED or PROCESSING​

Job status: COMPLETE​

Job status: FAILED​