GitHub source

evo.objects.typed.block_model_ref.BlockModel

A GeoscienceObject representing a block model.

This object acts as a proxy, allowing you to access block model data and attributes through the Block Model Service while the reference itself is stored as a Geoscience Object.

Metadata-only operations (geometry, attributes, name) always work. Data operations (to_dataframe, add_attribute, create_report, etc.) require the evo-blockmodels package to be installed: pip install evo-objects[blockmodels]

Example usage:

# Create a new regular block model
data = RegularBlockModelData(
    name="My Block Model",
    origin=Point3(x=0, y=0, z=0),
    n_blocks=Size3i(nx=10, ny=10, nz=5),
    block_size=Size3d(dx=2.5, dy=5.0, dz=5.0),
    cell_data=my_dataframe,
)
bm = await BlockModel.create_regular(context, data)

# Get an existing block model
bm = await BlockModel.from_reference(context, reference)

# Access geometry
print(f"Origin: {bm.geometry.origin}")
print(f"Size: {bm.geometry.n_blocks}")

# Access data through the Block Model Service (requires evo-blockmodels)
df = await bm.to_dataframe(columns=["*"])

# Create a new attribute on the block model (requires evo-blockmodels)
await bm.add_attribute(data_df, "new_attribute")

attributes 

attributes: BlockModelAttributes

The attributes available on this block model.

get_attribute 

get_attribute(name: str) -> BlockModelAttribute | None

Get an attribute by name.

Parameters:

Name Type Description Default
name str

The name of the attribute.

 required

Returns:

Type Description
BlockModelAttribute | None

The attribute, or None if not found.

get_block_model_metadata 

get_block_model_metadata() -> BlockModelMetadata

Get the full block model metadata from the Block Model Service.

Returns:

Type Description
BlockModel

The BlockModel metadata from the Block Model Service.

get_versions 

get_versions() -> list[Version]

Get all versions of this block model.

Returns:

Type Description
list[Version]

List of versions, ordered from newest to oldest.

to_dataframe 

to_dataframe(
    columns: list[str] | None = None,
    version_uuid: UUID | None | Literal["latest"] = "latest",
    fb: IFeedback = NoFeedback,
) -> pd.DataFrame

Get block model data as a DataFrame.

This is the preferred method for accessing block model data. It retrieves the data from the Block Model Service and returns it as a pandas DataFrame.

Parameters:

Name Type Description Default
columns list[str] | None

List of column names to retrieve. Defaults to all columns ["*"].

 None
version_uuid UUID | None | Literal['latest']

Specific version to query. Use "latest" (default) to get the latest version, or None to use the version referenced by this object.

 'latest'
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
DataFrame

DataFrame containing the block model data with user-friendly column names. Example: >>> df = await block_model.to_dataframe() >>> df.head()

refresh 

refresh() -> BlockModel

Refresh this block model object with the latest data from the server.

Use this after a remote operation (like kriging) has updated the block model to see the newly added attributes.

Returns:

Type Description
BlockModel

A new BlockModel instance with refreshed data. Example: >>> # After running kriging that adds attributes... >>> block_model = await block_model.refresh() >>> block_model.attributes # Now shows the new attributes

add_attribute 

add_attribute(data: DataFrame, attribute_name: str, unit: str | None = None, fb: IFeedback = NoFeedback) -> Version

Add a new attribute to the block model.

The DataFrame must contain geometry columns (i, j, k) or (x, y, z) and the attribute column to add.

Parameters:

Name Type Description Default
data DataFrame

DataFrame containing geometry columns and the new attribute.

 required
attribute_name str

Name of the attribute column in the DataFrame to add.

 required
unit str | None

Optional unit ID for the attribute (must be a valid unit ID from the Block Model Service).

 None
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
Version

The new version created by adding the attribute.

update_attributes 

update_attributes(
    data: DataFrame,
    new_columns: list[str] | None = None,
    update_columns: set[str] | None = None,
    delete_columns: set[str] | None = None,
    units: dict[str, str] | None = None,
    fb: IFeedback = NoFeedback,
) -> Version

Update attributes on the block model.

Parameters:

Name Type Description Default
data DataFrame

DataFrame containing geometry columns and attribute data.

 required
new_columns list[str] | None

List of new column names to add.

 None
update_columns set[str] | None

Set of existing column names to update.

 None
delete_columns set[str] | None

Set of column names to delete.

 None
units dict[str, str] | None

Dictionary mapping column names to unit IDs (must be valid unit IDs from the Block Model Service).

 None
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
Version

The new version created by the update.

create_regular 

create_regular(
    context: IContext, data: RegularBlockModelData, path: str | None = None, fb: IFeedback = NoFeedback
) -> Self

Create a new regular block model.

This creates a block model in the Block Model Service and a corresponding Geoscience Object reference.

Parameters:

Name Type Description Default
context IContext

The context containing environment, connector, and cache.

 required
data RegularBlockModelData

The data defining the regular block model to create.

 required
path str | None

Optional path for the Geoscience Object.

 None
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
Self

A new BlockModel instance.

set_attribute_units 

set_attribute_units(units: dict[str, str], fb: IFeedback = NoFeedback) -> BlockModel

Set units for attributes on this block model.

This is required before creating reports, as reports need columns to have units defined.

Parameters:

Name Type Description Default
units dict[str, str]

Dictionary mapping attribute names to unit IDs (e.g., {"Au": "g/t", "density": "t/m3"}).

 required
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
BlockModel

The updated BlockModel instance (refreshed from server). Example: >>> from evo.blockmodels import Units >>> block_model = await block_model.set_attribute_units({ ... "Au": Units.GRAMS_PER_TONNE, ... "density": Units.TONNES_PER_CUBIC_METRE, ... })

create_report 

create_report(data: ReportSpecificationData, fb: IFeedback = NoFeedback) -> Report

Create a new report specification for this block model.

Reports require: 1. Columns to have units set (use set_attribute_units() first) 2. At least one category column for grouping (e.g., domain, rock type)

Parameters:

Name Type Description Default
data ReportSpecificationData

The report specification data.

 required
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
Report

A Report instance representing the created report. Example: >>> from evo.blockmodels.typed import ReportSpecificationData, ReportColumnSpec, ReportCategorySpec >>> report = await block_model.create_report(ReportSpecificationData( ... name="Gold Resource Report", ... columns=[ReportColumnSpec(column_name="Au", aggregation="WEIGHTED_MEAN", output_unit_id="g/t")], ... categories=[ReportCategorySpec(column_name="domain")], ... mass_unit_id="t", ... density_value=2.7, ... density_unit_id="t/m3", ... )) >>> report # Pretty-prints with BlockSync link

list_reports 

list_reports(fb: IFeedback = NoFeedback) -> list[Report]

List all report specifications for this block model.

Parameters:

Name Type Description Default
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
list[Report]

List of Report instances.