3.3.1. pci.api.cts module

This module has classes that hold representative information about coordinate systems and coordinate transformations.

3.3.1.1. Coordinate systems

class pci.api.cts.CRS

Bases: instance

This class represents a coordinate system.

A coordinate system is a mathematical space, where the elements of the space are called positions. Each position is described by a list of numbers. The length of the list corresponds to the dimension of the coordinate system. So in a two-dimensional coordinate system each position is described by a list containing two numbers.

However, in a coordinate system, not all lists of numbers correspond to a position - some lists may be outside the domain of the coordinate system. For example, in a 2D Lat/Lon coordinate system, the list (91,91) does not correspond to a position. Some coordinate systems also have a mapping from the mathematical space into locations in the real world. So in a Lat/Lon coordinate system, the mathematical position (lat, long) corresponds to a location on the surface of the Earth. This mapping from the mathematical space into real-world locations is called a datum.

A CRS cannot be created directly from python, it must be read from a Dataset, created from a string using mapunits_to_crs(), or another CRS and a vertical datum using create_3D_crs().

property crs_type

The CRSType of this coordinate system.

property dimensions

The number of dimensions of the coordinate system.

get_axis((CRS)self, (uint_)axis) → AxisInfo :

Get the AxisInfo for the specified axis.

get_unit((CRS)self, (uint_)axis) → IUnit :

Get the IUnit for the specified axis.

property is_projectable

True if this coordinate system is projectable, False otherwise.

property wkt

The well-known text representation of this coordinate system.

pci.api.cts.is_crs_pixel((CRS)crs) → bool :

Check if a given CRS is in PIXEL projection.

New in version 2016.

pci.api.cts.is_crs_local((CRS)crs) → bool :

Check if a given CRS is in local (METER, FOOT, PIXEL, etc.) projection.

New in version 2016.

class pci.api.cts.CRSType

Bases: enum

Specifies the type of coordinate system.

  • CST_Compound specifies a coordinate system made up of an aggregation of other coordinate systems, typically a two-dimensional horizontal coordinate system and a vertical coordinate system.

  • CST_Geocentric Specifies a three-dimensional coordinate system, with its origin at the centre of the earth.

  • CST_Geographic Specifies a two-dimensional coordinate system based on latitude and longitude.

  • CST_Fitted Specifies a coordinate system which sits inside another coordinate system. The fitted coordinate system can be rotated and shifted, or use any other math transform to inject itself into the base coordinate system.

  • CST_Local Specifies a local coordinate system, with uncertain relationship to the world.

  • CST_Projected specifies a two-dimensional cartographic projected coordinate system.

  • CST_Vertical specifies a one-dimensional vertical coordinate system.

  • CST_Unknown - specifies an unknown coordinate system, typically indicative of an error.

CST_Compound = pci.api.cts.CRSType.CST_Compound
CST_Fitted = pci.api.cts.CRSType.CST_Fitted
CST_Geocentric = pci.api.cts.CRSType.CST_Geocentric
CST_Geographic = pci.api.cts.CRSType.CST_Geographic
CST_Local = pci.api.cts.CRSType.CST_Local
CST_Projected = pci.api.cts.CRSType.CST_Projected
CST_Vertical = pci.api.cts.CRSType.CST_Vertical
CST_Unknown = pci.api.cts.CRSType.CST_Unknown
class pci.api.cts.AxisInfo

Bases: instance

This class contains information about a coordinate system axis.

property name

Name of the axis.

property orientation

The AxisOrientation orientation of the axis.

class pci.api.cts.AxisOrientation

Bases: enum

Specifies the orientation of a coordinate system axis.

  • AO_Other refers to an unspecifed axis orientation, can be used for a local CRS.

  • AO_North refers to increasing ordinates values go north.

  • AO_South refers to increasing ordinates values go south.

  • AO_East refers to increasing ordinates values go east.

  • AO_West refers to increasing ordinates values go west.

  • AO_Up refers to increasing ordinates values go vertically up.

  • AO_Down refers to increasing ordinates values go vertically down.

  • AO_Unknown typically specifies an error.

AO_Other = pci.api.cts.AxisOrientation.AO_Other
AO_North = pci.api.cts.AxisOrientation.AO_North
AO_South = pci.api.cts.AxisOrientation.AO_South
AO_East = pci.api.cts.AxisOrientation.AO_East
AO_West = pci.api.cts.AxisOrientation.AO_West
AO_Up = pci.api.cts.AxisOrientation.AO_Up
AO_Down = pci.api.cts.AxisOrientation.AO_Down
AO_Unknown = pci.api.cts.AxisOrientation.AO_Unknown
class pci.api.cts.IUnit

Bases: instance

This class represents information about the units of an axis of a coordinate system.

property ratio

The ratio between this unit and the standard unit of this type.

property unit_code

The UnitCode for this unit.

property unit_type

The UnitType type of this unit.

class pci.api.cts.AngularUnit

Bases: IUnit

This class represents information about the angular unit of an axis of a coordinate system, such as degrees or radians.

property radians_per_unit

The number of radians for one unit of this type. This variable has the same value as ratio.

property ratio

The ratio between this unit and the standard unit of this type.

property unit_code

The UnitCode for this unit.

property unit_type

The UnitType type of this unit.

class pci.api.cts.LinearUnit

Bases: IUnit

This class represents information about the linear unit of an axis of a coordinate system, such as metres or US feet.

property metres_per_unit

The number of metres for one unit of this type. This variable has the same value as ratio.

property ratio

The ratio between this unit and the standard unit of this type.

property unit_code

The UnitCode for this unit.

property unit_type

The UnitType type of this unit.

class pci.api.cts.UnitCode

Bases: enum

Specifies the type of units.

  • eRadians specifies radians.

  • eUSFeet specifies US feet.

  • eMeter specifies metres.

  • eSeconds specifies seconds.

  • eDegrees specifies degrees.

  • eFeet specifies international feet.

  • ePixels specifies pixels.

  • eOther specifies any other type of unit.

eRadians = pci.api.cts.UnitCode.eRadians
eUSFeet = pci.api.cts.UnitCode.eUSFeet
eMeter = pci.api.cts.UnitCode.eMeter
eSeconds = pci.api.cts.UnitCode.eSeconds
eDegrees = pci.api.cts.UnitCode.eDegrees
eFeet = pci.api.cts.UnitCode.eFeet
ePixels = pci.api.cts.UnitCode.ePixels
eOther = pci.api.cts.UnitCode.eOther
class pci.api.cts.UnitType

Bases: enum

Specifies the type of units of an axis of a coordinate system.

  • UT_Angular specifies angular units, such as degree or radians.

  • UT_Linear specifies linear units, such as metres or US feet.

  • UT_Scalar specifies units that are neither linear nor angular.

UT_Angular = pci.api.cts.UnitType.UT_Angular
UT_Linear = pci.api.cts.UnitType.UT_Linear
UT_Scalar = pci.api.cts.UnitType.UT_Scalar
class pci.api.cts.DatumType

Bases: enum

Specifies the type of datum.

  • VD_Ellipsoidal specifies an ellipsoidal vertical datum.

  • VD_Orthometric specifies a mean sea level vertical datum.

  • VD_Other specifies any other vertical datum, typically used in local coordinate systems.

VD_Ellipsoidal = pci.api.cts.DatumType.VD_Ellipsoidal
VD_Orthometric = pci.api.cts.DatumType.VD_Orthometric
VD_Other = pci.api.cts.DatumType.VD_Other
pci.api.cts.create_3D_crs((CRS)horiz, (DatumType)vdatum) → CRS :

Create a 3D coordinate system based on the 2D coordinate system horiz, and the vertical datum vdatum.

pci.api.cts.create_wgs84_crs() → CRS :

Create a 2D CRS for WGS84.

New in version CATALYST: 2.1

pci.api.cts.create_wgs84_3d_crs() → CRS :

Create a 3D CRS for WGS84.

New in version CATALYST: 2.1

pci.api.cts.crs_corners_to_geocodinginfo((CRS)crs, (float)ulx, (float)uly, (float)urx, (float)ury, (float)llx, (float)lly, (float)lrx, (float)lry, (int_)width, (int_)height, (bool)pixel_center) → GeocodingInfo :

Create a GeocodingInfo based on a CRS crs, four corners (UL=upper left, UR=upper right, LL=lower left, LR=lower right), the width and height (pixels and lines), and whether the points are centered on the pixel, pixel_center=True, or at the the top left of the pixel, pixel_center=False

New in version CATALYST: 2.1

pci.api.cts.get_horiz_crs((CRS)crs3D) → CRS :

Get the 2D coordinate system corresponding to the 3D coordinate system crs3D.

pci.api.cts.get_vert_datum_type((CRS)crs3D) → DatumType :

Get the vertical datum type for the 3D coordinate system crs3D.

pci.api.cts.get_vert_unit_type((CRS)crs3D) → UnitCode :

Get the vertical unit type for the 3D coordinate system crs3D.

pci.api.cts.get_utm_mapunits((float)x, (float)y, (CRS)crs) → str :

Retrieve the UTM zone and row as a map units string, based on the given x and y coordinate, in the given crs, a CRS. The datum or ellipsoid from the crs is used as the datum or ellipsoid in the output map units.

This function will return a best guess for a x or y outside the normal range.

Example return value: ‘UTM 43 G E000’

New in version CATALYST: 2.1

pci.api.cts.get_utm_mapunits_from_long_lat((float)longitude, (float)latitude, (string_)datum) → str :

Retrieve the UTM zone and row as a map units string, based on the given longitude and latitude in degrees, and an optional datum. The datum parameter is any object from which a datum can be extracted or derived. Accepted types are: DatumInfo, EllipsInfo, and a datum code or ellipsoid code.

If datum is omitted then the default datum of “D000” is used.

This function will return a best guess for a longitude or latitude outside the normal range.

Example return value: get_utm_mapunits_from_long_lat(75, -45, ‘E000’) results in ‘UTM 43 G E000’

get_utm_mapunits_from_long_lat( (float)longitude, (float)latitude) -> str

get_utm_mapunits_from_long_lat( (float)longitude, (float)latitude, (DatumInfo)datum) -> str

get_utm_mapunits_from_long_lat( (float)longitude, (float)latitude, (EllipsInfo)datum) -> str

New in version CATALYST: 2.1

pci.api.cts.get_utm_zone((float)longitude, (float)latitude) → tuple :

Retrieve the UTM zone and row information as a tuple. (zone, row) based on the given longitude and latitude in degrees. This function will return a best guess for a longitude or latitude outside the normal range.

New in version 2016.

3.3.1.1.1. Mapunits (string representations of coordinate systems)

A coordinate system can be represented potentially by the following various strings:

  1. Simple mapunits string - A string that indicates the projection and Earth model of the coordinate system, such as "UTM 18 D000". If a projection requires additional parameters, a mapunits string is insufficient to represent a coordinate system. For example, "LCC D122" does NOT fully specify a coordinate system, because the standard parallels, the origin, and the false easting and northing are not specified. With coordinate systems that do not require extra parameters, a mapunits string can be obtained from a CRS by calling crs_to_mapunits().

  2. Mapunits params string - A string that contains a mapunits string and a list of parameters separated by a “|”, such as "LCC   D122|0 0 -95 49 49 77 0 0 0 0 0 0 0 0 0 0 0 2". A mapunits string can be obtained from a CRS by calling crs_to_mapunits_params().

  3. User-projection string - A special alias for a coordinate system; such as, "CanLCC". User-projection strings are defined in $PCIHOME/etc/userproj.txt. A user-projection string can be obtained from a CRS by calling crs_to_userproj().

  4. EPSG code - A standard integer code associaed with a coordinate system, such as 42304. An EPSG code can be obtained from a supported CRS by calling crs_to_epsg().

  5. WKT string - A markup-text string for describing a coordinate system. A WKT string can be obtained from a CRS by accessing member variable CRS.wkt.

  6. Name of WKT Projection - The name of the coordinate system that is used in wkt strings

pci.api.cts.mapunits_to_crs((string_)mapunits) → CRS :

Create a CRS from the provided mapunits string, or any other supported string representation of a coordinate system, such as EPSG code or mapunits params string.

pci.api.cts.crs_to_mapunits((CRS)crs) → str :

Given a CRS, return the mapunits string. The returned value will be the default string representation of a CRS. If the CRS is a user projection, a User Projection String will be returned, otherwise if the CRS requires additional parameters, a Mapunits Params String will be returned, otherwise a Simple Mapunits String will be returned.

New in version 2016.

pci.api.cts.crs_to_mapunits_params((CRS)crs) → str :

Create a string representation of a CRS that contains the mapunits and parms seperated by a ‘|’.

New in version 2016.

pci.api.cts.crs_to_userproj((CRS)crs) → object :

Return the user projection string associated with the CRS crs. If crs is not a user projection, None is returned.

New in version 2016.

pci.api.cts.crs_to_epsg((CRS)crs) → object :

Return the integer EPSG code associated with the CRS crs. If an EPSG code cannot be found for crs, None is returned.

New in version 2016.

pci.api.cts.get_geographic_crs((CRS)crs) → CRS :

Get a geographic CRS that corresponds to crs. If crs is 3D, then the resulting CRS will also be 3D. If no corresponding geographic CRS, then None is returned.

New in version 2018sp3.

pci.api.cts.get_to_meters_ratio((CRS)crs[, (float)latitude=0.0]) → float :

Get the ratio to use to convert the unit of crs to meters. If the CRS cannot be converted to meters, then 0.0 is returned. If latitude is specified, then it is used to calculate this ratio for geographic coordinate systems.

New in version 2018sp3.

3.3.1.1.2. Earth model

Earth model is a PCI term for a regular model to represent the surface of the Earth. Note: This term can apply to either of the two forms of representing a model of the Earth that is supported in PCI software. The Earth model can be specified by either of the following forms:

  • A datum code (example: “D000”) for the horizontal datum.

  • An ellipsoid code (example: “E000”) for the ellipsoid used by the horizontal datum.

class pci.api.cts.DatumInfo

Bases: instance

The DatumInfo class is used to encapsulate all information related to horizontal datums.

New in version 2016.

property datum_code

PCI code for the datum

property datum_name

Name for the datum

property datum_where

Where the datum is used

property ellips_code

PCI code for the ellipsoid

property ellips_name

Name for the ellipsoid

property flattening

Flattening of the Ellipsoid. Where Flattening (f) = (semi_major - semi_minor) / semi_major

property grid_files

Name of the Grid File(s)

property grid_shift_to

If this datum has a gridshift file, specifies the datum that it shifts to.

property reverse_shift

Indicates whether gridshift file specifes a shift in the same or opposite direction of transforming to WGS84

property scale

Scale, default is 1.0

property semi_major

Semi-major (or equatorial) axis in metres

property semi_minor

Semi-minor (or polar) axis in metres

property x_offset

X axis offset (or delta) in metres

property x_rotate

X axis rotation (or alpha) in seconds

property y_offset

Y axis offset (or delta) in metres

property y_rotate

Y axis rotation (or beta ) in seconds

property z_offset

Z axis offset (or delta) in metres

property z_rotate

Z axis rotation (or gamma) in seconds

pci.api.cts.datum_code_to_datuminfo((string_)datum_code) → DatumInfo :

Get the DatumInfo for the specified datum from 4 character datum code

New in version 2016.

pci.api.cts.datum_num_code_to_datuminfo((int_)datum_num_code) → DatumInfo :

Get the class:DatumInfo for the specified datum numerical code of the datum.

New in version 2016.

class pci.api.cts.EllipsInfo

Bases: instance

The EllipsInfo class is used to encapsulate all information related to ellipsoids.

New in version 2016.

property ellips_code

PCI code for the ellipsoid

property ellips_name

Name for the ellipsoid

property semi_major

Semi-major (or equatorial) axis in metres

property semi_minor

Semi-minor (or polar) axis in metres

pci.api.cts.ellips_code_to_ellipsinfo((string_)ellips_code) → EllipsInfo :

Get the EllipsInfo for the specified ellipsoid from 4 character ellipsoid code

New in version 2016.

pci.api.cts.ellips_num_code_to_ellipsinfo((int_)ellips_num_code) → EllipsInfo :

Get the EllipsInfo for the specified ellipsoid numerical code of the ellipsoid.

New in version 2016.

3.3.1.1.3. Geocoding

class pci.api.cts.GeocodingInfo((object)arg1, (float)x_offset, (float)x_per_col, (float)x_per_row, (float)y_offset, (float)y_per_col, (float)y_per_row)

Bases: instance

The geocoding information is used to convert between raster (row, column) and map (easting/northing, longitude/latitude, X/Y, etc.) coordinates. It does not provide any information regarding what coordinate frame these map coordinates are expressed in; that information is represented by a CRS object.

The geocoding information is a 6-parameter affine transformation from raster to map space, allowing the user to store information for raster files that may be rotated and have different ground sample distance in the row and column directions.Create by specifying the x_offset, x_per_col *x_per_row, y_offset, y_per_col, and y_per_row.

__init__( (object)arg1, (float)x_offset, (float)y_offset, (float)col_inc, (float)row_inc [, (float)rotation]) -> None

almost_equal((GeocodingInfo)self, (GeocodingInfo)other[, (float)pixels=10000[, (float)lines=10000[, (float)threshold=0.001]]]) → bool :

Check to see if this object is almost equal to other. Two GeocodingInfo objects can be considered almost equal if their corners, with image size pixels by lines, are all within threshold pixels.

get_rotation((GeocodingInfo)self, (int_)width, (int_)height) → float :

Get the angle of rotaion in degrees. If the dataset is rotated (and not simple rotated) then the width and height of the dataset is needed to calculate the rotation angle.

property is_map_oriented

True if this object represents map-oriented raster space: +column parallel with +X and +row parallel with -Y, False otherwise.

property is_rotated

True if this object represents a simple rotated raster space with no differential shearing or reflection of coordinates, False otherwise.

property is_simple_rotated

True if this object represents a simple rotated raster space with no differential shearing or reflection of coordinates. The rectangular raster space becomes a rotated rectangle in map space and is not transformed to a parallelogram, False otherwise.

property map_oriented_coeffs

A four-element tuple of corner coordinates and resolution values that can be used for raster-to-map and map-to-raster calculations for simple map-oriented rasters.

map_to_raster((GeocodingInfo)self, (float)x, (float)y) → tuple :

Given the x and y map coordinates return a tuple of raster coordinates.

map_to_raster_array((GeocodingInfo)self, (object)arr) → None :

Convert the specified points from map coordinates to raster coordinates.

The numpy.ndarray, arr of N points must be either a 2D Nx3 array or a 1D array of size N*3 This array must contain the (x, y, z) map coordinates that will be converted to raster coordinates by this function.

raster_to_map((GeocodingInfo)self, (float)col, (float)row) → tuple :

Given the col and row raster coordinates return a tuple of map coordinates.

raster_to_map_array((GeocodingInfo)self, (object)arr) → None :

Convert the specified points from map coordinates to raster coordinates.

The numpy.ndarray, arr of N points must be either a 2D Nx3 array or a 1D array of size N*3 This array must contain the (x, y, z) raster coordinates that will be converted to map coordinates by this function.

property resolution

Get a two-element tuple of the column and row ground space distances.

property simple_rotated_coeffs

A five-element tuple of corner coordinates, resolution values, and rotation angle that can be used for raster-to-map and map-to-raster calculations for rasters that are rotated but not sheared with respect to map space.

property x_offset

The x offset of the top left corner of the image.

property x_per_col

The x increment in map space per column in raster space.

property x_per_row

The x increment in map space per row in raster space.

property y_offset

The y offset of the top left corner of the image.

property y_per_col

The y increment in map space per column in raster space.

property y_per_row

The y increment in map space per row in raster space.

pci.api.cts.make_simple_geocoding((float)x_offset, (float)y_offset, (float)col_inc, (float)row_inc[, (float)rotation=0.0]) → GeocodingInfo :

Create a simple rotated geocoding by specifying the offset upper left corner x and y offsets as x_offset and y_offset respectively. Specify the ground increment per pixel in the column and row directions as col_inc and row_inc respectively. Specify the rotation angle in degrees as rotation. The rotation angle is measured clockwise from the positive column axis to the positive X axis (i.e., to the first axis of the map coordinate system).

pci.api.cts.create_geocoding_info((float)min_x, (float)min_y, (float)max_x, (float)max_y, (float)gsd_x, (float)gsd_y[, (CRS)crs=0]) → GeocodingInfo :

Get the geocoding information from the bounding rectangle created by min_x, min_y, max_x, max_y, gsd_x, gsd_y and optionally a crs to query for its axis information.

3.3.1.1.4. ProjInfo

class pci.api.cts.ProjInfo((object)arg1)

Bases: instance

The ProjInfo class is used to encapsulate all information related to defining the projection of a data layer, as well as the transformation between data (pixel/line) coordinates in that data layer and projected coordinates.

Deprecated since version 2015: In future versions, this class will be removed. Please use CRS, GeocodingInfo, mapunits_to_crs() and crs_to_mapunits_params() for similar functionality.

property IOmultiply

Multiplicative conversion of IOunits.

property IOunits

Units of the Projection ‘FOOT’ or ‘METER’

property azimuth

Azimuth of the projection.

property d_earth

A two element tuple of the semi-major and semi-minor axes.

property false_easting

False easting of the projection.

property false_northing

False northing of the projection.

property height

Height Parameter of the projection.

property landsat_num

Landsat number parameter of the projection.

property landsat_path

Landsat number parameter of the projection.

property lat1

Latitude point number 1 of the projection.

property lat2

Latitude point number 2 of the projection.

property long1

Longitude point number 1 of the projection.

property long2

Longitude point number 2 of the projection.

property projection_code

USGS GCTPC projection code.

property projection_zone

USGS GCTPC projection zone.

property ref_lat

Reference latitude of the projection.

property ref_long

Reference longitude of the projection.

property scale

Scale of the projection.

property spheroid

USGS GCTPC code for spheroid.

property std_parallel1

First standard parallel of the projection.

property std_parallel2

Second standard parallel of the projection.

property units

The mapunits of the projection

property units_code

USGS GCTPC code for units.

property usgsparms

A list of up to 15 USGS GCTPC projection parameters.

property x_off

X offset of the upper left corner of the image.

property x_rot

X rotation parameter of the image.

property x_size

X size of the image.

property y_off

Y offset of the upper left corner of the image.

property y_rot

Y rotation parameter of the image.

property y_size

Y size of the image.

pci.api.cts.crs_to_projinfo((CRS)crs) → ProjInfo :

Create a ProjInfo based on the CRS crs

Deprecated since version 2015: In future versions, this function will be removed.

pci.api.cts.projinfo_to_crs((ProjInfo)proj) → CRS :

Create a CRS based on the ProjInfo proj

Deprecated since version 2015: In future versions, this function will be removed.

3.3.1.2. Coordinate transformations

class pci.api.cts.MathTransform

Bases: instance

Class to transform between multi-dimensional points in different coordinate systems. This class cannot be created directly from python. To create a MathTransform, call create_crs_transform().

inverse((MathTransform)self) → MathTransform :

Create a new MathTransform that performs the inverse of this transform.

property is_identity

True if this coordinate system is an identity transform, False otherwise.

property src_dims

The number of dimensions in the source coordinate system.

property tgt_dims

The number of dimensions in the target coordinate system.

transform((MathTransform)self, (VecDouble)input_points) → list :

Transform the specified point, or points from the source to target coordinate system. The input values input_points should be a list of coordinates of length num_points`*`src_dims. For example, if you wish to transform 2 points for a 3D coordinate system, then input_points should be a list with entries arranged as follows [x1, y1, z1, x2, y2, z2]. Return a list of similar structure to input_points with one entry for each dimension of each point.

transform_point((MathTransform)self, (object)input_point) → tuple :

Transform the specified point from the source to target coordinate system. The point input_point must have one entry for each source dimension. In other words, if the source coordinate system is 2D, then input_point must have 2 entries and if the source coordinate system is 3D, then input_point must have 3 entries. Return a tuple representing the point in the target coordinate system.

pci.api.cts.create_crs_transform((CRS)src, (CRS)tgt[, (float)default_height=0.0]) → MathTransform :

Create a MathTransform that can be used to transform points for the src coordinate system to the tgt coordinate system. Specify default_height for the constant output height value when performing a 2D->3D transform.