resqpy.crs.Crs

class resqpy.crs.Crs(parent_model: Model, uuid: UUID | None = None, x_offset: float = 0.0, y_offset: float = 0.0, z_offset: float = 0.0, rotation: float = 0.0, rotation_units: str = 'dega', xy_units: str = 'm', z_units: str = 'm', z_inc_down: bool = True, axis_order: str = 'easting northing', time_units: str | None = None, epsg_code: str | None = None, title: str | None = None, originator: str | None = None, extra_metadata: Dict[str, str] | None = None)

Bases: BaseResqpy

Coordinate reference system object.

Public Data Attributes:

resqml_type	Returns the RESQML class for this crs.
valid_axis_orders

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, x_offset, ...])	Create a new coordinate reference system object.
convert_to(other_crs, xyz)	Converts a single xyz point from this coordinate reference system to the other.
convert_array_to(other_crs, xyz)	Converts in situ a numpy array of xyz points from this coordinate reference system to the other.
convert_from(other_crs, xyz)	Converts a single xyz point from the other coordinate reference system to this one.
convert_array_from(other_crs, xyz)	Converts in situ a numpy array of xyz points from the other coordinate reference system to this one.
create_xml([title, originator, ...])	Creates a Coordinate Reference System xml node and optionally adds as a part in the parent model.

Methods:

set_rotation_matrices()	Sets the rotation matrices, and the rotated and null_transform flags, call after changing rotation.
is_right_handed_xy()	Returns True if the xy axes are right handed when viewed from above; False if left handed.
is_right_handed_xyz()	Returns True if the xyz axes are right handed; False if left handed.
global_to_local(xyz[, global_z_inc_down, ...])	Convert a single xyz point from the parent coordinate reference system to this one.
global_to_local_array(xyz[, ...])	Convert in situ a numpy array of xyz points from the parent coordinate reference system to this one.
local_to_global(xyz[, global_z_inc_down, ...])	Convert a single xyz point from this coordinate reference system to the parent one.
local_to_global_array(xyz[, ...])	Convert in situ a numpy array of xyz points from this coordinate reference system to the parent one.
has_same_epsg_code(other_crs)	Returns True if either of the crs'es has a null EPSG code, or if they are the same.
is_equivalent(other_crs)	Returns True if this crs is effectively the same as the other crs.

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.

property resqml_type

Returns the RESQML class for this crs.

__init__(parent_model: Model, uuid: UUID | None = None, x_offset: float = 0.0, y_offset: float = 0.0, z_offset: float = 0.0, rotation: float = 0.0, rotation_units: str = 'dega', xy_units: str = 'm', z_units: str = 'm', z_inc_down: bool = True, axis_order: str = 'easting northing', time_units: str | None = None, epsg_code: str | None = None, title: str | None = None, originator: str | None = None, extra_metadata: Dict[str, str] | None = None)

Create a new coordinate reference system object.

Parameters:

• parent_model (model.Model) – the model to which the new Crs object will belong

• crs_uuid (uuid.UUID) – the uuid of an existing RESQML crs object in model, from which to instantiate the resqpy Crs object; if present, all the remaining arguments are ignored

• x_offset (floats, default zero) – the local origin within an implicit parent crs

• y_offset (floats, default zero) – the local origin within an implicit parent crs

• z_offset (floats, default zero) – the local origin within an implicit parent crs

• rotation (float, default zero) – a projected view rotation (in the xy plane), in radians, relative to an implicit parent crs; positive value indicates local y axis is clockwise from global y axis.

• rotation_units (str, default 'dega') – the units applicable to rotation, usually ‘dega’ or ‘rad’

• xy_units (str, default 'm') – the units applicable to x & y values; must be one of the RESQML length uom strings

• z_units (str, default 'm') – the units applicable to z depth values; must be one of the RESQML length uom strings

• z_inc_down (boolean, default True) – if True, increasing z values indicate greater depth (ie. in direction of gravity); if False, increasing z values indicate greater elevation

• axis_order (str, default 'easting northing') – the compass directions of the positive x and y axes respectively

• time_units (str, optional) – if present, the time units of the z values (for seismic datasets), in which case the z_units argument is irrelevant

• epsg_code (str, optional) – if present, the EPSG code of the implicit parent crs

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

• originator (str, optional) – the name of the person creating the crs, 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 crs; ignored if uuid is not None

Returns:

a new resqpy Crs object

Notes

although resqpy does not have full support for identifying a parent crs, the modifiers such as a local origin may be used on the assumption that all crs objects refer to the same implicit parent crs; there are two equivalent RESQML classes and which one is generated depends on whether the time_units argument is used, when instantiating from values; it is strongly encourage to call the create_xml() method immediately after instantiation (unless the resqpy crs is a temporary object) as the uuid may be modified at that point to re-use any existing equivalent RESQML crs object in the model; a positive rotation implies that local coordinates are clockwise from global coordinates

set_rotation_matrices()

Sets the rotation matrices, and the rotated and null_transform flags, call after changing rotation.

is_right_handed_xy() → bool

Returns True if the xy axes are right handed when viewed from above; False if left handed.

is_right_handed_xyz() → bool

Returns True if the xyz axes are right handed; False if left handed.

global_to_local(xyz: Tuple[float, float, float] | List[float] | ndarray, global_z_inc_down: bool = True, global_axis_order='easting northing') → Tuple[float, float, float]

Convert a single xyz point from the parent coordinate reference system to this one.

global_to_local_array(xyz: ndarray, global_z_inc_down: bool = True, global_axis_order='easting northing')

Convert in situ a numpy array of xyz points from the parent coordinate reference system to this one.

local_to_global(xyz: Tuple[float, float, float] | List[float] | ndarray, global_z_inc_down: bool = True, global_axis_order='easting northing') → Tuple[float, float, float]

Convert a single xyz point from this coordinate reference system to the parent one.

local_to_global_array(xyz: ndarray, global_z_inc_down: bool = True, global_axis_order='easting northing')

Convert in situ a numpy array of xyz points from this coordinate reference system to the parent one.

has_same_epsg_code(other_crs: Crs) → bool

Returns True if either of the crs’es has a null EPSG code, or if they are the same.

is_equivalent(other_crs: Crs) → bool

Returns True if this crs is effectively the same as the other crs.

convert_to(other_crs: Crs, xyz: Tuple[float, float, float] | List[float] | ndarray) → Tuple[float, float, float]

Converts a single xyz point from this coordinate reference system to the other.

convert_array_to(other_crs: Crs, xyz: ndarray)

Converts in situ a numpy array of xyz points from this coordinate reference system to the other.

convert_from(other_crs: Crs, xyz: Tuple[float, float, float] | List[float] | ndarray) → Tuple[float, float, float]

Converts a single xyz point from the other coordinate reference system to this one.

convert_array_from(other_crs: Crs, xyz: ndarray)

Converts in situ a numpy array of xyz points from the other coordinate reference system to this one.

create_xml(title: str | None = None, originator: str | None = None, extra_metadata: Dict[str, str] | None = None, add_as_part: bool = True, reuse: bool = True)

Creates a Coordinate Reference System xml node and optionally adds as a part in the parent model.

Parameters:

• title (string, optional) – used as the Title text in the citation node

• originator (string, optional) – the name of the human being who created the crs object; default is to use the login name

• extra_metadata (dict, optional) – string key, value pairs to add as extra metadata for the crs

• add_as_part (boolean, default True) – if True the newly created crs node is added to the model as a part

• reuse (boolean, default True) – if True and an equivalent crs already exists in the model then the uuid for this Crs is modified to match that of the existing object and the existing xml node is returned without anything new being added

Returns:

newly created (or reused) coordinate reference system xml node

Notes

if the reuse argument is True, it is strongly recommended to call this method immediately after a new Crs has been instantiated from explicit values, as the uuid may be modified here; if reuse is True, the title is not regarded as important and a match with an existing object may occur even if the titles differ

append_extra_metadata(meta_dict)

Append a given dictionary of metadata to the existing metadata.

property citation_title

Citation block title equivalent to self.title.

property part

Standard part name corresponding to self.uuid.

property root

XML node corresponding to self.uuid.

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

title

Citation title

originator

Creator of object. By default, user id.

uuid

Unique identifier