resqpy.lines.Polyline¶
- class resqpy.lines.Polyline(parent_model, uuid=None, set_bool=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
Returns the uuid of the represented interpretation.
Inherited from
BaseResqpy
resqml_type
Standard part name corresponding to self.uuid.
XML node corresponding to self.uuid.
Citation block title equivalent to self.title.
Commonly Used Methods:
__init__
(parent_model[, uuid, set_bool, ...])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 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.
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.
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__
(parent_model[, uuid, set_bool, ...])Initialises a new polyline object.
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 for polyline and optionally adds as part to model.
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, is_closed=None, title=None, rep_int_root=None, originator=None, extra_metadata=None)[source]¶
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_bool (boolean, optional) – DEPRECATED: synonym for is_closed argument
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.
- 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 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')[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.
- extract_property_collection(refresh=False)[source]¶
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)[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
- 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
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')[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) – 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)[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.
- segment_xyz_from_xy(segment, x, y)[source]¶
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)[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