fractopo.tval.trace_validators module

Contains Validator classes which each have their own error to handle and mark.

class fractopo.tval.trace_validators.BaseValidator

Bases: object

Base validator that all classes inherit.

TODO: Validation requires overhaul at some point.

ERROR = 'BASE ERROR'

INTERACTION_NODES_COLUMN = 'IP'

LINESTRING_ONLY = True

static fix_method(**_) → LineString | None

Abstract fix method.

static validation_method(**_) → bool

Abstract validation method.

class fractopo.tval.trace_validators.EmptyTargetAreaValidator

Bases: BaseValidator

Stub validator for empty target area.

Validation for this error occurs at the start of run_validation.

ERROR = 'EMPTY TARGET AREA'

class fractopo.tval.trace_validators.GeomNullValidator

Bases: BaseValidator

Validate the geometry for NULL GEOMETRY errors.

ERROR = 'NULL GEOMETRY'

LINESTRING_ONLY = False

static validation_method(geom: Any, **_) → bool

Validate for empty and null geometries.

E.g. some validations are handled by GeomTypeValidator

>>> GeomNullValidator.validation_method(Point(1, 1))
True

Empty geometries are not valid.

>>> GeomNullValidator.validation_method(LineString())
False

>>> GeomNullValidator.validation_method(LineString([(-1, 1), (1, 1)]))
True

class fractopo.tval.trace_validators.GeomTypeValidator

Bases: BaseValidator

Validates the geometry type.

Validates that all traces are LineStrings. Tries to use shapely.ops.linemerge to merge MultiLineStrings into LineStrings.

ERROR = 'GEOM TYPE MULTILINESTRING'

LINESTRING_ONLY = False

static fix_method(geom: Any, **_) → LineString | None

Fix mergeable MultiLineStrings to LineStrings.

E.g. mergeable MultiLineString

>>> mls = MultiLineString([((0, 0), (1, 1)), ((1, 1), (2, 2))])
>>> GeomTypeValidator.fix_method(geom=mls).wkt
'LINESTRING (0 0, 1 1, 2 2)'

Unhandled types will just return as None.

>>> GeomTypeValidator.fix_method(geom=Point(1, 1)) is None
True

static validation_method(geom: Any, **_) → bool

Validate geometries.

E.g. Anything but LineString

>>> GeomTypeValidator.validation_method(Point(1, 1))
False

With LineString:

>>> GeomTypeValidator.validation_method(LineString([(0, 0), (1, 1)]))
True

class fractopo.tval.trace_validators.MultiJunctionValidator

Bases: BaseValidator

Validates that junctions consists of a maximum of two lines crossing.

ERROR = 'MULTI JUNCTION'

static determine_faulty_junctions(all_nodes: list[tuple[Point, ...]], snap_threshold: float | int | Real, snap_threshold_error_multiplier: float | int | Real) → set[int]

Determine when a point of interest represents a multi junction.

I.e. when there are more than 2 points within the buffer distance of each other.

Two points is the limit because an intersection point between two traces is added to the list of interest points twice, once for each trace.

Faulty junction can also represent a slightly overlapping trace i.e. a snapping error.

>>> all_nodes = [
...     (Point(0, 0), Point(1, 1)),
...     (Point(1, 1),),
...     (Point(5, 5),),
...     (Point(0, 0), Point(1, 1)),
... ]
>>> snap_threshold = 0.01
>>> snap_threshold_error_multiplier = 1.1
>>> MultiJunctionValidator.determine_faulty_junctions(
...     all_nodes, snap_threshold, snap_threshold_error_multiplier
... )
{0, 1, 3}

static validation_method(idx: int, faulty_junctions: set[int], **_) → bool

Validate for multi junctions between traces.

>>> MultiJunctionValidator.validation_method(
...     idx=1, faulty_junctions=set([1, 2])
... )
False

class fractopo.tval.trace_validators.MultipleCrosscutValidator

Bases: BaseValidator

Find traces that cross-cut each other multiple times.

This also indicates the possibility of duplicate traces.

ERROR = 'MULTIPLE CROSSCUTS'

static validation_method(geom: LineString, trace_candidates: GeoSeries, **_) → bool

Validate for multiple crosscuts.

>>> geom = LineString([Point(-3, -4), Point(-3, -1)])
>>> trace_candidates = gpd.GeoSeries(
...     [
...         LineString(
...             [Point(-4, -3), Point(-2, -3), Point(-4, -2), Point(-2, -1)]
...         )
...     ]
... )
>>> MultipleCrosscutValidator.validation_method(geom, trace_candidates)
False

>>> geom = LineString([Point(-3, -4), Point(-3, -4.5)])
>>> trace_candidates = gpd.GeoSeries(
...     [
...         LineString(
...             [Point(-4, -3), Point(-2, -3), Point(-4, -2), Point(-2, -1)]
...         )
...     ]
... )
>>> MultipleCrosscutValidator.validation_method(geom, trace_candidates)
True

class fractopo.tval.trace_validators.SharpCornerValidator

Bases: BaseValidator

Find sharp cornered traces.

ERROR = 'SHARP TURNS'

static validation_method(geom: LineString, sharp_avg_threshold: float | int | Real, sharp_prev_seg_threshold: float | int | Real, **_) → bool

Validate for sharp cornered traces.

class fractopo.tval.trace_validators.SimpleGeometryValidator

Bases: BaseValidator

Use shapely is_simple and is_ring attributes to validate LineString.

Checks that trace does not cut itself.

ERROR = 'CUTS ITSELF'

static validation_method(geom: LineString, **_) → bool

Validate for self-intersections.

class fractopo.tval.trace_validators.StackedTracesValidator

Bases: BaseValidator

Find stacked traces and small triangle intersections.

ERROR = 'STACKED TRACES'

static validation_method(geom: LineString, trace_candidates: GeoSeries, snap_threshold: float | int | Real, snap_threshold_error_multiplier: float | int | Real, overlap_detection_multiplier: float | int | Real, triangle_error_snap_multiplier: float | int | Real, stacked_detector_buffer_multiplier: float | int | Real, **_) → bool

Validate for stacked traces and small triangle intersections.

>>> geom = LineString([(0, 0), (0, 1)])
>>> trace_candidates = gpd.GeoSeries([LineString([(0, -1), (0, 2)])])
>>> snap_threshold = 0.01
>>> snap_threshold_error_multiplier = 1.1
>>> overlap_detection_multiplier = 50
>>> triangle_error_snap_multiplier = 10
>>> stacked_detector_buffer_multiplier = 5
>>> StackedTracesValidator.validation_method(
...     geom,
...     trace_candidates,
...     snap_threshold,
...     snap_threshold_error_multiplier,
...     overlap_detection_multiplier,
...     triangle_error_snap_multiplier,
...     stacked_detector_buffer_multiplier,
... )
False

>>> geom = LineString([(10, 0), (10, 1)])
>>> trace_candidates = gpd.GeoSeries([LineString([(0, -1), (0, 2)])])
>>> snap_threshold = 0.01
>>> snap_threshold_error_multiplier = 1.1
>>> overlap_detection_multiplier = 50
>>> triangle_error_snap_multiplier = 10
>>> stacked_detector_buffer_multiplier = 10
>>> StackedTracesValidator.validation_method(
...     geom,
...     trace_candidates,
...     snap_threshold,
...     snap_threshold_error_multiplier,
...     overlap_detection_multiplier,
...     triangle_error_snap_multiplier,
...     stacked_detector_buffer_multiplier,
... )
True

class fractopo.tval.trace_validators.TargetAreaSnapValidator

Bases: BaseValidator

Validator for traces that underlap the target area.

ERROR = 'TRACE UNDERLAPS TARGET AREA'

static is_candidate_underlapping(endpoint: Point, geom: LineString, area_polygon: Polygon | MultiPolygon, snap_threshold: float | int | Real) → bool

Determine if endpoint is candidate for Underlapping error.

static simple_underlapping_checks(endpoint: Point, geom: LineString, area_polygon: Polygon | MultiPolygon, snap_threshold: float | int | Real) → bool | None

Perform simple underlapping checks.

static validation_method(geom: LineString, area: GeoDataFrame | GeoSeries, snap_threshold: float | int | Real, snap_threshold_error_multiplier: float | int | Real, area_edge_snap_multiplier: float | int | Real, **_) → bool

Validate for trace underlaps.

>>> geom = LineString([(0, 0), (0, 1)])
>>> area = gpd.GeoDataFrame(
...     geometry=[Polygon([(0, 0), (0, 1), (1, 1), (1, 0)])]
... )
>>> snap_threshold = 0.01
>>> snap_threshold_error_multiplier = 1.1
>>> area_edge_snap_multiplier = 1.0
>>> TargetAreaSnapValidator.validation_method(
...     geom,
...     area,
...     snap_threshold,
...     snap_threshold_error_multiplier,
...     area_edge_snap_multiplier,
... )
True

>>> geom = LineString([(0.5, 0.5), (0.5, 0.98)])
>>> area = gpd.GeoDataFrame(
...     geometry=[Polygon([(0, 0), (0, 1), (1, 1), (1, 0)])]
... )
>>> snap_threshold = 0.01
>>> snap_threshold_error_multiplier = 1.1
>>> area_edge_snap_multiplier = 10
>>> TargetAreaSnapValidator.validation_method(
...     geom,
...     area,
...     snap_threshold,
...     snap_threshold_error_multiplier,
...     area_edge_snap_multiplier,
... )
False

class fractopo.tval.trace_validators.UnderlappingSnapValidator

Bases: BaseValidator

Find snapping errors of underlapping traces.

Uses a multiple of the given snap_threshold.

ERROR = 'UNDERLAPPING SNAP'

classmethod validation_method(geom: LineString, trace_candidates: GeoSeries, snap_threshold: float | int | Real, snap_threshold_error_multiplier: float | int | Real, **_) → bool

Validate for UnderlappingSnapValidator errors.

>>> snap_threshold = 0.01
>>> snap_threshold_error_multiplier = 1.1
>>> geom = LineString(
...     [
...         (0, 0),
...         (0, 1 + snap_threshold * snap_threshold_error_multiplier * 0.99),
...     ]
... )
>>> trace_candidates = gpd.GeoSeries([LineString([(-1, 1), (1, 1)])])
>>> UnderlappingSnapValidator.validation_method(
...     geom, trace_candidates, snap_threshold, snap_threshold_error_multiplier
... )
False

>>> snap_threshold = 0.01
>>> snap_threshold_error_multiplier = 1.1
>>> geom = LineString([(0, 0), (0, 1)])
>>> trace_candidates = gpd.GeoSeries([LineString([(-1, 1), (1, 1)])])
>>> UnderlappingSnapValidator.validation_method(
...     geom, trace_candidates, snap_threshold, snap_threshold_error_multiplier
... )
True

class fractopo.tval.trace_validators.VNodeValidator

Bases: BaseValidator

Finds V-nodes within trace data.

ERROR = 'V NODE'

static determine_v_nodes(endpoint_nodes: list[tuple[Point, ...]], snap_threshold: float | int | Real, snap_threshold_error_multiplier: float | int | Real) → set[int]

Determine V-node errors.

>>> endpoint_nodes = [
...     (Point(0, 0), Point(1, 1)),
...     (Point(1, 1),),
... ]
>>> snap_threshold = 0.01
>>> snap_threshold_error_multiplier = 1.1
>>> VNodeValidator.determine_v_nodes(
...     endpoint_nodes, snap_threshold, snap_threshold_error_multiplier
... )
{0, 1}

static validation_method(idx: int, vnodes: set[int], **_) → bool

Validate for V-nodes.

>>> VNodeValidator.validation_method(idx=1, vnodes=set([1, 2]))
False

>>> VNodeValidator.validation_method(idx=5, vnodes=set([1, 2]))
True