Skip to content

Block Model🍋

BlockModel 🍋

Bases: GridObject

A BlockModel is considered cartesian/XYZ oriented with fixed cell size. The cells may not be contiguous and don't have to all be defined. The grid is considered cell-centered.

For instance, a block model can be of shape 5 x 3 x 2 but only have 3 cells defined at [1, 2, 1], [1, 3, 1] and [2, 3, 1].

Grid dimensions and cell sizes are inferred from the X, Y, Z geometry. The grid is assumed to be cartesian and to have a constant cell size.

Parameters:

Name Type Description Default
name str

object name.

 required
xyz Optional[Data]

cell centers of the block model.

 None
atol float

absolute tolerance used to automatically calculate the cell dimension. It is the distance tolerance (same unit as xyz) to consider whether the dimensions of all cells can be considered equal. Defaults to 0.001.

 0.001
cell_size Optional[Vector]

bypass automatic cell size inference and enforce cell size. Note that the shape and origin of the Block Model is directly computed from the cell size: providing an erroneous cell size may have undesirable side effects.

 None

Raises:

Type Description
ValueError
  • Variable cell size is inferred and cell_size is not provided.
  • There is a single cell in one of the axes and cell_size is not provided.
  • If the provided cell_size does not have 3 dimensions.
  • If the provided cell_size has negative values.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
bm = geo.BlockModel("MyBM", xyz)

azimuth property 🍋

Return the azimuth angle of the grid.

Returns:

Type Description
Optional[Angles]

The azimuth of the grid.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2], azimuth=60)
vx.azimuth
Output
60

builtins property 🍋

Return the built-in object property names, defaults to X, Y, Z.

Returns:

Type Description
List[str]

Built-in property names.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.builtins
Output
['X', 'Y', 'Z']

default_support property 🍋

Return the default support type use for setting/getting attributes in the database.

Returns:

Type Description
AttributeSupportType

The default support type.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.default_support
Output
<AttributeSupportType.NODE: 'NODE'>

dimension property 🍋

Return the number of dimensions of the grid (2D, 3D, 4D, etc.).

Returns:

Type Description
int

The number of dimensions.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.dimension
Output
3

n_cells property 🍋

Return the total number of cells.

Returns:

Type Description
int

The product of the number of cells in each dimension.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.n_cells
Output
24

name property writable 🍋

Return the object name.

Returns:

Type Description
str

Object name.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.name
Output
'MyPointCloud'

origin property 🍋

Return the origin of the grid.

Returns:

Type Description
Vector

Grid origin 3D point (X, Y, Z).

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.origin
Output
array([0., 0., 0.])

shape property 🍋

Return the shape of the grid in each direction.

Returns:

Type Description
ndarray

Grid shape as list.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.shape
Output
array([4, 3, 2])

volume property 🍋

Return the volume of the grid.

Returns:

Type Description
float

Grid volume.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.volume()
Output
24.0

aggregate(properties=None, agg_methods=None) 🍋

Return the object data grouped by location (X, Y) and grid index (U, V).

Parameters:

Name Type Description Default
properties Optional[Union[List[str], str]]

list of properties name to transfer to the GIS Object. Setting to None or empty list will select all existing properties.

 None
agg_methods Optional[Union[AggregationMethod, Callable, List[Union[AggregationMethod, Callable]]]]

aggregation data methods. See Pandas - Group By to find out supported methods. Defaults to first.

 None

Returns:

Type Description
DataFrame

DataFrame of XY coordinates with aggregated data.

Raises:

Type Description
ValueError
  • No aggregation method is provided.
  • 'X', 'Y', 'U' or 'V' are part of the properties.
AttributeError

One of the aggregation methods is not supported.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.aggregate()
Output
    X    Y  U  V  Z_first  W_first
0   0.5  0.5  0  0      0.5        0
1   0.5  1.5  0  1      0.5        0
2   0.5  2.5  0  2      0.5        0
3   1.5  0.5  1  0      0.5        0
4   1.5  1.5  1  1      0.5        0
5   1.5  2.5  1  2      0.5        0
6   2.5  0.5  2  0      0.5        0
7   2.5  1.5  2  1      0.5        0
8   2.5  2.5  2  2      0.5        0
9   3.5  0.5  3  0      0.5        0
10  3.5  1.5  3  1      0.5        0
11  3.5  2.5  3  2      0.5        0

axis(axis=None) 🍋

Return the cell unit vector for the given axis. If axis is not provided, the sum of all vectors is returned.

Parameters:

Name Type Description Default
axis Optional[Axis]

given axis to get the vector from. If None, the sum of all axes is computed.

 None

Returns:

Type Description
Vector

Grid directional vector (X, Y, Z).

Raises:

Type Description
ValueError

Axis is out of dimensions when provided.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.axis(1)
vx.axis()
Output
array([0., 1., 0.])
array([1., 1., 1.])

bounds(region=None) 🍋

Return the object bounds, respectively separate minimum and maximum X, Y and Z.

Parameters:

Name Type Description Default
region Optional[str]

name of the region or condition to optionally filter the data to be returned.

 None

Returns:

Type Description
ndarray

XYZ bounding coordinates.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.bounds()
Output
array([[ 0,  1,  2],
    [27, 28, 29]])

centroid(region=None) 🍋

Return the object centroid, respectively separate mean X, Y and Z.

Parameters:

Name Type Description Default
region Optional[str]

name of the region or condition to optionally filter the data to be returned.

 None

Returns:

Type Description
ndarray

XYZ centroid coordinates.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.centroid()
Output
array([13.5, 14.5, 15.5])

check_coords_bounds(coords) 🍋

Check whether grid coordinates are out of bounds or not. If true, the exception will be returned, otherwise None.

Parameters:

Name Type Description Default
coords Vector

grid coordinates as (dimension,) or (N, dimension)

 required

Returns:

Name Type Description
ValueError ValueError

containing the error or None if coordinates are valid.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.check_coords_bounds([0,0,0])
Output


import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.check_coords_bounds([3,5,0])
Output
ValueError('idx 5.0 is out of bounds [0, 2] for axis 1')

convert_to_gis_object(name, properties=None, agg_methods=None, region=None, region_agg=None) 🍋

Create a new GISObject from the GeoRefObject. The original GeoRefObject is not modified.

Parameters:

Name Type Description Default
name str

name of the GISObject to create.

 required
properties Optional[Union[List[str], str]]

list of properties name to transfer to the GIS Object. Setting to None or empty list will select all existing properties.

 None
agg_methods Optional[Union[AggregationMethod, Callable, List[Union[AggregationMethod, Callable]]]]

aggregation data methods. See Pandas - Group By to find out supported methods. Defaults to first.

 None
region Optional[str]

Object region or condition to select data from.

 None
region_agg Optional[RegionAggregationMethod]

Aggregation region method.

 None

Returns:

Type Description
GISObject

GeoLime GISObject.

Raises:

Type Description
ValueError

'X' or 'Y' are part of the properties.
AttributeError

One of the aggregation methods is not supported.

coords(region=None) 🍋

Return the object coordinates, respectively X, Y, and Z as data arrays.

Parameters:

Name Type Description Default
region Optional[str]

name of the region or condition to optionally filter the data to be returned.

 None

Returns:

Type Description
ndarray

XYZ coordinates.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.coords()
Output
array([[ 0,  1,  2],
    [ 3,  4,  5],
    [ 6,  7,  8],
    [ 9, 10, 11],
    [12, 13, 14],
    [15, 16, 17],
    [18, 19, 20],
    [21, 22, 23],
    [24, 25, 26],
    [27, 28, 29]])

coords2idx(coords) 🍋

Get the global grid index of the cell corresponding to the given (U, V, W) coordinates. See idx2coords() for inverse function.

Parameters:

Name Type Description Default
coords Union[List[int], List[List[int]], ndarray]

Grid coordinates as (n_dim,) or (N, n_dim)

 required

Returns:

Type Description
Union[int, ndarray]

The global index or list of indices.

Raises:

Type Description
ValueError

Grid coords are out of bounds.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.coords2idx([1, 0, 0])
Output
1

coords2xyz(coords) 🍋

Get the (X, Y, Z) coordinates of the center of the cell corresponding to the given coordinate indices. Note that it returns the theoretical (X, Y, Z) position which may not exist (e.g. see BlockModel) or has been moved (e.g. actual positions have changed).

Parameters:

Name Type Description Default
coords Union[List[int], List[List[int]], ndarray]

Grid coordinates as (n_dim,) or (N, n_dim)

 required

Returns:

Type Description
ndarray

The (X, Y, Z) coordinates as an array of shape (n_dim,) if coords is a single coordinates set (n_dim,) or as an array of shape (N, n_dim) if coords is an array of N coordinates sets (N, n_dim).

Raises:

Type Description
ValueError
  • Grid coords doesn't have the expected dimension.
  • Grid coords are out of bounds.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.coords2xyz([[1, 0, 0], [3, 0, 1]])
Output
array([[1.5, 0.5, 0.5],
       [3.5, 0.5, 1.5]])

copy(name, attributes=None) 🍋

Copy the object.

Parameters:

Name Type Description Default
name str

name of the new object.

 required
attributes Optional[Union[List[str], str]]

list of attributes to copy.

 None

Returns:

Type Description

GeoRefObject

Raises:

Type Description
ValueError

Given attributes (properties and regions) do not exist.

data(names, region=None, support=None) 🍋

Return the attribute data corresponding to the given name(s) for the given support type and optionally in the given region. If no region is specified, it will return the whole data. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
names Union[List[str], str]

single or list of names to get data from.

 required
region str

name of the region or condition to optionally filter the data to be returned.

 None
support AttributeSupportType

type supporting the region (e.g. node = vertex, element = triangles).

 None

Returns:

Type Description
ndarray

Underlying data array associated to the given attribute names.

Raises:

Type Description
ValueError
  • Attribute does not exist.
  • Support type is not valid.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum)
xyz_region = xyz_sum < 10
obj.set_region("Lower10", xyz_region)
point_cloud.data("XYZ", "Lower10")
Output
array([3])

delete_cells(region) 🍋

Delete cells in region.

Parameters:

Name Type Description Default
region str

Region or condition to select cells.

 required

describe(properties=None, **kwargs) 🍋

Generate descriptive statistics. For kwargs, see Pandas - Describe.

Parameters:

Name Type Description Default
properties Optional[Union[List[str], str]]

List of names to get data summary from.

 None

Returns:

Type Description
DataFrame

pd.DataFrame

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.describe()
Output
               X          Y          Z
count  10.000000  10.000000  10.000000
mean   13.500000  14.500000  15.500000
std     9.082951   9.082951   9.082951
min     0.000000   1.000000   2.000000
25%     6.750000   7.750000   8.750000
50%    13.500000  14.500000  15.500000
75%    20.250000  21.250000  22.250000
max    27.000000  28.000000  29.000000

downscale(name, discr) 🍋

Downscale the BlockModel by a given discretisation.

Parameters:

Name Type Description Default
name str

name of the newly created BlockModel.

 required
discr Vector

Discretisation of the new BlockModel.

 required

Returns:

Type Description
BlockModel

BlockModel object downscaled.

Raises:

Type Description
ValueError
  • discr must be of dimension 3.
  • discr must be composed of integers.

element_count(region=None) 🍋

Return the actual number of cells defined in the grid. This number may be different from n_cells depending on the grid type. Same as sample_count().

Parameters:

Name Type Description Default
region Optional[str]

name of the region to optionally filter the data to be counted.

 None

Returns:

Type Description
int

Number of cells defined.

Example

import geolime as geo
vx = geo.Voxel("GridObj", [4, 3], axis=[[1., 0., 0.], [0., 1., 0.]])
vx.element_count()
Output
12

import geolime as geo
import numpy as np
vx = geo.Voxel("GridObj", [4, 3], axis=[[1., 0., 0.], [0., 1., 0.]])

vx.set_property(
    name="PROP",
    data=np.array([1.2, 5.1, 6., 1.4, 1.6, 2.9, 4.1, 8.2, 6.1, 8.7, 3.9, 9.1]),
)
vx.set_region(
    name="REG",
    data="PROP < 5.5",
)
vx.element_count(region="REG")
Output
7

generate_attribute_name(prefix='_', support=None) 🍋

Return a random unused name for a property or a region with the given prefix.

Parameters:

Name Type Description Default
prefix str

Prefix to start the attribute name with.

 '_'
support Optional[AttributeSupportType]

Type supporting the attributes (e.g. node = vertex, element = triangles).

 None

Returns:

Type Description
str

The attribute name string.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.generate_attribute_name(prefix="new_prop")
Output
'new_prop1b750b'

idx2coords(idx) 🍋

Get the grid coordinates of the cell corresponding to the given global grid index. See coords2idx() for inverse function.

Parameters:

Name Type Description Default
idx Union[int, List[int], ndarray]

global index or list of indices - index must be in range [0, n_cells[

 required

Returns:

Type Description
ndarray

The grid coordinates as an array of shape (n_dim,) if idx is an integer or as an array of shape (N, n_dim) if idx is an array of size N.

Raises:

Type Description
ValueError

idx is out of bounds.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.idx2coords(3)
Output
array([3, 0, 0])

indexed_coords(region=None) 🍋

Return the object geometry along with its indexed coordinates.

Parameters:

Name Type Description Default
region str

Region or condition to filter the data.

 None

Returns:

Type Description
ndarray

Object geometry and indices, respectively X, Y, Z, coords data arrays.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.indexed_coords()
Output
array([[0.5, 0.5, 0.5, 0. , 0. , 0. ],
    [1.5, 0.5, 0.5, 1. , 0. , 0. ],
    [2.5, 0.5, 0.5, 2. , 0. , 0. ],
    [3.5, 0.5, 0.5, 3. , 0. , 0. ],
    [0.5, 1.5, 0.5, 0. , 1. , 0. ],
    [1.5, 1.5, 0.5, 1. , 1. , 0. ],
    [2.5, 1.5, 0.5, 2. , 1. , 0. ],
    [3.5, 1.5, 0.5, 3. , 1. , 0. ],
    [0.5, 2.5, 0.5, 0. , 2. , 0. ],
    [1.5, 2.5, 0.5, 1. , 2. , 0. ],
    [2.5, 2.5, 0.5, 2. , 2. , 0. ],
    [3.5, 2.5, 0.5, 3. , 2. , 0. ],
    [0.5, 0.5, 1.5, 0. , 0. , 1. ],
    [1.5, 0.5, 1.5, 1. , 0. , 1. ],
    [2.5, 0.5, 1.5, 2. , 0. , 1. ],
    [3.5, 0.5, 1.5, 3. , 0. , 1. ],
    [0.5, 1.5, 1.5, 0. , 1. , 1. ],
    [1.5, 1.5, 1.5, 1. , 1. , 1. ],
    [2.5, 1.5, 1.5, 2. , 1. , 1. ],
    [3.5, 1.5, 1.5, 3. , 1. , 1. ],
    [0.5, 2.5, 1.5, 0. , 2. , 1. ],
    [1.5, 2.5, 1.5, 1. , 2. , 1. ],
    [2.5, 2.5, 1.5, 2. , 2. , 1. ],
    [3.5, 2.5, 1.5, 3. , 2. , 1. ]])

internals(support=None) 🍋

Return list of all existing internal properties for the specified support. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
support Optional[AttributeSupportType]

type supporting the property (e.g. node = vertex, element = triangles).

 None

Returns:

Type Description
List

List containing all object internal property names.

keep_only_cells(region) 🍋

Keep cells in region.

Parameters:

Name Type Description Default
region str

Region or condition to select cells.

 required

plot_2d(property=None, agg_method=None, region=None, region_agg=None, interactive_map=False, interactive_max_sample=5000, **kwargs) 🍋

Display the data on a regular plot or an interactive map.

Note

  • interactive map requires folium and mapclassify packages to be installed.
  • a CRS must be defined for the data to be properly plotted. If the data doesn't have a CRS, the Project CRS will be used by default. See Project.
  • interactive map works within a Jupyter Notebook context, please see folium for more information.

Parameters:

Name Type Description Default
property Optional[str]

object attribute to aggregate and display.

 None
agg_method Optional[AggregationMethod]

aggregation data method. See Pandas - Group By to find out supported methods.

 None
region Optional[str]

Object region or condition to select data from.

 None
region_agg Optional[RegionAggregationMethod]

Aggregation region method.

 None
interactive_map bool

if True, folium interactive map is used.

 False
interactive_max_sample int

maximum number of samples to display in interactive mode. Above 10 000 samples, loading time and interactivity will be impacted.

 5000
**kwargs

extra arguments to pass along to GeoPandas - Plot or GeoPandas - Explore.

 {}

Returns:

Type Description
Union[Axes, Map]

A folium Map in interactive mode, or an instance of Matplotlib Axes otherwise.

Raises:

Type Description
ValueError

Packages are missing for interactive mode.

properties(support=None) 🍋

Return list of all existing properties for the specified support. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
support AttributeSupportType

type supporting the property (e.g. node = vertex, element = triangles).

 None

Returns:

Type Description
List[str]

List containing all object property names.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum)
point_cloud.properties()
Output
['X', 'Y', 'Z', 'XYZ']

property(name, support=None, return_none=False) 🍋

Return the object property for the given name for the given support type. The support databased are disjoints, so it is possible to have properties carried by the nodes but not by the elements and vice-versa. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
name str

name to get property from.

 required
support AttributeSupportType

type supporting the property (e.g. node = vertex, element = triangles).

 None
return_none bool

if True, returns None instead of raising an error.

 False

Returns:

Type Description
ObjectProperty

Object property associated to the given name.

Raises:

Type Description
ValueError
  • Property does not exist.
  • Attribute is not a property.
  • Support type is not valid.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum)
point_cloud.property("XYZ")
Output
ObjectProperty
└─data()
└─dynamic ⇨ False
└─expr ⇨ None
└─kind ⇨ None
└─name ⇨ XYZ
└─read_only ⇨ False
└─unit ⇨ None

read_file(filepath, attributes=None) classmethod 🍋

Read the object from its folder path. If it does not end with .geo, the suffix will automatically be appended. See global read_file() provided for convenience.

Parameters:

Name Type Description Default
filepath str

path to the object folder path.

 required
attributes Optional[List[str]]

list of attributes to read from the object.

 None

Returns:

Type Description
Union[GeoRefObject, GISObject]

The newly created object read from the file.

Raises:

Type Description
ValueError
  • if the path is invalid.
  • if the format version is not found in the manifest.
  • if the object type in the manifest does not match this object reader.
  • if there is any data file read error.

read_manifest(filepath) staticmethod 🍋

Read the manifest first from the given object folder path (ending with .geo).

Parameters:

Name Type Description Default
filepath str

path to the object folder path.

 required

Raises:

Type Description
ValueError

Path is invalid.

Returns:

Type Description

The contents of the manifest file as JSON dictionary.

refresh(names, support=None) 🍋

Recompute the given properties or regions that store an expression or a condition. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
names Union[List[str], str]

list of names or single name of the properties or regions to refresh.

 required
support AttributeSupportType

type supporting the property or region (e.g. node = vertex, element = triangles).

 None

Raises:

Type Description
ValueError
  • Property or region does not exist.
  • Support type is not valid.

region(name, support=None, return_none=False) 🍋

Return the object region for the given name for the given support type. The support databased are disjoints, so it is possible to have regions carried by the nodes but not by the elements and vice-versa. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
name str

name to get region from.

 required
support AttributeSupportType

type supporting the region (e.g. node = vertex, element = triangles).

 None
return_none bool

if True, returns None instead of raising an error.

 False

Returns:

Type Description
ObjectRegion

Object region associated to the given name.

Raises:

Type Description
ValueError
  • Region does not exist.
  • Attribute is not a region.
  • Support type is not valid.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum)
xyz_region = xyz_sum < 10
point_cloud.set_region("Lower10", xyz_region)
point_cloud.region("Lower10")
Output
ObjectRegion
└─data()
└─dynamic ⇨ False
└─expr ⇨ None
└─name ⇨ Lower10
└─read_only ⇨ False

region_mask(region, support=None) 🍋

Get the boolean mask corresponding to the given region.

Parameters:

Name Type Description Default
region str

region or condition to filter data.

 required
support Optional[AttributeSupportType]

type supporting the property (e.g. node = vertex, element = triangles).

 None

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum)
xyz_region = xyz_sum < 10
point_cloud.set_region("Lower10", xyz_region)
point_cloud.region_mask("Lower10")
Output
array([ True, False, False, False, False, False, False, False, False, False])

regions(support=None) 🍋

Return a list of regions for a given GeoRefObject.

Parameters:

Name Type Description Default
support Optional[AttributeSupportType]

support on which the regions are defined. Default value is None.

 None

Returns:

Type Description
List[str]

List containing all user region names.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum)
xyz_region = xyz_sum < 10
point_cloud.set_region("Lower10", xyz_region)
point_cloud.regions()
Output
['Lower10']

remove_property(names, support=None) 🍋

Remove the object property associated to the given name. Use a list of property names to remove all of them at once.

Parameters:

Name Type Description Default
names Union[str, List[str]]

name of the property or a list of names of propertie(s) to remove.

 required
support Optional[AttributeSupportType]

type supporting the attributes (e.g. node = vertex, element = triangles).

 None

Raises:

Type Description
ValueError
  • Support type is not valid.
  • Property does not exist.
  • Attribute is not a property.
  • Property is built-in or internal.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)

xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum)

xyz_sum_off1 = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ_off1", xyz_sum_off1)

# Remove only one property
point_cloud.remove_property("XYZ")
# Or remove multiple properties
point_cloud.remove_property(["XYZ", "XYZ_off1"])
Output
True

remove_region(names, support=None) 🍋

Remove the object region associated to the given name. Use a list of region names to remove all of them at once.

Parameters:

Name Type Description Default
names Union[str, List[str]]

name of the region or a list of names of region(s) to remove.

 required
support Optional[AttributeSupportType]

type supporting the attributes (e.g. node = vertex, element = triangles).

 None

Raises:

Type Description
ValueError
  • Region does not exist.
  • Attribute is not a region.
  • Support type is not valid.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum)

xyz_region_inf10 = xyz_sum < 10
point_cloud.set_region("Lower10", xyz_region_inf10)

xyz_region_sup10 = xyz_sum > 10
point_cloud.set_region("Upper10", xyz_region_sup10)

# Remove only one region
point_cloud.remove_property("Lower10")
# Or remove multiple regions
point_cloud.remove_property(["Lower10", "Upper10"])
Output
True

rename_property(names, support=None) 🍋

Rename the object property.

Parameters:

Name Type Description Default
names Dict[str, str]

a dictionary where each item is a pair of current name and new name.

 required
support Optional[AttributeSupportType]

type supporting the attributes (e.g. node = vertex, element = triangles).

 None

Raises:

Type Description
ValueError
  • Support type is not valid.
  • Attribute is built-in or internal or doesn't exist.
  • Attribute new name already exists.
  • Attribute new name is invalid (e.g. whitespace in name, special character, starting with a number, read-only, etc.).
KeyError

Any of the current names is not found in the database.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
pc = geo.PointCloud("test", xyz)

data = np.arange(0., 10., 1.)
pc.set_property("PROP_1", data)
pc.set_property("PROP_2", "PROP_1 + 1.")
pc.set_property("PROP_3", "PROP_1 + 10.")

pc.rename_property(names={"PROP_1": "PROP_1_renamed})
pc.rename_property(names={"PROP_2": "PROP_2_renamed", "PROP_3": "PROP_3_renamed"})

rename_region(names, support=None) 🍋

Rename the object region.

Parameters:

Name Type Description Default
names Dict[str, str]

a dictionary where each item is a pair of current name and new name.

 required
support Optional[AttributeSupportType]

type supporting the attributes (e.g. node = vertex, element = triangles).

 None

Raises:

Type Description
ValueError
  • Support type is not valid.
  • Attribute is built-in or internal or doesn't exist.
  • Attribute new name already exists.
  • Attribute new name is invalid (e.g. whitespace in name, special character, starting with a number, read-only, etc.).
KeyError

Any of the current names is not found in the database.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
pc = geo.PointCloud("MyPointCloud", xyz)

xyz_sum = np.sum(xyz, axis=1)
pc.set_property("XYZ", xyz_sum)

xyz_region = xyz_sum < 2
pc.set_region("Lower2", xyz_region)

xyz_region = xyz_sum > 3
pc.set_region("Upper3", xyz_region)

xyz_region = xyz_sum < 10
pc.set_region("Lower10", xyz_region)

pc.rename_region(names={"Lower2": "Lower2_renamed"})
pc.rename_region(names={"Upper3": "Upper3_renamed", "Lower10": "Lower10_renamed"})

sample_count(region=None) 🍋

Return the actual number of cells defined in the grid. This number may be different from n_cells depending on the grid type. Same as element_count().

Parameters:

Name Type Description Default
region Optional[str]

name of the region to optionally filter the data to be counted.

 None

Returns:

Type Description
int

Number of cells defined.

Example

import geolime as geo
vx = geo.Voxel("GridObj", [4, 3], axis=[[1., 0., 0.], [0., 1., 0.]])
vx.sample_count()
Output
12

import geolime as geo
import numpy as np
vx = geo.Voxel("GridObj", [4, 3], axis=[[1., 0., 0.], [0., 1., 0.]])

vx.set_property(
    name="PROP",
    data=np.array([1.2, 5.1, 6., 1.4, 1.6, 2.9, 4.1, 8.2, 6.1, 8.7, 3.9, 9.1]),
)
vx.set_region(
    name="REG",
    data="PROP < 5.5",
)
vx.sample_count(region="REG")
Output
7

set_property(name, data, kind=None, unit=None, read_only=False, support=None, region=None, default=None, dynamic=False) 🍋

Add the property corresponding to the given name and a numerical value, a sequence of values or an expression for the given support type. If no support is specified, the default database will be used. To recreate an existing property, remove it first.

Parameters:

Name Type Description Default
name str

name of the property to create.

 required
data Union[Data, str, int, float]

property data array or expression use to compute the property values. Use backquotes when attribute names contains whitespace.

 required
kind Optional[PropertyKind]

property kind, see PropertyKind for available kinds.

 None
unit Optional[Unit]

property unit, see Pint Unit for more information.

 None
read_only bool

whether attribute data is protected.

 False
support Optional[AttributeSupportType]

type supporting the property (e.g. node = vertex, element = triangles).

 None
region Optional[str]

region or condition in which to set the property data. Properties that hold a sequence of values must be created first, and then updated with the specified region.

 None
default Optional[str]

default value used outside of the region. This must be used in combination with a region parameter. This parameter is only intended to be used for properties that store an expresion, a string or a numerical value.

 None
dynamic bool

set to True to have property values recomputed each time the data is requested. Dynamic properties need to be create with an expression.

 False

Raises:

Type Description
ValueError
  • Property already exists.
  • Attribute exists but is not a property.
  • Support type is not valid.

Example

import geolime as geo
import numpy as np
from pint import Unit

xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
xyz_sum = np.sum(xyz, axis=1)

# Create a new property from a numpy array and define kind and units.
point_cloud.set_property(
    name="XYZ",
    data=xyz_sum,
    kind=geo.PropertyKind.LENGTH,
    unit=Unit("m")
)

# Or using the shortcut method for simplicity.
# Note here, unit and kind are default to None.
point_cloud["XYZ_2"] = xyz_sum

# Create a property with an expression defined for a specific region
# and a default value for the remaining data.
point_cloud.set_property(
    name="PROP",
    data="X * Y * Z",
    kind=geo.PropertyKind.LENGTH,
    unit=Unit("m"),
    region="(Z >= 14) & (Z <= 17)",
    default="Y",
    dynamic=False
)

# Or using the shortcut method for simplicity.
# Like the previous example, unit and kind are default to None
# and it's not possible to define a region.
point_cloud["PROP_2"] = "X * Y * Z"

# Setting the value to a string.
# !! Don't forget backquotes inside the string !!
point_cloud.set_property("domain", "'hg'")

# or
point_cloud["domain"] = "'hg'"

# or with using the shortcut
point_cloud["XYZ_2"] = 2 * xyz_sum

# The same with an expression
point_cloud["PROP_2"] = "X * Y * (Z + 10)"

set_region(name, data, read_only=False, support=None, region=None, dynamic=False) 🍋

Add the region data corresponding to the given name(s) and data or condition for the given support type. If no support is specified, the default database will be used. To recreate an existing region, remove it first.

Parameters:

Name Type Description Default
name str

name of the property to create.

 required
data Union[Data, str]

data array or condition use to compute the region values. Use backquotes when attribute names contains whitespace.

 required
read_only bool

set to True if region data is protected.

 False
support Optional[AttributeSupportType]

type supporting the region (e.g. node = vertex, element = triangles).

 None
region Optional[str]

region or condition in which to set the region data. Regions that store a sequence of values must first be created and then updated with the given region.

 None
dynamic bool

set to True to have region values recomputed each time the data is requested. Dynamic regions need to be create with an expression or a numerical value (no sequence of values).

 False

Raises:

Type Description
ValueError
  • Region already exists.
  • Attribute exists but is not a region.
  • Support type is not valid.
  • Region in which to set the data.

Example

import geolime as geo
import numpy as np
from pint import Unit
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)

# Create regions from a numpy array.
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_property("XYZ", xyz_sum, geo.PropertyKind.LENGTH, Unit("m"))

xyz_region = xyz_sum < 10
point_cloud.set_region('RegionTest', xyz_region)

# Create a region from a condition.
point_cloud.set_region('RegionTest2', 'X + Y + Z < 10', False)

to_csv(filename, names=None, region=None, skip_nan=False, sort_by=None, sort_ascending=True, mapping=None, support=None, **kwargs) 🍋

Export the given attribute(s) to a CSV-file. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
filename str

path to export the file to.

 required
names Union[List[str], str]

list of names or single name of the attribute(s) to export. If not specified, all attributes are exported.

 None
region str

region name or condition to filter data to export.

 None
skip_nan bool

True will drop NaN values from the exported file. Otherwise, NaN values will be exported as NumericalConstants.NDV (-99999). To overwrite the NaN values, use na_rep argument of pandas.to_csv().

 False
sort_by Union[str, List[str]]

sort the data by the given attributes.

 None
sort_ascending Union[bool, List[bool]]

sorting order when sort_by is provided.

 True
mapping Dict

rename given columns in the exported CSV.

 None
support AttributeSupportType

type supporting the attributes (e.g. node = vertex, element = triangles).

 None
**kwargs

extra arguments to pass along to Pandas - To CSV.

 {}

Raises:

Type Description
ValueError
  • Support type is not valid.
  • Attribute does not exist.

to_dataframe(names=None, region=None, support=None) 🍋

Export the given attribute(s) to a Pandas DataFrame. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
names Union[List[str], str]

list of names or single name of the attribute(s) to export. If not specified, all attributes are exported.

 None
region str

region name or condition to filter data to export.

 None
support AttributeSupportType

type supporting the attributes (e.g. node = vertex, element = triangles).

 None

Raises:

Type Description
ValueError
  • Support type is not valid.
  • Attribute does not exist.

to_file(filepath, attributes=None, version=None) 🍋

Write the object to the given folder path. If it does not end with .geo, the suffix will automatically be appended.

Parameters:

Name Type Description Default
filepath str

path to the object folder path.

 required
attributes Optional[List[str]]

list of attributes to write to the object.

 None
version Optional[str]

specific version format to use. Use None will default to the latest available version.

 None

Raises:

Type Description
ValueError

There is any data file write error.

to_pyvista(properties=None, region=None) 🍋

Export BlockModel and selected properties to Pyvista UnstructuredGrid.

Parameters:

Name Type Description Default
properties Optional[Union[str, List[str]]]

Property or list of properties to export to Pyvista.

 None
region Optional[str]

Object region or condition to select data from.

 None

Returns:

Type Description
UnstructuredGrid

UnstructuredGrid object.

transform(properties=None, agg_methods=None) 🍋

Return the object data grouped by location (X, Y).

Parameters:

Name Type Description Default
properties Optional[Union[List[str], str]]

list of properties name to transfer to the GIS Object. Setting to None or empty list will select all existing properties.

 None
agg_methods Optional[Union[AggregationMethod, Callable]]

aggregation data methods. See Pandas - Group By to find out supported methods. Defaults to first.

 None

Returns:

Type Description
DataFrame

DataFrame of XY coordinates with aggregated data.

Raises:

Type Description
ValueError
  • No aggregation method is provided.
  • 'X' or 'Y' are part of the properties.
  • One of the aggregation methods is not supported.

Example

import geolime as geo
import numpy as np
xyz = np.array(
    [[7, 6, 5],
    [3, 4, 6],
    [4, 7, 1],
    [6, 4, 6],
    [2, 2, 1],
    [3, 7, 8],
    [8, 2, 1],
    [3, 2, 4],
    [3, 2, 6],
    [9, 5, 7]]
)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.transform("Z", "max")
Output
Z_max
0      5
1      6
2      1
3      6
4      1
5      8
6      1
7      6
8      6
9      7

import geolime as geo
import numpy as np
xyz = np.array(
    [[7, 6, 5],
    [3, 4, 6],
    [4, 7, 1],
    [6, 4, 6],
    [2, 2, 1],
    [3, 7, 8],
    [8, 2, 1],
    [3, 2, 4],
    [3, 2, 6],
    [9, 5, 7]]
)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.transform()
Output
Z_first
0        5
1        6
2        1
3        6
4        1
5        8
6        1
7        4
8        4
9        7

translate_by(coord, expr, region=None, ignore_warning=False) 🍋

Shift the given existing X, Y or Z coordinate by the given expression or value.

Parameters:

Name Type Description Default
coord Union[Attribute, Coord]

coordinate property.

 required
expr str

expression use to compute the property values. Use backquotes when attribute names contains whitespace.

 required
region Optional[str]

region or condition in which to set the property data.

 None
ignore_warning bool

Boolean to avoid warning in case of rotated object. For rotated object, origin cannot be recomputated, meaning the origin is not valid anymore after translation.

 False

Raises:

Type Description
ValueError

Coordinate doesn't exist.

update_property(name, data, region=None, support=None) 🍋

update the property corresponding to the given name and a numerical value, a sequence of values or an expression for the given support type. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
name str

name of the property to update.

 required
data Union[Data, str, int, float]

property data array or expression use to compute the property values. Use backquotes when attribute names contains whitespace.

 required
support Optional[AttributeSupportType]

type supporting the property (e.g. node = vertex, element = triangles).

 None
region Optional[str]

region or condition in which to set the property data. Properties that store a sequence of values must first be created and then updated with the given region.

 None

Raises:

Type Description
ValueError
  • Property does not exist.
  • Property is read-only.
  • Attribute exists but is not a property.
  • Support type is not valid.

update_region(name, data, region=None, support=None) 🍋

Update the region data corresponding to the given name(s) and data or condition for the given support type. If no support is specified, the default database will be used.

Parameters:

Name Type Description Default
name str

name of the region to update.

 required
data Union[Data, str]

data array or condition use to compute the region values. Use backquotes when attribute names contains whitespace.

 required
support Optional[AttributeSupportType]

type supporting the region (e.g. node = vertex, element = triangles).

 None
region Optional[str]

region or condition in which to set the region data. Regions that store a sequence of values must first be created and then updated with the given region.

 None

Raises:

Type Description
ValueError
  • Region does not exist.
  • Region is read-only.
  • Attribute exists but is not a property.
  • Support type is not valid.

user_properties(support=None) 🍋

Return a list of properties for a given GeoRefObject including all the objects properties excluding built-in ones.

Parameters:

Name Type Description Default
support Optional[AttributeSupportType]

support on which the properties are defined. Default value is None.

 None

Returns:

Type Description
List[str]

List containing all user property names.