Domain definition

Bases: BaseGeom

Geometry object factory

Factory class that creates and returns concrete geometry object based on the input types.

Attributes:

crs: Read-only attribute for CRS of the input geometry
multipolygon: Read-only attribute for shapely representation of the geometry

Methods

is_valid_type(geom)

Static method to check if an object is a valid geometry type

Notes

The object created when using this class is not an instance of this class or a subclass of it. It is a subclass of BaseGeom instead.

Parameters:

geomCanCreateGeom: Object to create the domain geometry from. The type of this object determines the created geometry object type
**kwargsdict, optional: Keyword arguments passed to the constructor of the correct geometry type

Attributes:

crs: Read-only attribute for CRS of the input geometry
multipolygon: Read-only attribute for shapely representation of the geometry

Methods

`get_multipolygon`(**kwargs)	Calculate the shapely representation of the geometry
`is_valid_type`(geom)	Checks if an object is a valid geometry type
`msh_t`(**kwargs)	Returns the jigsawpy representation of the geometry.

static is_valid_type(geom: Any) → bool: Checks if an object is a valid geometry type

get_multipolygon(**kwargs: Any) → MultiPolygon

Calculate the shapely representation of the geometry

This abstract method defines the expected API for a geometry object.

Raises:

NotImplementedError: If method is not redefined in the subclass

property crs: CRS: Read-only attribute for CRS of the input geometry

msh_t(**kwargs: Any) → jigsaw_msh_t

Returns the jigsawpy representation of the geometry.

This method calculates the vertex-edge representation of the geometry in the form of jigsaw_msh_t. The return value is in a projected CRS. If the geometry CRS is geographic, then a local UTM CRS is calculated and used for this representation.

Parameters:

**kwargsdict, optional: Keyword arguments passed to get_multipolygon method

Returns:

jigsaw_msh_t: Calculated vertex-edge representation of the geometry if a projected or local UTM CRS.

Notes

The output of this method needs to have length unit for distances (i.e. not degrees) since mesh size is specified in length units and the domain and size function are the passed to the mesh engine for cartesian meshing.

property multipolygon: MultiPolygon

Read-only attribute for shapely representation of the geometry

This read-only attribute is calculated lazily and has the same value as calling get_multipolygon without any arguments.

class ocsmesh.geom.RasterGeom(raster: Raster | str | PathLike, zmin: float | None = None, zmax: float | None = None)

Bases: BaseGeom

Raster based geometry.

Create geometry based on a raster object. All the calculations are done on the raster image.

Attributes:

raster: Read-only attribute for reference to the source raster
crs: Read-only attribute returning the CRS of the source raster

Methods

msh_t(kwargs)**	Returns the jigsawpy vertex-edge representation of the geometry
get_multipolygon(zmin=None, zmax=None)	Returns shapely object representation of the geometry

Notes

This is the main object to use for handling DEM data. The objects of this class hold a reference to the original raster object and use that handle to extract data using Raster API.

Initialize a raster based geometry object.

Parameters:

rasterRaster or str or path-like: Input raster for generating the geometry, i.e. the simulation domain
zminfloat or None, default=None: Minimum elevation cut-off for calculating polygon
zmaxfloat or None, default=None: Maximum elevation cut-off for calculating polygon

Attributes:

crs: Read-only attribute returning the CRS of the source raster
multipolygon: Read-only attribute for shapely representation of the geometry
raster: Read-only attribute for reference to the source raster

Methods

`get_multipolygon`([zmin, zmax])	Returns the shapely representation of the geometry
`make_plot`([ax, show])	Create a plot from the boundaries of the geometry polygon
`msh_t`(**kwargs)	Returns the jigsawpy representation of the geometry.

get_multipolygon(zmin: float | None = None, zmax: float | None = None) → MultiPolygon

Returns the shapely representation of the geometry

Calculates and returns the MultiPolygon representation of the geometry.

Parameters:

zminfloat or None, default=None: Minimum elevation cut-off for calculating polygon, overrides value provided during object construction
zmaxfloat or None, default=None: Maximum elevation cut-off for calculating polygon, overrides value provided during object construction

Returns:

MultiPolygon: Calculated polygon from raster data based on the minimum and maximum elevations of interest.

property raster: Raster: Read-only attribute for reference to the source raster

property crs: CRS: Read-only attribute returning the CRS of the source raster

make_plot(ax: Axes | None = None, show: bool = False) → Axes

Create a plot from the boundaries of the geometry polygon

Parameters:

axAxes or None, default=None: An existing axes to draw the geomtry polygon on
showbool, default=False: Whether to call pyplot.show() after drawing the polygon

Returns:

Axes: The axes onto which the polygon boundaries are drawn

msh_t(**kwargs: Any) → jigsaw_msh_t

Returns the jigsawpy representation of the geometry.

This method calculates the vertex-edge representation of the geometry in the form of jigsaw_msh_t. The return value is in a projected CRS. If the geometry CRS is geographic, then a local UTM CRS is calculated and used for this representation.

Parameters:

**kwargsdict, optional: Keyword arguments passed to get_multipolygon method

Returns:

jigsaw_msh_t: Calculated vertex-edge representation of the geometry if a projected or local UTM CRS.

Notes

The output of this method needs to have length unit for distances (i.e. not degrees) since mesh size is specified in length units and the domain and size function are the passed to the mesh engine for cartesian meshing.

property multipolygon: MultiPolygon

Read-only attribute for shapely representation of the geometry

This read-only attribute is calculated lazily and has the same value as calling get_multipolygon without any arguments.

class ocsmesh.geom.MeshGeom(mesh: BaseMesh | str | PathLike)

Bases: BaseGeom

Mesh based geometry.

Create a geometry based on an input mesh. All the calculations for polygon are done on the underlying mesh object.

Attributes:

meshBaseMesh: Read-only attribute for reference to the source mesh
crsCRS: Read-only attribute returning the CRS of the underlying mesh

Methods

get_multipolygon(kwargs)**	Returns shapely object representation of the geometry
msh_t(kwargs)**	Returns the jigsawpy vertex-edge representation of the geometry

Notes

This class is a handy tool for reusing existing mesh extent for geometry (i.e. domain) definition and then remeshing that domain.

Initialize a mesh based geometry object

Parameters:

mesh:: Input object used to compute the output mesh hull.

Attributes:

crs: Read-only attribute returning the CRS of the underlying mesh
mesh: Read-only attribute for reference to the source mesh
multipolygon: Read-only attribute for shapely representation of the geometry

Methods

`get_multipolygon`(**kwargs)	Returns the shapely representation of the geometry
`msh_t`(**kwargs)	Returns the jigsawpy representation of the geometry.

get_multipolygon(**kwargs) → MultiPolygon

Returns the shapely representation of the geometry

Calculates and returns the MultiPolygon representation of the geometry.

Parameters:

**kwargsdict, optional: Currently unused for this class, needed for generic API support

Returns:

MultiPolygon: Calculated polygon from mesh based on the element boundaries

property mesh: Read-only attribute for reference to the source mesh

property crs: Read-only attribute returning the CRS of the underlying mesh

msh_t(**kwargs: Any) → jigsaw_msh_t

Returns the jigsawpy representation of the geometry.

This method calculates the vertex-edge representation of the geometry in the form of jigsaw_msh_t. The return value is in a projected CRS. If the geometry CRS is geographic, then a local UTM CRS is calculated and used for this representation.

Parameters:

**kwargsdict, optional: Keyword arguments passed to get_multipolygon method

Returns:

jigsaw_msh_t: Calculated vertex-edge representation of the geometry if a projected or local UTM CRS.

Notes

The output of this method needs to have length unit for distances (i.e. not degrees) since mesh size is specified in length units and the domain and size function are the passed to the mesh engine for cartesian meshing.

property multipolygon: MultiPolygon

Read-only attribute for shapely representation of the geometry

This read-only attribute is calculated lazily and has the same value as calling get_multipolygon without any arguments.

class ocsmesh.geom.PolygonGeom(polygon: Polygon, crs: CRS | str)

Bases: ShapelyGeom

Geometry based on shapely.geometry.Polygon.

Attributes:

polygonPolygon: Read-only attribute referencing the underlying Polygon
crscrs: Read-only attribute returning the CRS associated with the geometry

Methods

get_multipolygon(kwargs)**	Returns shapely object representation of the geometry
msh_t(kwargs)**	Returns the jigsawpy vertex-edge representation of the geometry

Initialize a shapely based geometry object

Parameters:

polygonPolygon: Input polygon to be used for geometry object
crsCRS or str: The CRS of the input Polygon

Attributes:

crs: Read-only attribute returning the CRS associated with the geometry
multipolygon: Read-only attribute for shapely representation of the geometry
polygon: Read-only attribute referencing the underlying Polygon

Methods

`get_multipolygon`(**kwargs)	Returns a MultiPolygon from the underlying shapely geometry
`msh_t`(**kwargs)	Returns the jigsawpy representation of the geometry.

get_multipolygon(**kwargs: Any) → MultiPolygon

Returns a MultiPolygon from the underlying shapely geometry

Parameters:

**kwargsdict, optional: Currently unused for this class, needed for generic API support

Returns:

MultiPolygon: Multipolygon created from the input single polygon

property polygon: Read-only attribute referencing the underlying Polygon

property crs: Read-only attribute returning the CRS associated with the geometry

msh_t(**kwargs: Any) → jigsaw_msh_t

Returns the jigsawpy representation of the geometry.

This method calculates the vertex-edge representation of the geometry in the form of jigsaw_msh_t. The return value is in a projected CRS. If the geometry CRS is geographic, then a local UTM CRS is calculated and used for this representation.

Parameters:

**kwargsdict, optional: Keyword arguments passed to get_multipolygon method

Returns:

jigsaw_msh_t: Calculated vertex-edge representation of the geometry if a projected or local UTM CRS.

Notes

The output of this method needs to have length unit for distances (i.e. not degrees) since mesh size is specified in length units and the domain and size function are the passed to the mesh engine for cartesian meshing.

property multipolygon: MultiPolygon

Read-only attribute for shapely representation of the geometry

This read-only attribute is calculated lazily and has the same value as calling get_multipolygon without any arguments.

class ocsmesh.geom.MultiPolygonGeom(multipolygon: MultiPolygon, crs: CRS | str)

Bases: ShapelyGeom

Initialize a shapely based geometry object

Parameters:

multipolygonMultiPolygon: Input multipolygon to be used for geometry object
crsCRS or str: The CRS of the input Polygon

Attributes:

crs: Read-only attribute for CRS of the input geometry
multipolygon: Read-only attribute referencing the underlying MultiPolygon

Methods

`get_multipolygon`(**kwargs)	Returns the underlying shapely MultiPolygon
`msh_t`(**kwargs)	Returns the jigsawpy representation of the geometry.

get_multipolygon(**kwargs)

Returns the underlying shapely MultiPolygon

Parameters:

**kwargsdict, optional: Currently unused for this class, needed for generic API support

Returns:

MultiPolygon: Underlying Multipolygon

property multipolygon: Read-only attribute referencing the underlying MultiPolygon

property crs: CRS: Read-only attribute for CRS of the input geometry

msh_t(**kwargs: Any) → jigsaw_msh_t

Returns the jigsawpy representation of the geometry.

This method calculates the vertex-edge representation of the geometry in the form of jigsaw_msh_t. The return value is in a projected CRS. If the geometry CRS is geographic, then a local UTM CRS is calculated and used for this representation.

Parameters:

**kwargsdict, optional: Keyword arguments passed to get_multipolygon method

Returns:

jigsaw_msh_t: Calculated vertex-edge representation of the geometry if a projected or local UTM CRS.

Notes

The output of this method needs to have length unit for distances (i.e. not degrees) since mesh size is specified in length units and the domain and size function are the passed to the mesh engine for cartesian meshing.

Bases: BaseGeom

Geometry object based on multiple input types

Geometry type that merges the information from different types of inputs such as raster, mesh and shapely geometries.

Attributes:

crsCRSDescriptor: Read-only attribute for CRS of the input geometry
multipolygonMultiPolygon: Read-only attribute for shapely representation of the geometry

Methods

msh_t(kwargs)**	Returns the jigsawpy vertex-edge representation of the geometry
get_multipolygon(kwargs)**	Returns shapely object representation of the geometry
add_patch(…)	Define local (patch) contour extraction definition from all the input data (e.g. raster, mesh, etc.)

Initialize geometry collector object

Parameters:

in_listlist: List of objects that from which single geometry object can be created. This includes path to a raster or mesh file as a string, as well as Raster, Mesh or Polygon objects. Note that objects are not copied and currently any clipping that happens during processing will affect the objects pass to the GeomCollector constructor.
base_meshMesh or None, default=None: Base mesh to be used for extracting boundaries of the domain. If not None all the input rasters all clipped by base_mesh polygon before further processing. This is useful for cases where we’d like to locally refine features of the domain (domain region >> inputs region) or when input rasters are much larger that the domain and we’d like to extract contours only within domain to save on computation.
zminfloat or None, default=None: Minimum elevation for extracting domain.
zmaxfloat or None, default=None: Maximum elevation for extracting domain.
nprocs: int or None, default=None: Number of processors to use in parallel parts of the collector computation
chunk_size: int or None, default=None: Chunk size for windowed calculation on rasters
overlap: int or None default=None: Window overlap for windowed calculation on rasters
verbosity: int, default=0,: Verbosity of the output
base_shape: Polygon or MultiPolygon or None, default=None: Similar to base_mesh, but instead of calculating the polygon from mesh, directly receive it from the calling code.
base_shape_crs: str or CRS, default=’EPSG:4326’: CRS of the input base_shape.

Attributes:

crs: Read-only attribute for CRS of the input geometry
multipolygon: Read-only attribute for shapely representation of the geometry

Methods

`add_patch`([shape, level, contour_defn, ...])	Specifies an area of geometry inputs to extract contours
`get_multipolygon`(**kwargs)	Returns the shapely representation of the geometry
`msh_t`(**kwargs)	Returns the jigsawpy representation of the geometry.

get_multipolygon(**kwargs: Any) → MultiPolygon

Returns the shapely representation of the geometry

Calculates and returns the MultiPolygon representation of the geometry.

Parameters:

**kwargsdict, optional: Currently unused for this class, needed for generic API support

Returns:

MultiPolygon: Calculated and merged polygons from all geometry inputs.

Notes

All calculations are done lazily and the results is not cached. During this process all the stored contour extraction specs are applied on all the inputs and then the resulting shapes are merged.

Calculation for each DEM and feature is stored on disk as feather files. In the last steps are all these feather files are combined using the out of core calculation by GeoPandas.

Specifies an area of geometry inputs to extract contours

Specifies a localized area of geometry inputs to extract contours from.

Parameters:

shapeMultiPolygon or Polygon or None, default=None: shapely (multi)polygon to specify the area from which contour specification for this patch should be extracted. CRS is assumed to be EPSG:4326.
level: float or tuple of float, default=None: Contour level specification for this patch. If provided, it could either be a single floating point number for the maximum elevation or a tuple indicating minimum and maximum elevations for contour extraction.
contour_defnFilledContour or Contour or None, default=None: Alternative way of specifying maximum or minimum or both elevation levels for contour extraction.
patch_defnPatch or None, default=None: Alternative way to specify which region within the input the contours need to be extracted from.
shapefile: str or Path or None, default=None: Alternative way to specify which region within the input the contours need to be extracted from.

Returns:

None

Notes

This method doesn’t result in any calculations. It simply stores the information about the user specified contour. During the get_multipolygon call the contours are actually calculated on all the inputs.

property crs: CRS: Read-only attribute for CRS of the input geometry

msh_t(**kwargs: Any) → jigsaw_msh_t

Returns the jigsawpy representation of the geometry.

This method calculates the vertex-edge representation of the geometry in the form of jigsaw_msh_t. The return value is in a projected CRS. If the geometry CRS is geographic, then a local UTM CRS is calculated and used for this representation.

Parameters:

**kwargsdict, optional: Keyword arguments passed to get_multipolygon method

Returns:

jigsaw_msh_t: Calculated vertex-edge representation of the geometry if a projected or local UTM CRS.

Notes

The output of this method needs to have length unit for distances (i.e. not degrees) since mesh size is specified in length units and the domain and size function are the passed to the mesh engine for cartesian meshing.

property multipolygon: MultiPolygon

Read-only attribute for shapely representation of the geometry

This read-only attribute is calculated lazily and has the same value as calling get_multipolygon without any arguments.