resqpy.lines.Polyline

class resqpy.lines.Polyline(parent_model, uuid=None, set_bool=None, set_coord=None, set_crs=None, title=None, rep_int_root=None, originator=None, extra_metadata=None)

Bases: _BasePolyline

Class for RESQML polyline representation.

Public Data Attributes:

resqml_type

rep_int_uuid

Returns the uuid of the represented interpretation.

Inherited from BaseResqpy

resqml_type

part

Standard part name corresponding to self.uuid.

root

XML node corresponding to self.uuid.

citation_title

Citation block title equivalent to self.title.

Commonly Used Methods:

__init__(parent_model[, uuid, set_bool, ...])

Initialises a new PolylineRepresentation object.

point_is_inside_xy(p[, mode])

Returns True if point p is inside closed polygon, in xy plane, otherwise False.

points_are_inside_xy(p_array)

Returns bool array, True where p is inside closed polygon, in xy plane, otherwise False.

full_length([in_xy])

Returns the naive length of the entire polyline.

interpolated_point(fraction[, in_xy])

Returns x,y,z point on the polyline at fractional distance along entire polyline.

splined([tangent_weight, min_subdivisions, ...])

Retrurns a new Polyline being a cubic spline of this polyline.

create_xml([ext_uuid, add_as_part, ...])

Create xml from polyline.

write_hdf5([file_name, mode])

Create or append the coordinates hdf5 array to hdf5 file.

Methods:

from_scaled_polyline(original, scaling[, ...])

Returns a scaled version of the original polyline.

from_trimmed_polyline(original, start_seg, ...)

Returns a trimmed version of the original polyline.

for_regular_polygon(model, n, radius, ...)

`Returns a closed polyline representing a regular polygon in xy plane.

convex_hull_from_closed_polyline(original, title)

Returns a new closed convex polyline being the convex hull of an original closed polyline.

is_convex([trust_metadata])

Returns True if the polyline is closed and convex in the xy plane, otherwise False.

is_clockwise([trust_metadata])

Returns True if first non-straight triplet of nodes is clockwise in the xy plane; False if anti-clockwise.

segment_length(segment_index[, in_xy])

Returns the naive length (ie.

segment_midpoint(segment_index)

Returns the midpoint of an individual segment of the polyline.

segment_normal(segment_index)

For a closed polyline return a unit vector giving the 2D (xy) direction of an outward facing normal to a segment.

equidistant_points(n[, in_xy])

Returns array of shape (n, 3) being points equally distributed along entire polyline.

balanced_centre([mode, n, cache, in_xy])

Returns a mean x,y,z based on sampling polyline at regular intervals.

first_line_intersection(x1, y1, x2, y2[, ...])

Finds the first intersection of (half) bounded line x,y 1 to 2 with polyline.

closest_segment_and_distance_to_point_xy(p)

Returns the index of the closest segment to a point, and its distance, in the xy plane.

point_snapped_to_segment_xy(segment, p)

Returns the point on a specified segment, in xy plane, that is closest to a point.

xy_crossings(other)

Returns list of (x, y) pairs of crossing points with other polyline, in xy plane.

normalised_xy(x, y[, mode])

Returns a normalised x',y' pair (in range 0..1) being point x,y under mapping from convex polygon.

denormalised_xy(norm_x, norm_y[, mode])

Returns a denormalised x,y pair being point norm_x,norm_y (in range 0..1) under mapping onto convex polygon.

tangent_vectors()

Returns a numpy array of unit length tangent vectors, one for each coordinate in the line.

area()

Returns the area in the xy plane of a closed convex polygon.

Inherited from _BasePolyline

create_interpretation_and_feature([kind, ...])

Creates xml and objects for a represented interpretaion and interpreted feature, if not already present.

Inherited from BaseResqpy

__init__(parent_model[, uuid, set_bool, ...])

Initialises a new PolylineRepresentation object.

try_reuse()

Look for an equivalent existing RESQML object and modify the uuid of this object if found.

create_xml([ext_uuid, add_as_part, ...])

Create xml from polyline.

append_extra_metadata(meta_dict)

Append a given dictionary of metadata to the existing metadata.

__eq__(other)

Implements equals operator; uses is_equivalent() otherwise compares class type and uuid.

__ne__(other)

Implements not equal operator.

__repr__()

String representation.


__init__(parent_model, uuid=None, set_bool=None, set_coord=None, set_crs=None, title=None, rep_int_root=None, originator=None, extra_metadata=None)[source]

Initialises a new PolylineRepresentation object.

Parameters
  • parent_model (model.Model object) – the model which the new PolylineRepresentation belongs to

  • uuid (uuid.UUID, optional) – the uuid of an existing RESQML PolylineRepresentation from which to initialise the resqpy Polyline

  • set_bool (boolean, optional) – if True, a new polyline created from coordinates is flagged as a closed polyline (polygon); ignored if uuid is not None

  • set_coord (numpy array of shape (..., 3), optional) – an ordered set of xyz values used to define a new polyline; ignored if uuid is not None

  • set_crs (uuid.UUID, optional) – the uuid of a crs to be used when initialising from coordinates; ignored if uuid is not None

  • title (str, optional) – the citation title to use for a new polyline; ignored if uuid is not None

  • rep_int_root

  • originator (str, optional) – the name of the person creating the polyline, defaults to login id; ignored if uuid is not None

  • extra_metadata (dict, optional) – string key, value pairs to add as extra metadata for the polyline; ignored if uuid is not None

Returns

the newly instantiated Polyline object

append_extra_metadata(meta_dict)

Append a given dictionary of metadata to the existing metadata.

area()[source]

Returns the area in the xy plane of a closed convex polygon.

balanced_centre(mode='weighted', n=20, cache=True, in_xy=False)[source]

Returns a mean x,y,z based on sampling polyline at regular intervals.

property citation_title

Citation block title equivalent to self.title.

closest_segment_and_distance_to_point_xy(p)[source]

Returns the index of the closest segment to a point, and its distance, in the xy plane.

Parameters

p (pair or triple float) – the point

Returns

(int, float) where the int is the index of the line segment that the point is closest to; and the float is the distance of the point from that bounded segment, in the xy plane; units of measure are the crs xy units

classmethod convex_hull_from_closed_polyline(original, title, mode='crossing')[source]

Returns a new closed convex polyline being the convex hull of an original closed polyline.

create_interpretation_and_feature(kind='horizon', name=None, interp_title_suffix=None, is_normal=True)

Creates xml and objects for a represented interpretaion and interpreted feature, if not already present.

create_xml(ext_uuid=None, add_as_part=True, add_relationships=True, title=None, originator=None)[source]

Create xml from polyline.

Parameters

ext_uuid – the uuid of the hdf5 external part

denormalised_xy(norm_x, norm_y, mode='perimeter')[source]

Returns a denormalised x,y pair being point norm_x,norm_y (in range 0..1) under mapping onto convex polygon.

Parameters
  • norm_x (floats) – normalised values, each in range 0..1, identifying a location in a unit shape

  • norm_y (floats) – normalised values, each in range 0..1, identifying a location in a unit shape

  • mode (string) – ‘square’, ‘circle’, or ‘perimeter’; if square, norm_x and norm_y are coordinates within a unit square; if circle or perimeter, norm_x is the square of a radial fraction between the centre of the polygon and the perimeter; if mode is circle, norm_y is simply the polar coordinate bearing of the point relative to the polygon centre, with values 0..1 corresponding to 0..2pi radians; if mode is perimeter, norm_y is a fractional distance along the length of the closed polyline projected onto the xy plane

Returns

x, y (floats)

the location of a point within the area outlined by the polyline, which must be closed

and project to a convex polygon in the xy plane

Notes

this method is the inverse of normalised_xy(), as long as a consistent mode is selected; each mode gives a reversible mapping but there are some variations in density which could introduce slightly different biases when working with stochastic locations; density distortion with square and circle modes tends to increase as the polygon shape becomes less square (and aligned) or circular respectively; perimeter mode is believed to yield least density distortion generally; for circle and perimeter modes, the normalised x value is treated as the square of the fractional distance to the boundary in order for a rectangular distribution of normalised values to map to an even density of denormalised locations

equidistant_points(n, in_xy=False)[source]

Returns array of shape (n, 3) being points equally distributed along entire polyline.

first_line_intersection(x1, y1, x2, y2, half_segment=False)[source]

Finds the first intersection of (half) bounded line x,y 1 to 2 with polyline.

Returns

segment number & x, y of first intersection of (half) bounded line x,y 1 to 2 with polyline, or None, None, None if no intersection found

Note

‘first’ primariliy refers to the ordering of segments in this polyline

classmethod for_regular_polygon(model, n, radius, centre_xyz, crs_uuid, title)[source]

`Returns a closed polyline representing a regular polygon in xy plane.

Parameters
  • model (Model) – the model for which the new polyline is intended

  • n (int) – number of sides for the regular polygon

  • radius (float) – distance from centre of polygon to vertices; units are crs xy unites

  • centre_xyz (triple float) – the centre of the polygon

  • crs_uuid (UUID) – the uuid of the crs for the centre point and the returned polyline

  • title (str) – the citation title for the new polyline

Returns

a new closed Polyline representing a regular polygon in the xy plane

notee:

z values are all set to the z value of the centre point; one vertex will have an x value identical to the centre and a positive y offset (due north usually); this method does not write to hdf5 nor create xml for the new polyline

classmethod from_scaled_polyline(original, scaling, title=None, originator=None, extra_metadata=None)[source]

Returns a scaled version of the original polyline.

Parameters
  • original (Polyline) – the polyline from which the new polyline will be spawned

  • scaling (float) – the factor by which the original will be scaled

  • title (str, optional) – the citation title for the new polyline; inherited from original if None

  • originator (str, optional) – the name of the person creating the polyline; inherited from original if None

  • extra_metadata (dict, optional) – extra metadata for the new polyline; inherited from original if None

Returns

a new Polyline

Notes

the scaling factor is applied to vectors radiating from the balanced centre of the original polyline to its coordinates; a scaling of 1.0 will result in a copy of the original; if extra_metadata is not None, no extra metadata is inherited from original

classmethod from_trimmed_polyline(original, start_seg, end_seg, start_xyz=None, end_xyz=None, title=None, originator=None, extra_metadata=None)[source]

Returns a trimmed version of the original polyline.

Parameters
  • original (Polyline) – the polyline from which the new polyline will be spawned

  • start_seg (int) – the index of the first segment in original to be kept

  • end_seg (int) – the index of the last segment in original to be kept

  • start_xyz (triple float, optional) – the new start point; if None, start of start_seg is used

  • end_xyz (triple float, optional) – the new end point; if None, end of end_seg is used

  • title (str, optional) – the citation title for the new polyline; inherited from original if None

  • originator (str, optional) – the name of the person creating the polyline; inherited from original if None

  • extra_metadata (dict, optional) – extra metadata for the new polyline; inherited from original if None

Returns

a new Polyline

full_length(in_xy=False)[source]

Returns the naive length of the entire polyline.

interpolated_point(fraction, in_xy=False)[source]

Returns x,y,z point on the polyline at fractional distance along entire polyline.

is_clockwise(trust_metadata=True)[source]

Returns True if first non-straight triplet of nodes is clockwise in the xy plane; False if anti-clockwise.

Note

this method currently assumes that the xy axes are left-handed

is_convex(trust_metadata=True)[source]

Returns True if the polyline is closed and convex in the xy plane, otherwise False.

normalised_xy(x, y, mode='square')[source]

Returns a normalised x’,y’ pair (in range 0..1) being point x,y under mapping from convex polygon.

Parameters
  • x (floats) – location of a point inside the polyline, which must be closed and project to a convex polygon in the xy plane

  • y (floats) – location of a point inside the polyline, which must be closed and project to a convex polygon in the xy plane

  • mode (string) – which mapping algorithm to use, one of: ‘square’, ‘circle’, or ‘perimeter’

Returns

x’, y’ (floats, each in range 0..1) being the normalised representation of point x,y

Notes

this method is the inverse of denormalised_xy(), as long as a consistent mode is selected; for more details of the mapping used by the 3 modes, see documentation for denormalised_xy()

property part

Standard part name corresponding to self.uuid.

point_is_inside_xy(p, mode='crossing')[source]

Returns True if point p is inside closed polygon, in xy plane, otherwise False.

point_snapped_to_segment_xy(segment, p)[source]

Returns the point on a specified segment, in xy plane, that is closest to a point.

Parameters
  • segment (int) – the index of the line segment within the polyline

  • p (pair or triple float) – the point p (z value is ignored if present)

Returns

numpy float array of shape (2,) being the x, y coordinates of the snapped point

points_are_inside_xy(p_array)[source]

Returns bool array, True where p is inside closed polygon, in xy plane, otherwise False.

Parameters

p_array (numpy float array of shape (..., 2 or 3)) – an array of points, each of which is tested for inclusion against the closed polygon

Returns

numpy bool array of shape p_array.shape[ – -1], set True for those points which are inside the polygon

property rep_int_uuid

Returns the uuid of the represented interpretation.

property root

XML node corresponding to self.uuid.

segment_length(segment_index, in_xy=False)[source]

Returns the naive length (ie.

assuming x,y & z units are the same) of an individual segment of the polyline.

segment_midpoint(segment_index)[source]

Returns the midpoint of an individual segment of the polyline.

segment_normal(segment_index)[source]

For a closed polyline return a unit vector giving the 2D (xy) direction of an outward facing normal to a segment.

splined(tangent_weight='square', min_subdivisions=1, max_segment_length=None, max_degrees_per_knot=5.0, title=None, rep_int_root=None)[source]

Retrurns a new Polyline being a cubic spline of this polyline.

tangent_vectors()[source]

Returns a numpy array of unit length tangent vectors, one for each coordinate in the line.

try_reuse()

Look for an equivalent existing RESQML object and modify the uuid of this object if found.

Returns

boolean – True if an equivalent object was found, False if not

Note

by design this method may change this object’s uuid as a side effect

write_hdf5(file_name=None, mode='a')[source]

Create or append the coordinates hdf5 array to hdf5 file.

xy_crossings(other)[source]

Returns list of (x, y) pairs of crossing points with other polyline, in xy plane.

title

Citation title

originator

Creator of object. By default, user id.

uuid

Unique identifier