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), use set_default_support() to change it.

Parameters:

Name Type Description Default
name

object name.

 required

Exceptions:

Type Description
ValueError

if object name is not provided.

builtins: List[str] property readonly 🍋

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

Returns:

Type Description
List[str]

Built-in property names.

default_support: AttributeSupportType property readonly 🍋

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

Returns:

Type Description
AttributeSupportType

The default support type.

name: str property readonly 🍋

Return the object name.

Returns:

Type Description
str

Object name.

data(self, name, 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
name Union[List[str], str]

single or list of name to get data from.

 required
region str

name of the region 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 name.

Exceptions:

Type Description
ValueError
  • if attribute does not exist.
  • if the support type is not valid.

properties(self, support=None) 🍋

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

Returns:

Type Description
List[str]

List containing all object property names.

property(self, 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.

Exceptions:

Type Description
ValueError
  • if property does not exist.
  • if attribute is not a property.
  • if the support type is not valid.

refresh_attributes(self, 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

Exceptions:

Type Description
ValueError

if the support type is not valid.

region(self, 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.

Exceptions:

Type Description
ValueError
  • if region does not exist.
  • if attribute is not a region.
  • if the support type is not valid.

set_default_support(self, support) 🍋

Change the default support type.

Parameters:

Name Type Description Default
support AttributeSupportType

corresponding database to change to.

 required

Exceptions:

Type Description
ValueError
  • if the support type is not defined or valid.
  • if the corresponding database is not defined.

set_property(self, 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 region (e.g. node = vertex, element = triangles).

 None

Exceptions:

Type Description
ValueError
  • if attribute exists but is not a property.
  • if the support type is not valid.

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

 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

set to True if attribute data is protected.

 False
support AttributeSupportType

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

 None

Exceptions:

Type Description
ValueError
  • if expression is invalid (e.g. contains "=" character).
  • if the support type is not valid.

set_property_value(self, name, data, support=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 AttributeSupportType

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

 None

Exceptions:

Type Description
ValueError
  • if property does not exist.
  • if the support type is not valid.

set_region(self, 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

Exceptions:

Type Description
ValueError
  • if attribute exists but is not a region.
  • if the support type is not valid.

set_region_condition(self, name, condition, dynamic, read_only=False, support=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.

 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

Exceptions:

Type Description
ValueError
  • if expression is invalid (e.g. contains "=" character).
  • if the support type is not valid.

set_region_value(self, name, data, support=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 AttributeSupportType

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

 None

Exceptions:

Type Description
ValueError
  • if region does not exist.
  • if the support type is not valid.

GeoRefObject (Entity, ObjectMixin) 🍋

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 ~Data

geometry data, respectively X, Y and Z.

 required
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.

 False
topological_types Union[geolime.base.enums.TopologicalElementType, List[geolime.base.enums.TopologicalElementType], numpy.ndarray]

type of the topologial 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 ~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

Exceptions:

Type Description
ValueError

Object name is not provided.
ValueError

Topological elements is not of shape (N, max_nodes).
ValueError

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(self, properties=None, agg_methods=[<AggregationMethod.SUM: 'sum'>, <AggregationMethod.MIN: 'min'>, <AggregationMethod.MAX: 'max'>, <AggregationMethod.MEAN: 'mean'>]) 🍋

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

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[str]

aggregation data methods. See pandas.DataFrame.groupby to find out supported methods.

 [<AggregationMethod.SUM: 'sum'>, <AggregationMethod.MIN: 'min'>, <AggregationMethod.MAX: 'max'>, <AggregationMethod.MEAN: 'mean'>]

Returns:

Type Description
DataFrame

DataFrame of XY coordinates with aggregated data.

Exceptions:

Type Description
ValueError
  • if no aggregation method is provided.
  • if 'X' or 'Y' are part of the properties.
Error

if one of the agg_methods is not supported.

bounds(self, region=None) 🍋

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

Parameters:

Name Type Description Default
region str

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

 None

Returns:

Type Description
ndarray

XYZ bounding coordinates.

convert_to_gis_object(self, name, properties=None, agg_methods=[<AggregationMethod.SUM: 'sum'>, <AggregationMethod.MIN: 'min'>, <AggregationMethod.MAX: 'max'>, <AggregationMethod.MEAN: 'mean'>]) 🍋

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 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[str]

aggregation data methods. See pandas.DataFrame.groupby to find out supported methods.

 [<AggregationMethod.SUM: 'sum'>, <AggregationMethod.MIN: 'min'>, <AggregationMethod.MAX: 'max'>, <AggregationMethod.MEAN: 'mean'>]

Returns:

Type Description
GISObject

GeoLime GISObject.

Exceptions:

Type Description
ValueError

if 'X' or 'Y' are part of the properties.
Error

if one of the agg_methods is not supported.

coords(self, region=None) 🍋

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

Parameters:

Name Type Description Default
region str

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

 None

Returns:

Type Description
ndarray

XYZ coordinates.

element_count(self) 🍋

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.

plot_2d(self, property, agg_method, 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
property str

object attribute to aggregate and display.

 required
agg_method str

aggregation data method. See pandas.DataFrame.groupby to find out supported methods.

 required
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[matplotlib.axes.Axes, folium.folium.Map]

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

Exceptions:

Type Description
ValueError

if packages are missing for interactive mode.

sample_count(self) 🍋

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.

GISObject (Entity, ObjectMixin) 🍋

GIS representation of 3D object in 2D.

Parameters:

Name Type Description Default
name str

object name.

 required
geometry ~GeoData

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

 required

Exceptions:

Type Description
ValueError

Object name is not provided.
ValueError

Geometry is empty.

Attributes:

Name Type Description
name

object name.
builtins

built-ins object property names.
default_support

the default database used when setting/getting attributes.

bounds(self, region=None) 🍋

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

Parameters:

Name Type Description Default
region str

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

 None

Returns:

Type Description
ndarray

XY bounding coordinates.

concave_hull(self, alpha=0.0) 🍋

Compute bouding 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

Returns:

Type Description
Polygon

Hull of data.

convex_hull(self) 🍋

Compute Convex Hull of geometry.

Returns:

Type Description
Polygon

Convex Hull.

element_count(self) 🍋

Return the number of geometrical elements for this object.

Returns:

Type Description
int

Number of elements.

plot(self, 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

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[matplotlib.axes.Axes, folium.folium.Map]

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

Exceptions:

Type Description
ValueError

if packages are missing for interactive mode.
Back to top