BlockModel

GitHub source

BlockModel

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.