resqpy.lines.Polyline

class resqpy.lines.Polyline(parent_model, uuid=None, set_coord=None, set_crs=None, is_closed=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	Definition of which RESQML object the class represents.
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_coord, ...])	Initialises a new polyline 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 for polyline and optionally adds as part to model.
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 closed polyline is clockwise when viewed from above; 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.
segment_xyz_from_xy(segment, x, y)	Returns xyz point on segment given x and y (which should be on or close to the segment).
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.
extract_property_collection([refresh])	Returns a property collection for the polyline.

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__(model[, uuid, title, originator, ...])	Load an existing resqml object, or create new.
try_reuse()	Look for an equivalent existing RESQML object and modify the uuid of this object if found.
create_xml([title, originator, ...])	Write citation block to XML.
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_coord=None, set_crs=None, is_closed=None, title=None, rep_int_root=None, originator=None, extra_metadata=None)

Initialises a new polyline 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_coord (numpy float array, optional) – an ordered set of xyz values used to define a new polyline; last dimension of array must have extent 3; 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

• is_closed (boolean, optional) – if True, a new polyline created from coordinates is flagged as a closed polyline (polygon); 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()

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

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

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)

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')

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)

Create xml for polyline and optionally adds as part to model.

Parameters:

ext_uuid – the uuid of the hdf5 external part

denormalised_xy(norm_x, norm_y, mode='perimeter')

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)

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

extract_property_collection(refresh=False)

Returns a property collection for the polyline.

Parameters:

refresh (bool, default False) – if True, the property collection is refreshed from the current state of the model; if False and the property collection has already been cached for the polyline, then the cached copy is used

Returns:

a PropertyCollection holding those properties in the model where this polyline is the supporting representation

Notes

polyline properties may have indexable element of ‘nodes’ or ‘intervals’; for interval properties, the number of elements depends on whether the polyline is closed or not

first_line_intersection(x1, y1, x2, y2, half_segment=False)

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)

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

Notes

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)

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)

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)

Returns the naive length of the entire polyline.

interpolated_point(fraction, in_xy=False)

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

is_clockwise(trust_metadata=True)

Returns True if closed polyline is clockwise when viewed from above; False if anti-clockwise.

is_convex(trust_metadata=True)

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

normalised_xy(x, y, mode='square')

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:

xn, yn (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')

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

point_snapped_to_segment_xy(segment, p)

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)

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

Parameters:

p_array (numpy float array) – an array of points, each of which is tested for inclusion against the closed polygon; the final axis of the array must have extent 2 or 3

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)

Returns the naive length (ie.

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

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.

segment_xyz_from_xy(segment, x, y)

Returns xyz point on segment given x and y (which should be on or close to the segment).

Note

this method allows a return to a 3D point after working in the 2D xy plane; it will fail if the segment is ‘vertical’, ie. without range in x or y

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

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

tangent_vectors()

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')

Create or append the coordinates hdf5 array to hdf5 file.

xy_crossings(other)

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