Voxels

Voxel

Bases: GridObject

A Voxel is grid of regular cells, i-e: - all cells have the same size and geometry - cells are contiguous

Parameters:

Name	Type	Description	Default
name	str	object name.	required
shape	Optional[IntArray]	number of cells respectively along U, V, W axes.	None
origin	Vector	3D point where voxel starts from.	[0.0, 0.0, 0.0]
axis	Union[List[Vector], ndarray]	direction and size along the axis. Axis are ordered by row, i-e axis = [ u, # vector u, e.g. [1, 0, 0] v, # vector v, e.g. [0, 1, 0] w # vector w, e.g. [0, 0, 1] ] See example below.	[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]
extra_coord_labels	List[str]	labels corresponding to extra coordinates beyond the grid axes. For example, 4D cube would have an extra-dimension T beyond (U, V, W): vx = Voxel( "test", [4, 3, 2, 2], axis=[[1, 0, 0], [0, 1, 0], [0, 0, 1], [0, 0, 0]], extra_coord_labels=["T"] )	[]

Raises:

Type	Description
ValueError	Object name is not provided. Number of dimensions is not equal to number of axis. Dimension along any axis is negative. Origin or any cell vector doesn't have 3 components X, Y, Z.

Info

Note that the grid may not be cartesian. By default, Voxel is 3D however it does support multiple dimensions (2D, 3D, 4D, etc.).

Example

import geolime as geo

u = [2, 0, 0]
v = [0, 2, 0]
w = [0, 0, 5]

vx = geo.Voxel("MyGridObj", [4, 3, 2], axis=[u, v, w])

builtins: List[str] 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: AttributeSupportType 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: int 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: int 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: str 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: Vector 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: np.ndarray 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])

aggregate(properties=None, agg_methods=[AggregationMethod.SUM, AggregationMethod.MIN, AggregationMethod.MAX, AggregationMethod.MEAN])

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

Parameters:

Name	Type	Description	Default
properties	List[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	List[Union[AggregationMethod, Callable]]	aggregation data methods. See Pandas - Group By to find out supported methods.	[SUM, MIN, MAX, MEAN]

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_sum  Z_min  Z_max  Z_mean  W_sum  W_min  W_max  W_mean
0   0.5  0.5  0  0    2.0    0.5    1.5     1.0      1      0      1     0.5
1   0.5  1.5  0  1    2.0    0.5    1.5     1.0      1      0      1     0.5
2   0.5  2.5  0  2    2.0    0.5    1.5     1.0      1      0      1     0.5
3   1.5  0.5  1  0    2.0    0.5    1.5     1.0      1      0      1     0.5
4   1.5  1.5  1  1    2.0    0.5    1.5     1.0      1      0      1     0.5
5   1.5  2.5  1  2    2.0    0.5    1.5     1.0      1      0      1     0.5
6   2.5  0.5  2  0    2.0    0.5    1.5     1.0      1      0      1     0.5
7   2.5  1.5  2  1    2.0    0.5    1.5     1.0      1      0      1     0.5
8   2.5  2.5  2  2    2.0    0.5    1.5     1.0      1      0      1     0.5
9   3.5  0.5  3  0    2.0    0.5    1.5     1.0      1      0      1     0.5
10  3.5  1.5  3  1    2.0    0.5    1.5     1.0      1      0      1     0.5
11  3.5  2.5  3  2    2.0    0.5    1.5     1.0      1      0      1     0.5

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

Example 1Example 2

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=[AggregationMethod.SUM, AggregationMethod.MIN, AggregationMethod.MAX, AggregationMethod.MEAN], 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[List[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	List[Union[AggregationMethod, Callable]]	aggregation data methods. See Pandas - Group By to find out supported methods.	[SUM, MIN, MAX, MEAN]
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
ndarray	coordinates set (n_dim,) or as an array of shape (N, n_dim) if coords is an array
ndarray	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])

describe(properties=None, **kwargs)

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

Parameters:

Name	Type	Description	Default
properties	Optional[List[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 Voxel by a given discretisation.

Parameters:

Name	Type	Description	Default
name	str	name of the newly created Voxel.	required
discr	Vector	Discretisation of the new Voxel.	required

Returns:

Type	Description
Voxel	Voxel object downscaled.

Raises:

Type	Description
ValueError	discr must have the shape of the voxel dimension. 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

Count all the elements in the GridObjectCount all the elements within a given region

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_condition(
    name="REG",
    condition="PROP < 5.5",
)
vx.element_count(region="REG")

Output

7

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

Return a random unused name 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.

plot_2d(property, agg_method, 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	str	object attribute to aggregate and display.	required
agg_method	AggregationMethod	aggregation data method. See Pandas - Group By to find out supported methods.	required
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.

Raise

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

Raise

ValueError: Path is invalid.

Returns:

Type	Description
	The contents of the manifest file as JSON dictionary.

refresh_attributes(names, support=None)

Recompute the given attribute(s) for the given support type. 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 refresh.	required
support	AttributeSupportType	type supporting the region (e.g. node = vertex, element = triangles).	None

Raises:

Type	Description
ValueError	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_attribute(name, support=None)

Remove the object attribute (property or region) associated to the given name. Use a list of attribute names to remove all of them at once.

Parameters:

Name	Type	Description	Default
name	Union[str, List[str]]	name of the attribute to remove or a list of names of the attribute(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.
ValueError	Property is built-in or internal or doesn't exist.

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 attribute
point_cloud.remove_attribute("Lower10")
# Or remove multiple attributes
point_cloud.remove_attribute(["Lower10", "Upper10"])

Output

True

remove_property(name, 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
name	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.
ValueError	Property does not exist. Attribute is not a property.
ValueError	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_attribute(["XYZ", "XYZ_off1"])

Output

True

remove_region(name, 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
name	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.
ValueError	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_attribute("Lower10")
# Or remove multiple regions
point_cloud.remove_attribute(["Lower10", "Upper10"])

Output

True

rename_attribute(names, support=None)

Rename the object attribute (property or 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("test", xyz)

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

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

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_expr("PROP_2", "PROP_1 + 1.")
pc.set_property_expr("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

Count all the elements in the GridObjectCount all the elements within a given region

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_condition(
    name="REG",
    condition="PROP < 5.5",
)
vx.sample_count(region="REG")

Output

7

set_property(name, data, kind=None, unit=None, read_only=False, support=None)

Add or update the property corresponding to the given name(s) for the given support type. See also set_property_value() if you only need to update the data value of an existing property. If no support is specified, the default database will be used.

Parameters:

Name	Type	Description	Default
name	str	name of the property to create or update.	required
data	Data	property data array.	required
kind	PropertyKind	property kind, see PropertyKind for available kinds.	None
unit	Unit	property unit, see Pint Unit for more information.	None
read_only	bool	whether attribute data is protected.	False
support	AttributeSupportType	type supporting the property (e.g. node = vertex, element = triangles).	None

Raises:

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

Example

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

# Setting a property using the method allowing to also define kind and units.
point_cloud.set_property("XYZ", xyz_sum, geo.PropertyKind.LENGTH, Unit("m"))

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

# Setting the value to a string.
point_cloud.set_property("domain", "'hg'")
# or
point_cloud["domain"] = "'hg'"

set_property_expr(name, expr, dynamic=False, kind=None, unit=None, read_only=False, support=None, region=None, default=None)

Add or update the property corresponding to the given name(s) and expression for the given support type. If no support is specified, the default database will be used.

Parameters:

Name	Type	Description	Default
name	str	property name.	required
expr	Union[str, int, float]	expression use to compute the property values. Use backquotes when attribute names contains whitespace.	required
dynamic	bool	set to True to have property values recomputed each time the data is requested.	False
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	set to True if 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.	None
default	Optional[str]	default value used outside of the region. This must be used in combination with a region parameter.	None

Raises:

Type	Description
ValueError	Expression is invalid (e.g. starts with "=" character). Support type is not valid. Property doesn't exist and region is specified

Example

import geolime as geo

# Or using the shortcut method for simplicity. Note that unit and kind
# default to None.
point_cloud["XYZ"] = "X * Y * Z"

# 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",
    expr="X * Y * Z",
    dynamic=False,
    region="(Z >= 14) & (Z <= 17)",
    default="Y"
)

# Setting the value to a string.
point_cloud.set_property_expr("domain", "'hg'")
# or
point_cloud["domain"] = "'hg'"

set_property_value(name, data, support=None, region=None)

Update the named property with the given data for the given support type. The property must already exist, otherwise use set_property(). 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	Data	property data array.	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.	None

Raises:

Type	Description
ValueError	Property does not exist. 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)
point_cloud.set_property("XYZ", xyz_sum, geo.PropertyKind.LENGTH, Unit("m"))
point_cloud.set_property_value("XYZ", 2 * point_cloud.data("XYZ"))

set_region(name, data, read_only=False, support=None)

Add or update the region data corresponding to the given name(s) for the given support type. See also set_region_values() if you only need to update the data value of an existing region. If no support is specified, the default database will be used.

Parameters:

Name	Type	Description	Default
name	str	name of the property to create or update.	required
data	Data	region data array.	required
read_only	bool	set to True if region data is protected.	False
support	AttributeSupportType	type supporting the region (e.g. node = vertex, element = triangles).	None

Raises:

Type	Description
ValueError	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)
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)

set_region_condition(name, condition, dynamic=False, read_only=False, support=None, region=None)

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

Parameters:

Name	Type	Description	Default
name	str	region name.	required
condition	str	condition use to compute the region values. Use backquotes when attribute names contains whitespace.	required
dynamic	bool	set to True to have region values recomputed each time the data is requested.	False
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.	None

Raises:

Type	Description
ValueError	Expression is invalid (e.g. starts with "=" character). Support type is not valid. Region doesn't exist and region/condition is specified.

Example

import geolime as geo
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.set_region_condition('RegionTest', 'X + Y + Z < 10', False)

set_region_value(name, data, support=None, region=None)

Update the named region with the given data for the given support type. The region must already exist, otherwise use set_region(). 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	Data	region data array.	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 property data.	None

Raises:

Type	Description
ValueError	Region 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)
point_cloud.set_region_condition('RegionTest', 'X + Y + Z < 10', False)
xyz_sum = np.sum(xyz, axis=1)
point_cloud.set_region_value('RegionTest', xyz_sum < 23)

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 GridObject and selected properties to Pyvista ImageData.

Parameters:

Name	Type	Description	Default
properties	Optional[Union[str, List[str]]]	Property or list of properties to export to Pyvista.	None
region	Optional[str]	Name of the region to filter the data.	None

Returns:

Type	Description
Union[ImageData, UnstructuredGrid]	ImageData object if full Object or UnstructuredGrid if a region is selected.

transform(properties=None, agg_methods=None)

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

Parameters:

Name	Type	Description	Default
properties	Optional[List[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.	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

Example 1Example 2

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

Output

    X   Y  Z_max
0   0   1      2
1   3   4      5
2   6   7      8
3   9  10     11
4  12  13     14
5  15  16     17
6  18  19     20
7  21  22     23
8  24  25     26
9  27  28     29

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

Output

    X   Y  Z_sum  Z_min  Z_max  Z_mean
0   0   1      2      2      2     2.0
1   3   4      5      5      5     5.0
2   6   7      8      8      8     8.0
3   9  10     11     11     11    11.0
4  12  13     14     14     14    14.0
5  15  16     17     17     17    17.0
6  18  19     20     20     20    20.0
7  21  22     23     23     23    23.0
8  24  25     26     26     26    26.0
9  27  28     29     29     29    29.0

translate_by(coord, expr, region=None)

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

Raises:

Type	Description
ValueError	Coordinate doesn't exist.

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.