Skip to content

Base Objects🍋

ObjectMixin 🍋

Mixin providing common functions and properties to Object-like Entity. It handles Property and Region data getters/setters as well as the object databases. By default the database points to the geometry (support=Node).

Attributes:

Name Type Description
name str

object name.

Raises:

Type Description
ValueError

Object name is not provided.

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'>

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'

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

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'

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.

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

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.

Parameters:

Name Type Description Default
name str

name of the attribute to remove.

 required
support Optional[AttributeSupportType]

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

 None

Returns:

Type Description
bool

True if successful and False if the attribute does not exist on the object.

Raises:

Type Description
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 = xyz_sum < 10
point_cloud.set_region("Lower10", xyz_region)
point_cloud.remove_attribute("Lower10")
Output
True

remove_property(name, support=None) 🍋

Remove the object property associated to the given name. If an attribute exists but is not a property, nothing is done.

Parameters:

Name Type Description Default
name str

name of the property to remove.

 required
support Optional[AttributeSupportType]

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

 None

Returns:

Type Description
bool

True if successful and False if the property does not exist on the object.

Raises:

Type Description
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 = xyz_sum < 10
point_cloud.set_region("Lower10", xyz_region)
point_cloud.remove_property("XYZ")
Output
True

remove_region(name, support=None) 🍋

Remove the object region associated to the given name. If an attribute exists but is not a region, nothing is done.

Parameters:

Name Type Description Default
name str

name of the region to remove.

 required
support Optional[AttributeSupportType]

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

 None

Returns:

Type Description
bool

True if successful and False if the region does not exist on the object.

Raises:

Type Description
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 = xyz_sum < 10
point_cloud.set_region("Lower10", xyz_region)
point_cloud.remove_region("Lower10")
Output
True

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)
point_cloud.set_property("XYZ", xyz_sum, geo.PropertyKind.LENGTH, Unit("m"))

set_property_expr(name, expr, dynamic=False, kind=None, unit=None, read_only=False, support=None, region=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 str

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

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
import numpy as np
xyz = np.arange(30).reshape(10, 3)
point_cloud = geo.PointCloud("MyPointCloud", xyz)
point_cloud.set_property_expr('XYZ', 'X * Y * Z', False)

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.

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.

GeoRefObject 🍋

Bases: Entity, ObjectMixin, ObjectIO

Elementary geographically referenced object, i-e defined at least by its geometry coordinates: X, Y, Z.

Parameters:

Name Type Description Default
name str

object name.

 required
xyz Optional[Data]

geometry data, respectively X, Y and Z.

 None
read_only Union[bool, List[bool]]

whether XYZ coordinates are read-only. Use a single boolean for all, or a list a 3 booleans, respectively for each axis.

 True
topological_types Optional[Union[TopologicalElementType, List[TopologicalElementType], ndarray]]

type of the topological elements. See TopologicalElementType for more information. Provide a single value if all elements are of the same type (e.g. triangulated surface made of only triangles) or provide the type of each element if the types are mixed (e.g. unstructured mesh).

 None
topological_elements Optional[Data]

array of topological elements of shape (N, level) where level is the maximum number of connected nodes per element (e.g., 3 for triangles, 4 for quads, 6 for hexahedron, etc.). Leave to None if elements are isolated/not connected (e.g. points, block model, voxel, etc.). For mixed types, undefined elements should be set to TopologicalElementType.NDV. An example of triangles + quads could be: 

    topological_types = [
        TopologicalElementType.TRIANGLE,
        TopologicalElementType.TRIANGLE,
        TopologicalElementType.QUAD
    ]

    topological_elements = [
        [0, 1, 2, TopologicalElementType.NDV],
        [1, 2, 3, TopologicalElementType.NDV],
        [0, 2, 4, 5]
    ]

None

Raises:

Type Description
ValueError
  • Object name is not provided.
  • Topological elements is not of shape (N, max_nodes).
  • Topology is inconsistent.
    • Topological type is defined but no element is provided.
    • Topological elements are provided but no type is defined.
    • In case of mixed type, when size of type doesn't match the number of elements.
    • Number of topological elements is not consistent with the declared type.
    • Topological type doesn't exist.

Attributes:

Name Type Description
name

object name.
builtins

built-ins object property names.
default_support

the default database used when setting/getting attributes.

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

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 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' or 'Y' are part of the properties.
AttributeError

One of the aggregation methods is not supported.

Example

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

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])

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]])

element_count() abstractmethod 🍋

Return the number of elements for this object. This method is abstract and must be re-implemented by child classes.

Returns:

Type Description
int

Number of elements.

Example

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

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.

sample_count() abstractmethod 🍋

Return the number of samples for this object. This method is abstract and must be re-implemented by child classes.

Returns:

Type Description
int

Number of samples.

Example

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

to_pyvista(properties=None) 🍋

Export GeoRefObject and selected properties to Pyvista PointSet.

Parameters:

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

Property or list of properties to export to Pyvista.

 None

Returns:

Type Description
PointSet

PointSet object.

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

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

Coord doesn't exist.

GISObject 🍋

Bases: Entity, ObjectMixin, ObjectIO

GIS representation of 3D object in 2D.

Parameters:

Name Type Description Default
name str

object name.

 required
geometry Optional[GeoData]

2D geometrical data, either a geopandas.GeoDataSeries of geometry or a XY array.

 None

Raises:

Type Description
ValueError

Object name is not provided.

Attributes:

Name Type Description
name

object name.
builtins

built-ins object property names.
default_support

the default database used when setting/getting attributes.

crs: CRS property 🍋

Return CRS.

Returns:

Name Type Description
CRS CRS

Coordinate Reference System.

bounds(region=None) 🍋

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

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

XY bounding coordinates.

Example

import geolime as geo
import numpy as np
xy = np.arange(20).reshape(10, 2)
gis_obj = geo.GISObject("GISObj", xy)
gis_obj.bounds()
Output
array([[ 0.,  1.],
       [18., 19.]])

centroid(region=None) 🍋

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

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

XY centroid coordinates.

Example

import geolime as geo
import numpy as np
xy = np.arange(20).reshape(10, 2)
gis_obj = geo.GISObject("GISObj", xy)
gis_obj.centroid()
Output
array([ 9., 10.])

concave_hull(alpha=0.0, region=None) 🍋

Compute bounding concave polygon of a set of points. Degree of concavity is determined with alpha parameter. Return convex hull by default.

Parameters:

Name Type Description Default
alpha float

Parameter of concavity degree: - alpha = 0. means convex hull - alpha = 2. means concave hull

 0.0
region Optional[str]

region or condition in which to perform concave hull.

 None

Returns:

Type Description
Polygon

Hull of data.

convex_hull() 🍋

Compute Convex Hull of geometry.

Returns:

Type Description
Polygon

Convex Hull.

delete_geometries(region) 🍋

Remove geometries from a given region.

Parameters:

Name Type Description Default
region str

Region or condition to remove.

 required

element_count() 🍋

Return the number of geometrical elements for this object.

Returns:

Type Description
int

Number of elements.

Example

import geolime as geo
import numpy as np
xy = np.arange(20).reshape(10, 2)
gis_obj = geo.GISObject("GISObj", xy)
gis_obj.element_count()
Output
10

keep_only_geometries(region) 🍋

Keep geometries from a given region.

Parameters:

Name Type Description Default
region str

Region or condition to keep.

 required

overlay(other_gis, name=None, **kwargs) 🍋

Perform spatial overlay between two GISOBject.

Allowed kwargs are GeoPandas overlay function arguments. See GeoPandas - Overlay.

Parameters:

Name Type Description Default
other_gis GISObject

GISOBject.

 required
name Optional[str]

Name of new GISObject. If not specified, the name used will be the names of the original object intertwined by _overlay_ string.

 None

Returns:

Type Description
GISObject

New GISObject.

plot(interactive_map=False, interactive_max_sample=5000, **kwargs) 🍋

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

Notes

  • 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
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 GeoDataFrame.plot() or GeoDataFrame.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.

set_crs(crs) 🍋

Set the Coordinate Reference System (CRS) of the GISObject.

Parameters:

Name Type Description Default
crs CRS

PyProj CRS.

 required

Raises:

Type Description
ValueError

crs already exists.

to_geojson(filename) 🍋

Export the geometry to a geojson file.

Parameters:

Name Type Description Default
filename str

path to export the file to.

 required

to_shp(filename) 🍋

Export the geometry to a shpfile.

Parameters:

Name Type Description Default
filename str

path to export the file to.

 required

ObjectIO🍋

read_file(filepath, attributes=None) 🍋

Read the object from its 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 read from the object.

 None

Raises:

Type Description
ValueError
  • Path is invalid.
  • Format version is not found in the manifest.
  • Object type in the manifest does not exist.
  • There is any data file read error.

Returns:

Type Description

The newly created object read from the file.

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.
Last update: 2023-10-09