pybend.model package

This package provides the data structure and process functions.

pybend.model.Bend module

Bend model.

This module defines the Bend object and helpers to encode/decode bend unique identifiers.

Let’s suppose a sinuous channel centerline. Bends are defined as the channel path comprised between two consecutive inflection points (o). A bend contains an apex whose definition may vary according to bend shape:

By convention, a bend is UP if curvature is positive (clockwise rotation along flow direction), and DOWN if curvature is negative (counter-clockwise rotation along flow direction).

                     UP                    DOWN
                     x
                   .   .               o     m     o
  Flow           .       .              .    b    .
   -->          .    b    .              .       .
Direction      o     m     o               .   .
                                             x

Elementary bends are defined by upstream and downstream inflection points (o). Bends contain distinctive points including the apex (x), the middle (m) and the barycenter (b).

class pybend.model.Bend.Bend(bend_id: int, index_inflex_up: int, index_inflex_down: int, age: int = 0, side: BendSide = BendSide.UNKNWON, isvalid: bool = False)

Bases: object

A meander bend delimited by two consecutive inflection points.

Store bend parameters associated to a Centerline object.

Parameters:

  • bend_id (int) – Bend id.

  • index_inflex_up (int) – index of the upstream inflection point along the centerline.

  • index_inflex_down (int) – index of the downstream inflection point along the centerline.

  • age (int, optional) – Age of the bend. Defaults to 0.

  • side (BendSide, optional) – Bend side (UP, DOWN, or UNKNOWN). Defaults to BendSide.UNKNWON.

  • isvalid (bool, optional) – bend is valid if its sinuosity is greater than a user defined threshold. Defaults to False.

add_bend_connection_next(bend_uid: int) → None

Add bend connection with bend in the next centerline.

Parameters:

bend_uid (int) – unique index of the bend connected to itself.

add_bend_connection_prev(bend_uid: int) → None

Add bend connection with bend in the previous centerline.

Parameters:

bend_uid (int) – unique index of the bend connected to itself.

add_intersected_section_index(i: int) → None

Add the section index of intersected section with itself.

Parameters:

i (int) – section index

get_nb_points() → int

Get the number of points of the bend.

Returns:

number of points

Return type:

int

age: int

bend age

apex_probability: ndarray[tuple[Any, ...], dtype[float64]] | None

apex probability values for each point of the bend

apex_probability_smooth: ndarray[tuple[Any, ...], dtype[float64]] | None

smoothed apex probability values for each point of the bend

bend_evol_id: int | None

id of the BendEvolution object the bend belongs to

bend_uid_next: list[int] | None

indexes of connected bend in next centerline

bend_uid_prev: list[int] | None

indexes of connected bend in previous centerline

id: int

bend id

index_apex: int

index of apex point

index_inflex_down: int

index of downstream inflection point

index_inflex_up: int

index of upstream inflection point

index_max_curv: int | None

index of maximal curvature point

intersected_section_indexes: list[int] | None
isvalid: bool

bend is valid

params: Series | None
params_averaged: DataFrame | None
polygon: Polygon | LineString | None

polygon defined by the centerline between upstream and downstream inflection points and is closed between these points

pt_center: ndarray[tuple[Any, ...], dtype[float64]] | None

center point coordinates. Center point is defined as the point at equal distance from inflection points.

pt_centroid: ndarray[tuple[Any, ...], dtype[float64]] | None

Bend centroid is the barycenter of the polygon defined by the centerline between upstream and downstream inflection points and is closed between these points.

side: BendSide

bend side

uid: int

bend unique id

class pybend.model.Bend.BendClPointIndexIter(bend: Bend)

Bases: object

Iterator over channel-point indices belonging to a Bend.

Create an iterator over bend channel-point indices.

Parameters:

bend (Bend) – Bend to iterate to.

bend

bend

index: int

index

pybend.model.Bend.get_bend_uid(bend_id: int, age: int) → int

Get bend unique id from bend id and age.

Parameters:

  • bend_id (int) – bend index

  • age (int) – age

Returns:

unique id

Return type:

int

pybend.model.Bend.parse_bend_uid(uid: int) → tuple[int, int]

Parse bend unique id to get back bend index and age.

Parameters:

uid (int) – bend unique id

Returns:

tuple containing bend age and index.

Return type:

tuple[float, int]

pybend.model.Bend.uid_module: int = 10000

modulo value for bend unique ids

pybend.model.BendEvolution module

Bend-evolution model.

Bend evolutions store how a bend (or a group of bends) evolves through time in a CenterlineCollection.

A bend at a give time may progressively become multilobate, including multiple smaller order bends. This is why Bend collection stores a list of bend index at each time step. In addition BendEvolution order increases with the number of individual bends it includes.

                X
           x °      °
       .   °   .      °
     .          .
         °               °
   .               .
       °                   °
 .                   .
     O                      O
o                     o

A BendEvolution contains the successvive state of a same bend that evolves through time, for instance here the bend has tranlated between age t (o..x..o) and t+1 (O°°X°°O)

class pybend.model.BendEvolution.BendEvolution(bend_indexes: dict[int, list[int]], ide: int, order: int, isvalid: bool = False)

Bases: object

A tracked bend (or bend group) evolving through time.

Store bend indexes in each Centerline that belongs to BendEvolution.

Parameters:

  • bend_indexes (dict[int, list[int]]) – dictionnary that contains indexes of bends that belongs to this BendEvolution in each centerline

  • ide (int) – id of bend evolution

  • order (int) – order of bend evolution

  • isvalid (bool, optional) – bend evolution is valid. Defaults to False.

_check_is_valid(nb: int) → bool

Check bend validity according to input number of bends.

Parameters:

nb (int) – minimum number of bends

get_all_ages() → ndarray[tuple[Any, ...], dtype[int64]]

Get the ages of all the bends that belong to the bend evolution.

Returns:

ages of bends

Return type:

npt.NDArray[np.int64]

get_number_of_bends() → int

Get the number of bends.

Returns:

number of bends

Return type:

int

set_is_valid(nb: int) → None

Update isvalid according to input number of bends.

Parameters:

nb (int) – minimum number of bends

apex_trajec_smooth: list[ndarray[tuple[Any, ...], dtype[float64]]]

list of smoothed apex point location

bend_indexes: dict[int, list[int]]

indexes of bends in each centerline that belongs to bend evolution

centroid_trajec_smooth: list[ndarray[tuple[Any, ...], dtype[float64]]]

list of smoothed centroid point location

id: int

bend evolution id

inflex_down_trajec_smooth: list[ndarray[tuple[Any, ...], dtype[float64]]]

list of smoothed downstream inflection point location

inflex_up_trajec_smooth: list[ndarray[tuple[Any, ...], dtype[float64]]]

list of smoothed upstream inflection point location

isvalid: bool

bend evolution validity

middle_trajec_smooth: list[ndarray[tuple[Any, ...], dtype[float64]]]

list of smoothed middle point location

order: int

bend evolution order

pybend.model.Centerline module

Centerline model.

Defines the Centerline object and methods to compute centerline attributes (inflection points, bends, apex/middle/centroid, etc.).

Let’s consider a channel centerline discretized into successive channel points. This module defines the Centerline object that stores all channel points. Centerline object also provides multiple methods to compute centerline attributes like inflection point locations, meander bends, bend apex, middle and barycenter point locations.

       x                         x                         x
    .     .                    .    .                   .    .
  .         .                .        .               .        .
 .     b     .              .     b    .             .     b    .
o      m      o      m     o      m     o     m     o      m     o
               .     b    .              .    b    .
                .        .                .       .
                  .    .                    .   .
                     x                        x

Sinuous channel centerline discretized into a series avec channel points (.) where bends are defined by upstream and downstream inflection points (o). Bends contains distinctive points including the apex (x), the middle (m) and the barucenter (b).

To use it:

centerline :Centerline = Centerline()
class pybend.model.Centerline.Centerline(age: int, dataset: DataFrame, spacing: float, smooth_distance: float, use_fix_nb_points: bool = False, curvature_filtering_window: int = 5, sinuo_thres: float = 1.05, n: float = 2, compute_curvature: bool = True, interpol_props: bool = True, find_bends: bool = True)

Bases: object

A channel centerline represented as an ordered collection of points.

Store channel centerline as a collection of ClPoint.

Parameters:

  • age (int) – Age of the centerline.

  • dataset (pd.DataFrame) – DataFrame that contains channel point coordinates and properties. Points must be ordered according to flow direction.

  • spacing (float) – Target distance (m) between channel points after resampling. If spacing equals 0, centerline is not resampled.

  • smooth_distance (float) – Smoothing distance (m) for Savitsky-Golay filter applied on channel path.

  • use_fix_nb_points (bool, optional) – If True, the resampled centerline will contains exactly spacing points, otherwise, spacing is the targeted distance between 2 consecutive points. Defaults to False.

  • curvature_filtering_window (int, optional) – Number of points used for filtering curvature. Defaults to 5.

  • sinuo_thres (float, optional) – Sinuosity threshold used to discriminate valid bends. Defaults to 1.05.

  • n (float) – exponent value for bend apex detection Defaults to 2.

  • compute_curvature (bool, optional) – If True, recompute and filter curvature along channel points. Defaults to True.

  • interpol_props (bool, optional) – If True, interpolate channel point properties along channel points. Defaults to True.

  • find_bends (bool, optional) – If True, automatically compute curvature and interpolate properties and detect meander bends along channel centerline. Defaults to True.

_compute_bend_apex_probability_user_weights(bend_index: int, curvature_weight: float, amplitude_weight: float, length_weight: float) → ndarray[tuple[Any, ...], dtype[float64]]

Compute bend apex probability according to input weights.

Apex probability corresponds to the probability \([0, 1]\) of a channel point being an apex according to its curvature, its distance to the bend middle point, and its distance to the closest inflection point.

The result is stored in Bend.apex_probability and as a property of channel points.

Parameters:

  • bend_index (int) – Index of the bend to treat.

  • curvature_weight (float) – Weight [0, 1] used for curvature property.

  • amplitude_weight (float) – Weight [0, 1] used for the distance to the middle point.

  • length_weight (float) – Weight [0, 1] used for the distance to inflection points.

Returns:

Apex probability of each channel point.

Return type:

npt.NDArray[np.float64]

_compute_bend_properties(sinuo_thres: float, n: float, bend_index: int) → tuple[BendSide, bool, int, ndarray[tuple[Any, ...], dtype[float64]]]

Compute bend properties (side, validity, apex and middle points).

Parameters:

  • sinuo_thres (float) – Sinuosity threshold used to discriminate valid bends.

  • n (float) – exponent value

  • bend_index (int) – Bend index.

Returns:

tuple containing side, isvalid, apex_index, and pt_center

Return type:

tuple[BendSide, bool, int, npt.NDArray[np.float64]]

_compute_curvature(dataset: DataFrame) → None

Compute the curvature of channel points along the centerline.

Parameters:

dataset (DataFrame) – DataFrame that contains channel point data. Input DataFrame is updated with the computed property.

_compute_curvature_monoproc(dataset: DataFrame) → None

Compute the curvature of channel points using monoprocessing.

Parameters:

dataset (DataFrame) – DataFrame that contains channel point data. Input DataFrame is updated with the computed property.

_compute_curvature_multiproc(dataset: DataFrame, nb_procs: int) → None

Compute the curvature of channel points using multirocessing.

Parameters:

  • dataset (DataFrame) – DataFrame that contains channel point data. Input DataFrame is updated with the computed property.

  • nb_procs (int) – number of processors.

_compute_curvilinear_abscissa(dataset: DataFrame) → None

Compute curvilinear abscissa of channel points along the centerline.

Parameters:

dataset (DataFrame) – DataFrame that contains channel point data. Input DataFrame is updated with the computed property.

_compute_distance_orthogonal_to_inflection_segment(bend_index: int, cl_pt_index: int) → float

Compute the distance between a channel point and the bend chord.

Bend chord is the segment defined by bend inflection points.

Warning

Channel point must belongs to the bend.

Parameters:

  • bend_index (int) – Index of the bend to treat.

  • cl_pt_index (int) – Index of the channel point.

Returns:

Distance (m) if channel point belongs to the bend.

Return type:

float

_compute_distance_to_bend_center(bend_index: int, cl_pt_index: int) → float

Compute the distance between a channel point and bend center point.

Warning

Channel point must belongs to the bend.

Parameters:

  • bend_index (int) – Index of the bend to treat.

  • cl_pt_index (int) – Index of the channel point.

Returns:

Distance (m) if channel point belongs to the bend.

Return type:

float

_compute_filtered_curvature(dataset: DataFrame, window: int, method: FilterName = FilterName.SAVITSKY) → None

Compute filtered curvature of channel points along the centerline.

Input DataFrame is updated with the computed property.

Parameters:

  • dataset (DataFrame) – DataFrame that contains channel point data.

  • window (int) – Number of points used for filtering curvature.

  • method (FilterName) – Filter to use, either FilterName.UNIFORM or Smooth_filter.SAVITSKY Defaults to FilterName.SAVITSKY.

_compute_index_max_curvature(bend_index: int) → int

Compute the index of maximum curvature along a bend.

Parameters:

bend_index (int) – bend index

Returns:

index of max curvature from upstream inflection point

Return type:

int

_compute_normal_to_points(dataset: DataFrame) → None

Compute the normal to channel points along the centerline.

Parameters:

dataset (DataFrame) – DataFrame that contains channel point data. Input DataFrame is updated with the computed property.

_compute_property_at_point(dataset: DataFrame, props_excluded: tuple[str, ...], dataset_new: DataFrame, i: int, row: Series) → None

Compute interpolated properties at index i in dataset_new.

Parameters:

  • dataset (pd.DataFrame) – Original DataFrame from which properties are interpolated.

  • props_excluded (tuple[str, ...]) – Properties excluded from interpolation.

  • dataset_new (pd.DataFrame) – Target DataFrame that is updated in-place.

  • i (int) – Index in dataset_new.

  • row (pd.Series) – Row containing the two source indices and distances used for interpolation.

_create_bend(bend_id: int, inflex_index_up: int, inflex_index_down: int) → Bend

Create a Bend object.

Parameters:

  • bend_id (int) – Id of the bend.

  • inflex_index_up (int) – Index of upstream inflection point.

  • inflex_index_down (int) – Index of downstream inflection point.

Returns:

Created Bend object.

Return type:

Bend

_create_bends_monoproc(inflex_pts_index: ndarray[tuple[Any, ...], dtype[int64]], sinuo_thres: float, n: float) → None

Create all Bend objects and add them in self.bends using monoproc.

Parameters:

  • inflex_pts_index (npt.NDArray[np.int64]) – List of inflection point indexes.

  • sinuo_thres (float) – Sinuosity threshold used to discriminate valid bends.

  • n (float) – exponent value

_create_bends_multiproc(inflex_pts_index: ndarray[tuple[Any, ...], dtype[int64]], sinuo_thres: float, n: float) → None

Create all Bend objects add them in self.bends using multiproc.

Parameters:

  • inflex_pts_index (npt.NDArray[np.int64]) – List of inflection point indexes.

  • sinuo_thres (float) – Sinuosity threshold used to discriminate valid bends.

  • n (float) – exponent value

_init_centerline(dataset: DataFrame, age: int, spacing: float, smooth_distance: float, curvature_filtering_window: int, use_fix_nb_points: bool, compute_curvature: bool, interpol_props: bool) → None

Initialize Centerline object.

Centerline intialization includes:

  • resampling the centerline with a parametric spline function

  • if spacing > 0, smoothing centerline path

  • if interpol_props is True, interpolating centerline properties to new points

  • if compute_curvature is True, computing and filtering curvatures

  • fill the list of channel point self.cl_points

Parameters:

  • dataset (DataFrame) – DataFrame that contains channel point coordinates and properties. Points must be ordered according to flow direction.

  • age (int) – Age of the centerline.

  • spacing (float) – Target distance (m) between channel points after resampling. If spacing equals 0, centerline is not resampled.

  • smooth_distance (float) – Smoothing distance (m) for Savitsky-Golay filter applied on channel path.

  • curvature_filtering_window (int) – Number of points used for filtering curvature.

  • use_fix_nb_points (bool) – If True, the resampled centerline will contains exactly spacing points, otherwise, spacing is the targeted distance between 2 consecutive points.

  • compute_curvature (bool) – If True, compute and smooth curvatures.

  • interpol_props (bool) – if True, interpolate centerline properties.

_interpolate_properties(dataset_new: DataFrame, dataset: DataFrame) → bool

Interpolate properties from dataset to dataset_new.

Parameters:

  • dataset_new (DataFrame) – DataFrame with resampled centerline data where to interpolate properties.

  • dataset (DataFrame) – Original DataFrame from which come properties.

Returns:

True if interpolation successfully ended. Input DataFrame dataset_new is updated with the computed properties.

Return type:

bool

_update_bend(bend_index: int, side: BendSide | None = None, valid: bool | None = None, index_apex: int | None = None, pt_center: ndarray[tuple[Any, ...], dtype[float64]] | None = None, pt_centroid: ndarray[tuple[Any, ...], dtype[float64]] | None = None) → None

Update bend properties (side, validity, apex and middle points).

Parameters:

  • bend_index (int) – Bend index.

  • side (BendSide, optional) – bend side Defaults to None.

  • valid (bool, optional) – bend validity Defaults to None.

  • index_apex (int, optional) – bend apex index Defaults to None.

  • pt_center (npt.NDArray[np.float64], optional) – bend middle point Defaults to None.

  • pt_centroid (npt.NDArray[np.float64], optional) – bend centroid point Defaults to None.

check_if_bend_is_valid(sinuo_thres: float, bend_index: int) → bool

Check if a bend is valid.

Parameters:

  • sinuo_thres (float) – Sinuosity threshold used to discriminate valid bends.

  • bend_index (int) – Index of the bend to treat.

Returns:

True if the bend is valid, False otherwise.

Return type:

bool

compute_all_bend_center() → None

Compute center point and update Bend of all bends.

compute_all_bend_centroid() → None

Compute centroid point and update Bend for all bends.

Bend centroid is the barycenter of the polygon defined by the centerline between upstream and downstream inflection points and is closed between these points.

compute_bend_centroid(bend_index: int) → ndarray[tuple[Any, ...], dtype[float64]]

Compute bend centroid point and update Bend.

Parameters:

bend_index (int) – Index of the bend to treat.

Returns:

bend centroid point coordinates

Return type:

npt.NDArray[np.float64]

compute_bend_middle(bend_index: int) → ndarray[tuple[Any, ...], dtype[float64]]

Compute bend middle point and update Bend.

Parameters:

bend_index (int) – Index of the bend to treat.

Returns:

middle point coordinates

Return type:

npt.NDArray[np.float64]

compute_bend_polygon(bend_index: int) → Polygon | LineString

Compute bend polygon.

Bend polygon defined by the centerline between upstream and downstream inflection points and is closed between these points.

Parameters:

bend_index (int) – Index of the bend to treat.

Returns:

bend polygon

Return type:

Polygon | LineString

filter_bends() → bool

Filter bends when some are unvalid.

Returns:

True when filtering sucessfully ended.

Return type:

bool

find_all_bend_apex(n: float) → None

Find bend apex and update Bend for all bends of the centerline.

Parameters:

n (float) – exponent value

find_all_bend_apex_user_weights(apex_proba_weights: tuple[float, float, float]) → None

Find bend apex and update Bend for all bends of the centerline.

Parameters:

apex_proba_weights (tuple[float, float, float]) – Weights for apex probability calculation. Apex probability depends on channel point curvature, bend amplitude (m), and the distance from inflection points.

find_bend_apex(n: float, bend_index: int) → int

Find bend apex from cummulative curvature function.

Parameters:

  • n (float) – exponent value

  • bend_index (int) – Index of the bend to treat.

Returns:

Bend apex index.

Return type:

int

find_bend_apex_from_weights(bend_index: int) → int

Find bend apex.

Parameters:

bend_index (int) – Index of the bend to treat.

Returns:

Bend apex index.

Return type:

int

find_bend_apex_limaye(bend_index: int) → int

Find bend apex according to Limage method.

Apex is defined from half of channel path angle variation between upstream and downstream end of the bend.

Limaye (2025) A geometric algorithm to identify river meander bends: 1. Effect of perspective. Journal of Geophysical Research: Earth Surface, 130, e2024JF007908. https://doi.org/10.1029/2024JF007908

Parameters:

bend_index (int) – Index of the bend to treat.

Returns:

Bend apex index.

Return type:

int

find_bends(sinuo_thres: float, n: float) → bool

Find bends along the centerline.

Bends are defined as the points between two consecutive inflection points.

Parameters:

  • sinuo_thres (float) – Sinuosity threshold used to discriminate valid bends.

  • n (float) – exponent value

Returns:

True if calculation successfully ended.

Return type:

bool

find_inflection_points() → ndarray[tuple[Any, ...], dtype[int64]]

Find inflection points along the centerline.

Inflection points are determine such as the smoothed curvature change of sign next to it.

Returns:

List of inflection point indexes.

Return type:

NDArray[np.int64]

gather_consecutive_invalid_bends(sinuo_thres: float) → None

Gather consecutive bends when some are unvalid.

Parameters:

sinuo_thres (float) – sinuosity threshold

get_all_curvature() → ndarray[tuple[Any, ...], dtype[float64]]

Get the array of curvature property along the centerline.

Returns:

Array with curvature values.

Return type:

NDArray[float]

get_all_curvature_filtered() → ndarray[tuple[Any, ...], dtype[float64]]

Get the array of filtered curvature property along the centerline.

Returns:

Array with smoothed curvature values.

Return type:

NDArray[float]

get_bend_curvature(bend_id: int) → ndarray[tuple[Any, ...], dtype[float64]]

Get the array of curvature property along the bend if id bend_id.

Returns:

Array with curvature values.

Return type:

NDArray[float]

get_bend_curvature_filtered(bend_id: int) → ndarray[tuple[Any, ...], dtype[float64]]

Get the array of filtered curvature property along the bend bend_id.

Returns:

Array with smoothed curvature values.

Return type:

NDArray[float]

get_bend_index_from_cl_pt_index(cl_pt_index: int) → int | None

Get bend index that contains the ClPoint at index cl_pt_index.

Parameters:

cl_pt_index (Optional[int]) – Index of the channel point in the list self.cl_points.

Returns:

Index of the bend in the list self.bends, or np.nan if no bend was found.

Return type:

int

get_bend_property(bend_id: int, prop_name: str) → ndarray[tuple[Any, ...], dtype[float64]]

Get the property of channel points along the bend with id bend_id.

Parameters:

  • bend_id (int) – Bend id.

  • prop_name (str) – Property name.

Returns:

Array with property values

Return type:

NDArray[float]

get_bend_side(bend_index: int) → BendSide

Compute bend side.

Parameters:

bend_index (int) – Index of the bend to treat.

Returns:

Bend side, either Bend_side.UP or Bend_side.DOWN.

Return type:

Bend_side

get_nb_bends() → int

Get the number of bends along the centerline.

Returns:

Number of bends

Return type:

int

get_nb_points() → int

Get the number of channel points.

Returns:

number of channel points

Return type:

int

get_nb_valid_bends() → int

Get the number of valid bends along the centerline.

Returns:

Number of valid bends

Return type:

int

get_property(prop_name: str) → ndarray[tuple[Any, ...], dtype[float64]]

Get the property of channel points along the centerline.

Parameters:

prop_name (str) – Property name

Returns:

Array with property values

Return type:

NDArray[float]

get_property_list() → tuple[str]

Get the list of property name stored on channel points.

Returns:

tuple of property names.

Return type:

tuple[str]

get_valid_bend_indexes() → list[int]

Get the list of valid bend indexes along the centerline.

Returns:

List of valid bends index

Return type:

list[int]

set_bend_apex_probability_user_weights(apex_proba_weights: tuple[float, float, float]) → None

Set bend apex probability using user-defined weights.

Parameters:

apex_proba_weights (tuple[float, float, float]) – Weights for apex probability calculation. Apex probability depends on channel point curvature, bend amplitude (m), and the distance from inflection points.

set_property_all_points(property_name: str, values: ndarray[tuple[Any, ...], dtype[float64]]) → None

Set the property values of all channel points.

Parameters:

  • property_name (str) – Property name.

  • values (NDArray[float]) – Array of value of the property.

set_property_point(cl_pt_index: int, property_name: str, value: float) → None

Set the property value of input point at index cl_pt_index.

Parameters:

  • cl_pt_index (int) – Channel point index in self.cl_points.

  • property_name (str) – Property name.

  • value (float) – Value of the property at the given channel point.

age: int

age of the enterline

bends: list[Bend]

list od bends

cl_points: list[ClPoint]

list of Channel points

index_cl_pts_next_centerline: list[list[int]]

indexes of each channel point in the next centerline

index_cl_pts_prev_centerline: list[int]

indexes of each channel point in the previous centerline

pybend.model.CenterlineCollection module

Centerline-collection model.

Defines CenterlineCollection, which stores successive channel centerlines through time for a single channel belt.

class pybend.model.CenterlineCollection.CenterlineCollection(map_centerline_data: dict[int, DataFrame], spacing: float, smooth_distance: float, use_fix_nb_points: bool, curvature_filtering_window: int = 5, sinuo_thres: float = 1.05, n: float = 2, compute_curvature: bool = True, interpol_props: bool = True, find_bends: bool = True)

Bases: object

A time series of Centerline objects representing channel evolution.

Store the successive Centerline objects from a single channel-belt.

Parameters:

  • map_centerline_data (dict[int, pd.DataFrame]) – dictionnary containing for each age a dataframe containing centerline data

  • spacing (float) – Target distance (m) between two consecutive channel points after resampling, or number of points if use_fix_nb_points is True

  • smooth_distance (float) – smoothing distance for channel point location and curvature

  • use_fix_nb_points (bool) – if True, spacing is the number of points of resampled centerline, otherwise it is the target distance.

  • curvature_filtering_window (int, optional) – Number of points to consider for curvature filtering window. Defaults to 5.

  • sinuo_thres (float, optional) – threshold above which bends are valid. Defaults to 1.05.

  • n (float) – exponent of the curvature distribution function. Defaults to 2.

  • compute_curvature (bool, optional) – if True, recompute channel point curvature after resampling. Defaults to True.

  • interpol_props (bool, optional) – if True, interpolate channel point properties along channel points after resampling. Defaults to True.

  • find_bends (bool, optional) – if True, automatically compute curvature and interpolate properties and detect bends along each centerline. Defaults to True.

_add_bend_connection(key: int, next_key: int, cur_bend_index: int, next_bend_index: int) → int

Register the reciprocal connection of bends of age key and next_key.

Parameters:

  • key (int) – Age of centerline.

  • next_key (int) – Age of successive centerline.

  • cur_bend_index (int) – index of the bend of age ‘key’.

  • next_bend_index (int) – index of the bend of age ‘next_key’.

Returns:

bend unique id

Return type:

int

_apply_centerline_warping(dmax: float, distance_weight: float, vel_perturb_weight: float, curvature_weight: float, window: int, pattern: str, keys: tuple[int, int]) → list[int]

Private method to compute centerline matching.

Parameters:

  • dmax (float) – Maximal allowed distance (m) between connected channel point.

  • distance_weight (float) – Weight [0, 1] on channel point distance.

  • vel_perturb_weight (float) – Weight [0, 1] on velocity perturbation.

  • curvature_weight (float) – Weight [0, 1] on curvature.

  • window (int) – Number of points for filter.

  • pattern (str) – Pattern input of dtw.dtw function.

  • keys (tuple[int, int]) – age of the current and previous cenerlines

Returns:

List of tuples containing indexes of Centerline of age key and indexes of Centerline of age prev_key.

Return type:

list[int]

_connect_bends_apex(dmax: float, bend_evol_validity: int) → bool

Connect bends from the successive centerlines using apex distance.

Connect bends from the successive centerlines of the collection by searching for the closests apex points that belongs to bends of same side.

Parameters:

  • dmax (float) – Maximum allowed distance (m) between 2 successive apex points.

  • bend_evol_validity (int) – Minimum number of bends in the BendEvolution to be considered as valid.

Returns:

True if the function ends witout errors

Return type:

bool

_connect_bends_centroid(dmax: float, bend_evol_validity: int) → bool

Connect bends from the successive centerlines using apex centroids.

Connect bends from the successive centerlines of the collection by searching for the closests centroids points that belongs to bends of same side.

Parameters:

  • dmax (float) – Maximum allowed distance (m) between 2 successive apex points.

  • bend_evol_validity (int) – Minimum number of bends in the BendEvolution to be considered as valid.

Returns:

True if the function ends witout errors

Return type:

bool

_connect_bends_from_matching(bend_evol_validity: int, weighting_func_type: str = 'uniform') → bool

Connect bends from the successive centerlines using matching result.

Connect bends from the successive centerlines of the collection by searching for the greatest number of connected channel points between connected bends.

Parameters:

  • bend_evol_validity (int) – Minimum number of bends in the BendEvolution to be considered as valid.

  • weighting_func_type (str, optional) – Weighting function type to use.

Returns:

True if the function ends witout errors

Return type:

bool

_create_all_channel_sections(section_line: LineString) → tuple[list[Isoline], list[int]]
_create_bend_evolution(bend_evol_validity: int, bend_uids: list[int]) → None

Create the list self.bends_evol with BendEvolution objects.

Parameters:

  • bend_evol_validity (int) – Minimum number of bends in the BendEvolution to be considered as valid.

  • bend_uids (list[int]) – list of bend uids.

_create_centerline(map_centerline_data: dict[int, DataFrame], spacing: float, smooth_distance: float, use_fix_nb_points: bool, curvature_filtering_window: int, sinuo_thres: float, n: float, compute_curvature: bool, interpol_props: bool, find_bends: bool, age: int) → Centerline

Create self.centerlines dictionnary.

CenterlineCollection object initialization consists in creating the dictionnary self.centerlines containing ages a keys and Centerline object as values.

Parameters:

  • map_centerline_data (dict[int, pd.DataFrame]) – dictionnary of ages and dataframe defining channel point location and properties.

  • spacing (float) – Target distance (m) between two consecutive channel points after resampling, or number of points if use_fix_nb_points is True

  • smooth_distance (float) – smoothing distance for channel point location and curvature

  • use_fix_nb_points (bool) – if True, spacing is the number of points of resampled centerline, otherwise it is the target distance.

  • curvature_filtering_window (int) – Number of points to consider for curvature smoothing window.

  • sinuo_thres (float) – threshold above which bends are valid.

  • n (float) – exponent of the curvature distribution function.

  • compute_curvature (bool) – if True, recompute channel point curvature after resampling.

  • interpol_props (bool) – if True, interpolate channel point properties along channel points after resampling.

  • find_bends (bool) – if True, automatically compute curvature and interpolate properties and detect bends along each centerline.

  • age (int) – centerline age

  • (pd.DataFrame (data) – centerline properties data

  • queue (mp.Queue) – queue where to dump created Centerline

Returns:

Centerline object

Return type:

Centerline

_create_section_lines_from_bend(point_name: CreateSectionMethod) → None

Create section lines across BendEvolution.

Automatically create section lines across BendEvolution objects such as lines goes by the middle or centroid point of the last bend of each BendEvolution.

Parameters:

point_name (CreateSectionMethod) – Name of point to use. It can be either CreateSectionMethod.MIDDLE or CreateSectionMethod.CENTROID.

_create_section_lines_from_neighboring_apex() → None

Create section lines across BendEvolution using APEX method.

Automatically create section lines across BendEvolution objects such as lines goes by the apex point of the last bend of each BendEvolution.

_do_smooth_bend_apex_trajec(bend_evol_index: int) → list[ndarray[tuple[Any, ...], dtype[float64]]]

Smooth apex trajectory of one bend evolution.

Parameters:

bend_evol_index (int) – bend evolution index

Returns:

Smooth apex trajectory coordinates.

Return type:

list[npt.NDArray[np.float64]]

_get_bend_evol_apex_points(bend_evol_index: int) → list[ndarray[tuple[Any, ...], dtype[float64]]]

Get the coordinates of all bend apex of the bend evolution.

Parameters:

bend_evol_index (int) – bend evolution index

Returns:

apex coordinates

Return type:

npt.NDArray[np.float64]

_get_bend_index_connection_counts(bend: Bend, key: int, next_key: int, next_iter: int, weighting_func_type: str) → list[int | None]

Get the number of times each connected bends is.

Parameters:

  • bend (Bend) – Bend object.

  • key (int) – Age of centerline.

  • next_key (int) – Next age to consider. It can be lower or greater depending on next_iter.

  • next_iter (bool) – If True, look for next centerline.

  • weighting_func_type (str) – Weighting function type to use.

Returns:

Bend uid for each connected bends, or None if no bend is connected.

Return type:

list[int | None]

_get_bend_index_from_cl_point_index(cl_pt_index: int, age: int) → int

Get bend index from the index of a channel point of age.

Parameters:

  • cl_pt_index (int) – Index of the channel point.

  • age (float) – Age of the Centerline where the channel point belongs to.

Returns:

Index of the Bend the channel point belongs to.

Return type:

int

_match_centerlines_monoproc(dmax: float, distance_weight: float, vel_perturb_weight: float, curvature_weight: float, window: int, pattern: str) → bool

Private method to compute centerline matching using monoprocessing.

Parameters:

  • dmax (float) – Maximal allowed distance (m) between connected channel point.

  • distance_weight (float) – Weight [0, 1] on channel point distance.

  • vel_perturb_weight (float) – Weight [0, 1] on velocity perturbation.

  • curvature_weight (float) – Weight [0, 1] on curvature.

  • window (int) – Number of points for filter.

  • pattern (str) – Pattern input of dtw.dtw function.

Returns:

True if calculation successfully ended.

Return type:

bool

_match_centerlines_multiproc(dmax: float, distance_weight: float, vel_perturb_weight: float, curvature_weight: float, window: int, pattern: str, nb_procs: int) → bool

Private method to compute centerline matching using multiprocessing.

Parameters:

  • dmax (float) – Maximal allowed distance (m) between connected channel point.

  • distance_weight (float) – Weight [0, 1] on channel point distance.

  • vel_perturb_weight (float) – Weight [0, 1] on velocity perturbation.

  • curvature_weight (float) – Weight [0, 1] on curvature.

  • window (int) – Number of points for smoothing filter.

  • pattern (str) – Pattern input of dtw.dtw function.

  • nb_procs (int) – number of processors.

Returns:

True if calculation successfully ended.

Return type:

bool

_set_cl_pts_indexes_in_prev_next_centerlines(key: int, prev_key: int, indexes: list[int], dmax: float) → None

Store the results if centerline matching in each Centerline object.

The method create the lists index_cl_pts_prev_centerline and index_cl_pts_next_centerline of each Centerline object and also upate ChannelPoint cl_pt_index_prev and cl_pt_index_next members.

Parameters:

  • key (float) – Age of the first matched centerline.

  • prev_key (float) – Age of the second matched centerline.

  • indexes (list[int]) – List of channel point indexes in the Centerline of age prev_key.

  • dmax (float) – Maximal allowed distance (m) between connected channel points.

_smooth_bend_apex_trajec() → None

Smooth apex trajectory of all bend evolutions.

_smooth_bend_centroid_trajec(bend_evol_index: int) → list[ndarray[tuple[Any, ...], dtype[float64]]]
_smooth_bend_middle_trajec(bend_evol_index: int) → list[ndarray[tuple[Any, ...], dtype[float64]]]
_update_bend_evolution(to_treat: set[int], bend_uids: list[int], bend_evol: list[int]) → None

Collect Bend indexes of connected bends.

The method works recursively from the lists Bend.bend_uid_next and Bend.bend_uid_prev.

Parameters:

  • to_treat (set[int]) – List of remaining Bend uid to treat.

  • bend_uids (list[int]) – List of all remaining Bend uid to treat.

  • bend_evol (list[int]) – List of Bend uid that belongs to a same BendEvolution.

connect_bends(bend_evol_validity: int = 2, method: BendConnectionMethod = BendConnectionMethod.APEX, dmax: float = inf, weighting_func_type: str = 'uniform') → bool

Pulic method to create BendEvolution objects by connecting bends.

Parameters:

  • bend_evol_validity (int, optional) – Minimum number of bends in the BendEvolution to be considered as valid. Defaults to 2.

  • method (Bend_connection_method, optional) – Method to use to compute BendEvolution. Defaults to Bend_connection_method.MATCHING.

  • dmax (float, optional) – Maximum allowed distance (m) between 2 successive apex points. Defaults to np.inf.

  • weighting_func_type (str, optional) – Weighting function type to use. Defaults to “uniform”.

Returns:

True if the function ends witout errors

Return type:

bool

create_section_lines(point_name: CreateSectionMethod = CreateSectionMethod.MIDDLE) → None

Automatically create section lines across BendEvolution objects.

Section lines are created

Parameters:

point_name (CreateSectionMethod, optional) – Name of the point to use to create the section. Defaults to CreateSectionMethod.MIDDLE.

Raises:

TypeError – in case of wrong method

find_all_bend_apex(n: float, smooth_trajectory: bool = False) → None

Find the apex of all bends of the CenterlineCollection.

Parameters:

  • n (float) – exponent of the curvature distribution function.

  • smooth_trajectory (bool, optional) – If True, middle trajectory through BendEvolution is smoothed and stored in the list BendEvolution.middle_trajec_smooth. Defaults to False.

find_all_bend_apex_user_weights(apex_proba_weights: tuple[float, float, float], smooth_trajectory: bool = False) → None

Find the apex of all bends of the CenterlineCollection.

Parameters:

  • apex_proba_weights (tuple[float, float, float]) – Weights for apex probability calculation. Apex probability depends on channel point curvature, bend amplitude (m), and the distance from inflection points.

  • smooth_trajectory (bool, optional) – If True, middle trajectory through BendEvolution is smoothed and stored in the list BendEvolution.middle_trajec_smooth. Defaults to False.

find_all_bend_centroid(smooth_trajectory: bool = False) → None

Compute the centroid point of each bend of the CenterlineCollection.

Parameters:

smooth_trajectory (bool, optional) – If True, centroid trajectory through BendEvolution is smoothed and stored in the list BendEvolution.centroid_trajec_smooth. Defaults to False.

find_all_bend_middle(smooth_trajectory: bool = False) → None

Compute the middle points of all bends of the CenterlineCollection.

Parameters:

smooth_trajectory (bool, optional) – If True, middle trajectory through BendEvolution is smoothed and stored in the list BendEvolution.middle_trajec_smooth. Defaults to False.

find_points_on_sections(thres: int = 1, flow_dir: ndarray[tuple[Any, ...], dtype[float64]] = array([1., 0.]), cl_collec_id: int = 0) → bool

Collect channels that are intersected by sections.

This method create the Section objects with intersected channel geometry and store them in the list self.sections.

Parameters:

  • thres (int, optional) – Minimum number of intersected lines to create the Section object. Defaults to 1.

  • flow_dir (NDArray[float], optional) – Direction vector of the flow used to orientate the Sections. Defaults to np.array([1,0]).

  • cl_collec_id (int, optional) – CenterlineCollection id used in the Section id. Defaults to 0.

Returns:

True if calculation successfully ended.

Return type:

bool

get_all_ages() → ndarray[tuple[Any, ...], dtype[int64]]

Get all centerline ages stored in the CenterlineCollection.

Returns:

Array of centerline ages sorted in ascending order.

Return type:

NDArray[int]

get_bend_evol_side(bend_evol_index: int) → BendSide

Get BendEvolution side.

BendEvolution side is the most frequent side of its constitutive bends.

Parameters:

bend_evol_index (int) – BendEvolution index.

Returns:

BendEvolution side.

Return type:

BendSide

get_centerline_property(age: int, property_name: str) → ndarray[tuple[Any, ...], dtype[float64]]

Get a property of input centerline channel points.

Agrs:

age (int): Age of the Centerline. property_name (str): Name of the property.

Returns:

Array containing the values of the property for each channel point.

Return type:

NDArray[float]

get_nb_bends_evol() → int

Get the number of BendEvolution stored in self.bends_evol list.

Returns:

Number of BendEvolution.

Return type:

int

get_nb_valid_bends_evol() → int

Get the number of valid BendEvolution stored in bends_evol list.

Returns:

Number of valid BendEvolution.

Return type:

int

get_valid_bends_evol_id() → list[int]

Get the ids of valid BendEvolution stored in self.bends_evol list.

Returns:

Ids of valid BendEvolution.

Return type:

list[int]

initialize_monoproc(map_centerline_data: dict[int, DataFrame], spacing: float, smooth_distance: float, use_fix_nb_points: bool, curvature_filtering_window: int, sinuo_thres: float, n: float, compute_curvature: bool, interpol_props: bool, find_bends: bool) → bool

Initialize Centerline_evoution object using monoprocessing.

Parameters:

  • map_centerline_data (dict[int, pd.DataFrame]) – dictionnary containing for each age a dataframe containing centerline data

  • spacing (float) – Target distance (m) between two consecutive channel points after resampling, or number of points if use_fix_nb_points is True

  • smooth_distance (float) – smoothing distance for channel point location and curvature

  • use_fix_nb_points (bool) – if True, spacing is the number of points of the resampled centerline, otherwise it is the target distance.

  • curvature_filtering_window (int) – Number of points to consider for curvature smoothing window.

  • sinuo_thres (float) – threshold above which bends are valid.

  • n (float) – exponent of the curvature distribution function.

  • compute_curvature (bool) – if True, recompute channel point curvature after resampling.

  • interpol_props (bool) – if True, interpolate channel point properties along channel points after resampling.

  • find_bends (bool) – if True, automatically compute curvature and interpolate properties and detect bends along each centerline

Returns:

True if calculation successfully eneded.

Return type:

bool

initialize_multiproc(map_centerline_data: dict[int, DataFrame], spacing: float, smooth_distance: float, use_fix_nb_points: bool, curvature_filtering_window: int, sinuo_thres: float, n: float, compute_curvature: bool, interpol_props: bool, find_bends: bool) → bool

Initialize Centerline_evoution object using multiprocessing.

Parameters:

  • map_centerline_data (dict[int, pd.DataFrame]) – dictionnary containing for each age a dataframe containing centerline data

  • spacing (float) – Target distance (m) between two consecutive channel points after resampling, or number of points if use_fix_nb_points is True

  • smooth_distance (float) – smoothing distance for channel point location and curvature

  • use_fix_nb_points (bool) – if True, spacing is the number of points of the resampled centerline, otherwise it is the target distance.

  • curvature_filtering_window (int) – Number of points to consider for curvature smoothing window.

  • sinuo_thres (float) – threshold above which bends are valid.

  • n (float) – exponent of the curvature distribution function.

  • compute_curvature (bool) – if True, recompute channel point curvature after resampling.

  • interpol_props (bool) – if True, interpolate channel point properties along channel points after resampling.

  • find_bends (bool) – if True, automatically compute curvature and interpolate properties and detect bends along each centerline

Returns:

True if calculation successfully eneded.

Return type:

bool

match_centerlines(dmax: float = inf, distance_weight: float = 0.0, vel_perturb_weight: float = 0.0, curvature_weight: float = 1.0, window: int = 5, pattern: str = 'asymmetric') → None

Public method to compute centerline matching.

Centerline matching consists in applying Dynamic Time Warping on each pair of consecutive Centerline to connect channel points together.

Parameters:

  • dmax (float, optional) – Maximal allowed distance (m) between connected channel point. Defaults to np.inf.

  • distance_weight (float, optional) – Weight [0, 1] on channel point distance. Defaults to 0.

  • vel_perturb_weight (float, optional) – Weight [0, 1] on velocity perturbation. Defaults to 0.

  • curvature_weight (float, optional) – Weight [0, 1] on curvature. Defaults to 1.

  • window (int, optional) – Number of points for filter. Defaults to 5.

  • pattern (str, optional) – Pattern input of dtw.dtw function. Defaults to “asymmetric”.

set_centerline_constant_properties(age: int, property_map: dict[str, float]) → None

Set properties with constant value to the centerline of input age.

Parameters:

  • age (float) – Age of the Centerline.

  • property_map (dict[str, float]) – Dictionnary containings property names as keys and property values as values.

set_centerline_properties(age: int, property_map: dict[str, ndarray[tuple[Any, ...], dtype[float64]]]) → None

Set properties values to the centerline of input age.

Parameters:

  • age (float) – Age of the Centerline.

  • property_map (dict[str, NDArray[float]]) – Dictionnary containings property names as keys and array of property values as values.

set_section_lines(pts_start: list[tuple[float, float]], pts_end: list[tuple[float, float]]) → None

Manually set section lines across CenterlineCollection.

Parameters:

  • pts_start (list[tuple[float, float]]) – List of 2D coordinates of section starting points.

  • pts_end – list[tuple[float, float]]): List of 2D coordinates of section ending points.

_centerline_matching_computed: bool

True if centerline matching was computed

apparent_kinematics_computed: bool

True if apparent kinematics were computed

bends_evol: list[BendEvolution]

list of BendEvolution objects

bends_tracking_computed: bool

True if bend tracking was computed

centerlines: dict[int, Centerline]

dictionnary to store Centerline object at each age

real_kinematics_computed: bool

True if real kinematics were computed

section_lines: list[LineString]

list of section lines

sections_computed: bool

True if sections lines were defined

pybend.model.ClPoint module

Centerline point model.

Defines ClPoint, a single point along a channel centerline with coordinates and associated properties.

Let’s consider a channel centerline discretized into successive channel points. This module defines channel point object that stores channel point properties. These properties include channel point cartesian and curvilinear coordinates, channel geometry (width, mean and maximal depth, curvature, etc.), and flow properties (velocity, velocity perturbation, etc.).

       .                         .                        .
    .     .                    .    .                   .    .
  .         .                .        .               .        .
 .           .              .          .             .          .
.             .            .            .           .            .
               .          .              .         .
                .        .                .       .
                  .    .                    .   .
                     .                        .

Sinuous channel centerline discretized into a series avec channel points (.).

To use it:

..code-block:: python

ide :int age :int data :pd.Series clPt :ClPoint = ClPoint(ide, age, data)

class pybend.model.ClPoint.ClPoint(ide: str, age: int, dataset: Series)

Bases: object

A single point along a Centerline with stored properties.

Centerline point stores coordinates and associated variables.

Channel point coordinates must be present in the dataset.

Parameters:

  • ide (str) – channel point id

  • age (int) – channel point age

  • dataset (pd.Series) – data associated to the channel point

curvature() → float

Get channel point curvature property.

Returns:

curvature

Return type:

float

curvature_filtered() → float

Get channel point filtered curvature property.

Returns:

smoothed curvature

Return type:

float

depth_max() → float

Get channel point mean depth property.

Returns:

mean depth

Return type:

float

depth_mean() → float

Get channel point mean depth property.

Returns:

mean depth

Return type:

float

get_data() → Series

Get the channel poitn properties.

Returns:

channel poitn properties

Return type:

pd.Series

get_property(name: str) → float

Get channel point property from input name.

Parameters:

name (str) – name of the property

Returns:

property values if it exists, or np.nan otherwise

Return type:

float

set_curvature(curv: float) → None

Set channel point curvature property.

Parameters:

curv (float) – curvature

set_property(name: str, value: float) → None

Set property value.

Parameters:

  • name (str) – name of the property to set

  • value (float) – value of the property to set

velocity() → float

Get channel point velocity property.

Returns:

velocity

Return type:

float

velocity_perturbation() → float

Get channel point velocity perturbation property.

Returns:

velocity perturbation

Return type:

float

width() → float

Get channel point width property.

Returns:

width

Return type:

float

_age: int

channel point age

_data: Series

channel point data (curvature, height, velocity, etc.)

_id: str

Channel point id

cl_pt_index_next: list[int]

list of channel point index in the centerline at next time step

cl_pt_index_prev: list[int]

list of channel point index in the centerline at previous time step

pt: ndarray[tuple[Any, ...], dtype[float64]]

channel point cartesian coordinates

pybend.model.Isoline module

Isoline models.

Defines Isoline and derived types such as channel cross-sections. Children objects specified the type IsolineType and the geometry from parametric function.

An Isoline object corresponds to a line defined by an isovalue (such as the age). ChannelCrossSection object allows to represent channel section geometry from a reference point and a paramteric shape.

class pybend.model.Isoline.ChannelCrossSection(age: int, cl_pt_ref: ClPoint)

Bases: Isoline

A channel cross-section isoline derived from a reference ClPoint.

Isoline for channel cross-section.

Parameters:

  • age (int) – age of the points

  • cl_pt_ref (npt.NDArray[np.float64]) – reference ClPoint

complete_channel_shape(nb_pts: int = 11) → None

Create channel cross-section assuming parabolic shape.

Parameters:

nb_pts (int, optional) – Number of points. Defaults to 11.

class pybend.model.Isoline.Isoline(age: int, cl_pt_ref: ClPoint, isoline_type: IsolineType)

Bases: object

A polyline associated with a constant isovalue (e.g., age).

Store points of the same age (for instance channel cross-section).

Parameters:

  • age (int) – age of the points

  • cl_pt_ref (ClPoint) – reference ClPoint

  • isoline_type (str) – isoline type (currently only ‘Channel’)

points: ndarray[tuple[Any, ...], dtype[float64]]

point coordinates according to cl_pt_ref

class pybend.model.Isoline.IsolineType(*values)

Bases: Enum

Types of isoline.

CHANNEL = 'Channel'

channel cross-section

UNKNOWN = 'Unknown'

undefined

pybend.model.Morphometry module

Bend morphometry computations.

Bends are defined as the channel path comprised between 2 consecutive inflection points (o). A Bend contains a maximum curvature point (+) and an apex (x) whose definition may vary.

Metrics include:

  • arc length: curvilinear distance between inflection points

  • wavelength (W): euclidean distance between inflection points

  • amplitude (Am): orthogonal distance between bend apex and chord

  • extension (Ex): distance between bend apex and center

  • asymmetry coefficient: A=(Lup-Ldown) / L, where Lup and Ldown are arc length distances between bend apex and upstream and downstream inflection point respectively, and L is the bend arc length.

  • radius of curvature: inverse of bend apex curvature

  • roundess: ratio of maximum to mean curvature along the bend

                             .   x  .
                         .      /|    .
                      .        / |     +
    Flow            .      Ex /  | Am  .
    -->            .         /   |    .
Direction         .         /    |   .
                 o --------c------- o
                 <---------------->
                        W

To use it:

centerline :Centerline
morphComputer :Morphometry = Morphometry(centerline)
metrics :pd.DataFrame = morphComputer.compute_bend_morphometry()
class pybend.model.Morphometry.Morphometry(centerline: Centerline)

Bases: object

Compute morphometric parameters from a Centerline.

Class to compute morphometric parameters from Centerline object.

Parameters:

centerline (Centerline) – Centerline object

_get_window_end_indexes(bend_index: int, window_size: float) → tuple[int, int]

Compute the indexes of first and last bends included in the window.

Parameters:

  • bend_index (int) – current bend index

  • window_size (float) – curvilinear length of the window [m].

Returns:

indexes of first and last bends of the window.

Return type:

tuple[int, int]

compute_average_metric_window(bend_id: int, window_size: float) → Series

Compute average morphometrics inside a moving window.

Parameters:

  • bend_id (int) – bend index

  • window_size (float) – curvulinear length of the window [m].

Returns:

Series containing average values of all metrics.

Return type:

pd.Series

compute_bend_amplitude(bend_id: int) → float

Compute bend amplitude.

Parameters:

bend_id (int) – bend index

Returns:

bend amplitude

Return type:

float

compute_bend_amplitude_leopold(bend_id: int) → float

Compute bend ampltiude according to Leopold method.

Leopold method is described in Leopold and Wolman (1957)

Parameters:

bend_id (int) – bend index.

Returns:

Leopold amplitude.

Return type:

float

compute_bend_arc_length(bend_id: int) → float

Compute bend arc length.

Parameters:

bend_id (int) – bend index

Returns:

bend arc length

Return type:

float

compute_bend_asymmetry(bend_id: int) → float

Compute bend asymmetry coefficient.

Asymmetry coefficient from Howard and Hemberger (1991)

Parameters:

bend_id (int) – bend index

Returns:

bend asymmetry coefficient

Return type:

float

compute_bend_extension(bend_id: int) → float

Compute bend extension.

Parameters:

bend_id (int) – bend index

Returns:

bend extension

Return type:

float

compute_bend_radius(bend_id: int) → float

Compute bend radius.

Parameters:

bend_id (int) – bend index

Returns:

bend radius

Return type:

float

compute_bend_roundness(bend_id: int) → float

Compute bend roundness.

Roundness coefficient from Schwenk et al. (2015)

Parameters:

bend_id (int) – bend index

Returns:

bend roundness

Return type:

float

compute_bend_sinuosity(bend_id: int) → float

Compute bend sinuosity.

Parameters:

bend_id (int) – bend index

Returns:

bend sinuosity

Return type:

float

compute_bend_sinuosity_moving_window(bend_id: int, window_size: float) → float

Compute bend sinuosity inside a moving window.

Parameters:

  • bend_id (int) – bend index

  • window_size (float) – curvulinear length of the window [m].

Returns:

sinuosity over the window.

Return type:

float

compute_bend_skewness(bend_id: int) → float

Compute bend skewness coefficient.

Skewness coefficient corresponds to the Pearson’s skewness coefficient of the curvature satial distribution.

Parameters:

bend_id (int) – bend index

Returns:

bend skewness coefficient

Return type:

float

compute_bend_wavelength(bend_id: int) → float

Compute bend wavelength.

Parameters:

bend_id (int) – bend index

Returns:

bend wavelength

Return type:

float

compute_bend_wavelength_leopold(bend_id: int) → float

Compute bend wavelength according to Leopold method.

Leopold method is described in Leopold and Wolman (1957)

Parameters:

bend_id (int) – bend index.

Returns:

Leopold wavelength.

Return type:

float

compute_bends_morphometry(valid_bends: bool = True) → DataFrame

Compute all bend morphometric parameters.

Parameters:

valid_bends (bool) – if True, compute morphometry on valid bends only Defaults to True.

Returns:

dataframe with morphometric measurements.

Return type:

pd.DataFrame

pybend.model.Section module

Stratigraphic section model.

The stratigraphic architecture is characterized by the stacking pattern. Stacking pattern types are defined from StackingPatternType enumeration.

Warning

this class is under construction…

class pybend.model.Section.Section(ide: str, bend_id: str, pt_start: ndarray[tuple[Any, ...], dtype[float64]], pt_stop: ndarray[tuple[Any, ...], dtype[float64]], isolines: list[Isoline], same_bend: list[bool] | None = None, flow_dir: ndarray[tuple[Any, ...], dtype[float64]] = array([1, 0]))

Bases: object

A 2D stratigraphic section composed of multiple isolines.

Object to store 2D stratigraphy composed of multiple Isolines.

..WARNING: Code implementation in progress…

Parameters:

  • ide (str) – section id

  • bend_id (str) – bend id crossed by the section

  • pt_start (npt.NDArray[np.float64]) – start point coordinates

  • pt_stop (npt.NDArray[np.float64]) – end point coordinates

  • isolines (list[Isoline]) – list of Isoline objects

  • same_bend (Optional[list[bool]], optional) – list of boolean, True if isoline at the same index belongs to the same BendEvolution object as the first one. Defaults to None.

  • flow_dir (npt.NDArray[np.float64], optional) – flow directin to orientate the section. Defaults to np.array([1, 0]).

_compute_average_disp(width: float, depth: float, whole_trajec: bool) → ndarray[tuple[Any, ...], dtype[float64]]

Compute section-averaged channel displacement metrics.

Metrics include (see Jobe et al., 2016):

  • Dx: lateral displacement

  • Dy: vertical displacement

  • Bcb: channel belt with

  • Hcb: channel belt thickness

  • Bcb_norm: normalized channel belt with

  • Hcb_norm: normalized channel belt thickness

  • Bcb_on_Hcb: channel belt aspect ratio

  • Msb: Stratigraphic Mobility number

Parameters:

  • width (float) – channel width (m)

  • depth (float) – channel depth (m)

  • whole_trajec (bool) – if True, compute channel displacements from first to last channel of the isoline, otherwise from first to last channel of the last migration phase.

Returns:

Averaged displacement metrics including in order: Dx, Dz, Bcb, Hcb, Bcb_norm, Hcb_norm, Bcb_on_Hcb, Msb

Return type:

npt.NDArray[np.float64]

_compute_origin(flow_dir: ndarray[tuple[Any, ...], dtype[float64]] = array([1, 0])) → list[tuple[float, float]]

Compute Isoline coordinates along the section from reference point.

Parameters:

flow_dir (npt.NDArray[np.float64], optional) – Flow direction. Defaults to np.array([1, 0]).

Returns:

isoline coordinates along the section

Return type:

list[tuple[float, float]]

channel_apparent_displacements(norm_hor: float = 1, norm_vert: float = 1, smooth: bool = False) → None

Compute channel apparent displacements along the section.

Parameters:

  • norm_hor (float, optional) – Normalisation value for horizontal dimension. Defaults to 1.

  • norm_vert (float, optional) – Normalisation value for vertical dimension. Defaults to 1.

  • smooth (bool, optional) – if True, channel apparent trajectory is smoothed. Defaults to False.

get_stacking_pattern_type(mig_threshold: float, frac_threshold: float = 0.95, begin_threshold: float = 0.1) → StackingPatternType

Get the channel stacking pattern of isolines on the section.

Parameters:

  • mig_threshold (float) – lateral migration threshold (m)

  • frac_threshold (float, optional) – fraction of the total number of isolines. Defaults to 0.95.

  • begin_threshold (float, optional) – fraction of the total number of isolines. Defaults to 0.1.

Returns:

Stacking pattern type

Return type:

StackingPatternType

section_averaged_channel_displacements(norm_hor: float = 1.0, norm_vert: float = 1.0, write_results: bool = False, filepath: str = '') → None

Compute section-averaged channel displacement.

Parameters:

  • norm_hor (float, optional) – Normalisation value for horizontal dimension. Defaults to 1.

  • norm_vert (float, optional) – Normalisation value for vertical dimension. Defaults to 1

  • write_results (bool, optional) – if True, write results in a file. Defaults to False.

  • filepath (str, optional) – Full name of the file to export the results. Defaults to “”.

averaged_disp: dict[str, ndarray[tuple[Any, ...], dtype[float64]]]

list of average displacements between first and last isolines

bend_id: str

reference bend id

dir: ndarray[tuple[Any, ...], dtype[float64]]

section direction

id: str

section id

isolines: list[Isoline]

list of isolines

isolines_origin: list[tuple[float, float]]

list of isoline origin coordinates from 1st isoline of the list

local_disp: ndarray[tuple[Any, ...], dtype[float64]]

list of displacements betweeen each pair of successive isolines

pt_start: ndarray[tuple[Any, ...], dtype[float64]]

section start point coordinates

pt_stop: ndarray[tuple[Any, ...], dtype[float64]]

section end point coordinates

same_bend: list[bool] | None

list of boolean, True if isoline at the same index belongs to the same BendEvolution object as the last one.

stacking_pattern_type: StackingPatternType

stacking pattern type

class pybend.model.Section.StackingPatternType(*values)

Bases: Enum

Channel stacking pattern type.

Let’s suppose a section across a meander bend. The channel moves laterally and vertically through time. According to channel basal point trajectory, 4 stacking pattern types are defined (see Lemay et al., 2024):

Aggradation only    |   One Way      | Aggradation then One Way |    Two Ways   |  Multiple Ways

    :                            .                    .           .                  .
    :                           .                 .                   .                 .
    :                        .                 .                        :                 :
    :                     .                  .                        .                .
    :                  .                     :                      .                 :
    :                .                       :                    .                       .

Channel Stacking pattern types. Each point represents the position of the channel basal point. ‘:’ stands for aggradation phase.

AGGRADATION = 'Aggradation Only'

pure aggradation

AGGRAD_ONE_WAY = 'Aggradation Then One Way'

Aggradation then 1 way migration

MULTIPLE_WAYS = 'Multiple Ways'

multiple ways migration

ONE_WAY = 'One Way'

one way migration

TWO_WAYS = 'Two Way'

two ways migration

UNDEFINED = 'Undefined'

undefined

pybend.model.enumerations module

Enumerations used throughout pybend.

class pybend.model.enumerations.AmplitudeType(*values)

Bases: StrEnum

Method to compute amplitude.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

MIDDLE = 'Middle'

use the distance between the given point and bend center.

ORTHOGONAL = 'Orthogonal'

use the orthogonal distance between the given point and bend chord.

class pybend.model.enumerations.BendConnectionMethod(*values)

Bases: StrEnum

Enumeration defining bend connection method.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

APEX = 'From Apex'

same side and shortest distance between apexes.

Type:

Connected bends

CENTROID = 'From Centroid'

same side and shortest distance between centroids.

Type:

Connected bends

MATCHING = 'From Matching'

greatest number of cnnected channel points.

Type:

Connected bends

class pybend.model.enumerations.BendSide(*values)

Bases: StrEnum

Enum for bend side.

Bend is UP if curvature is positive and is DOWN if curvature is negative.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

DOWN = 'down'

negative curvature bend

UNKNWON = 'unknown'

undefined side

UP = 'up'

positive curvature bend

class pybend.model.enumerations.CreateSectionMethod(*values)

Bases: StrEnum

Enumeration of methods to use to automatically create cross-sections.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

APEX = 'From neighboring apex'

Section goes by the apex point of the last bend of BendEvolution

CENTROID = 'From centroid'

Section goes by the centroid point of the last bend of BendEvolution

MIDDLE = 'From middle'

Section goes by the middle point of the last bend of BendEvolution

class pybend.model.enumerations.FilterName(*values)

Bases: StrEnum

Enumeration for filter names.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

SAVITSKY = 'Savitsky-Golay filter'

Savitsky-Golay filter

UNIFORM = 'Uniform filter'

Uniform filter

class pybend.model.enumerations.MorphometricNames(*values)

Bases: StrEnum

Enumeration for morphometric names.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

AMPLITUDE = 'Amplitude'
AMPLITUDE_LEOPOLD = 'Amplitude_Leopold'
ARC_LENGTH = 'Arc_length'
ASYMMETRY = 'Asymmetry'
EXTENSION = 'Extension'
RADIUS_CURVATURE = 'RadiusCurvature'
ROUNDNESS = 'Roundness'
SINUOSITY = 'Sinuosity'
SKEWNESS = 'Skewness'
WAVELENGTH = 'Wavelength'
WAVELENGTH_LEOPOLD = 'Wavelength_Leopold'
class pybend.model.enumerations.PropertyNames(*values)

Bases: StrEnum

Enumeration of usual ChannelPoint property names.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

AGE = 'Age'
APEX_PROBABILITY = 'Apex_probability'
CARTESIAN_ABSCISSA = 'Cart_abscissa'
CARTESIAN_ORDINATE = 'Cart_ordinate'
CURVATURE = 'Curvature'
CURVATURE_FILTERED = 'Curvature_filtered'
CURVILINEAR_ABSCISSA = 'Curv_abscissa'
DEPTH_MAX = 'Max_depth'
DEPTH_MEAN = 'Mean_depth'
ELEVATION = 'Elevation'
NORMAL_X = 'Normal_x'
NORMAL_Y = 'Normal_y'
VELOCITY = 'Velocity'
VELOCITY_PERTURBATION = 'Vel_perturb'
WIDTH = 'Width'