geosoft.gxpy.coordinate_system submodule¶

Coodinate systems

Classes

Coordinate_system: define a coordinate system
Coordinate_translate: translate coordinates between coordinate systems
Wkt: well-know coordinate system for ESRI interoperability

Coordinate systems describe how cartesian coordinates are located ralative to the Earth. Cartesian coordinates are right-handed (x, y, z) spatial ordinates that describe locations within a coordinate system frame of reference. For coordinates relative to a horizontal plane, positive z is up, usually equivalent to elevation relative to a vertical datum.

Coordinate systems can be oriented in three dimensions using an orientation definition, which defines an (x0, y0, z0) origin and rotation (rx, ry, rz) around the X, Y and then Z axis relative to a base coordinate system.

Base coordinate systems are usually defined by “well-known” coordinate system projections on a datum of the earth.

Coordinate System Name

A coordinate system will also have a descriptive name that identifies the base system with a datum and “well-known” map projection description, plus optional orientation and vertical reference datum if defined. Orientation parameters are enclosed in <> that define <x0, y0, z0, rx, ry, rz> (eg. <400000, 6200000,0,0,-90,0>). If a vertical reference datum is defined it will appear as a string in square brackets, for example [CGVD28].

Example coordinate system names:

"NAD83 / UTM zone 15N"
"NAD83 / UTM zone 15N <450000,6250000,0,0,0,-25>" # oriented system, rotated -25 degrees
"NAD83 / UTM zone 15N [NAVD88]"
"NAD83 / UTM zone 15N <450000,6250000,0,0,0,-25> [NAVD88]"

The descriptive name for “well-known” coordinate systems is sufficient to describe the coordinate system from the EPSG Geodetic Registry. To fully locate ad-hoc coordinates you will need the parameters defined in the GXF stings. See Coordinate_system.gxf.

Constants

NAME: None
NAME_HCS: gxapi.IPJ_NAME_PCS
NAME_PROJECTION: gxapi.IPJ_NAME_PROJECTION
NAME_METHOD: gxapi.IPJ_NAME_METHOD
NAME_DATUM: gxapi.IPJ_NAME_DATUM
NAME_ELLIPSOID: gxapi.IPJ_NAME_ELLIPSOID
NAME_LDATUM: gxapi.IPJ_NAME_LDATUM
NAME_UNIT: gxapi.IPJ_NAME_UNIT_ABBR
NAME_UNIT_FULL: gxapi.IPJ_NAME_UNIT_FULL
NAME_TYPE: gxapi.IPJ_NAME_TYPE
NAME_LLDATUM: gxapi.IPJ_NAME_LLDATUM
NAME_METHOD_PARMS: gxapi.IPJ_NAME_METHOD_PARMS
NAME_METHOD_LABEL: gxapi.IPJ_NAME_METHOD_LABEL
NAME_DATUM_PARMS: gxapi.IPJ_NAME_DATUM_PARMS
NAME_LDATUM_PARMS: gxapi.IPJ_NAME_LDATUM_PARMS
NAME_GEOID: gxapi.IPJ_NAME_GEOID
NAME_LDATUMDESCRIPTION: gxapi.IPJ_NAME_LDATUMDESCRIPTION
NAME_METHOD_PARMS_NATIVE: gxapi.IPJ_NAME_METHOD_PARMS_NATIVE
NAME_ORIENTATION: gxapi.IPJ_NAME_ORIENTATION_PARMS
NAME_VCS: -1
NAME_HCS_VCS: -2
LIST_COORDINATESYSTEM: gxapi.IPJ_PARM_LST_COORDINATESYSTEM
LIST_DATUM: gxapi.IPJ_PARM_LST_DATUM
LIST_PROJECTION: gxapi.IPJ_PARM_LST_PROJECTION
LIST_UNITS: gxapi.IPJ_PARM_LST_UNITS
LIST_UNITSDESCRIPTION: gxapi.IPJ_PARM_LST_UNITSDESCRIPTION
LIST_LOCALDATUMDESCRIPTION: gxapi.IPJ_PARM_LST_LOCALDATUMDESCRIPTION
LIST_LOCALDATUMNAME: gxapi.IPJ_PARM_LST_LOCALDATUMNAME
PARM_DATUM: ‘datum’
PARM_PROJECTION: ‘transform’
PARM_UNITS: ‘units’
PARM_LOCAL_DATUM: ‘datumtrf’

See also

geosoft.gxapi.GXIPJ

Note

Regression tests provide usage examples: tests

exception CSException(message)[source]¶

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.coordinate_system.

New in version 9.2.

class Coordinate_system(coordinate_system=None)[source]¶

Bases: object

Coordinate system class. A coordinate system defines a horizontal and vertical reference system to locate (x, y, z) cartesian coordinates relative to the Earth.

Parameters

coordinate_system –

a coordinate system can be created from a number of different forms:

Geosoft name string (ie. “WGS 84 / UTM zone 32N [geodetic]”)
Geosoft xml with root ‘projection’, xmlns=”http://www.geosoft.com/schema/geo”
ESRI WKT string (ie. “PROJCS[“WGS_1984_UTM_Zone_35N”,GEOGCS[…”)
a dictionary that contains the coordinate system properties either as a set of xml properties from a Geosoft xml ‘property’ definition, or as defined by Dictionary Structure below.
a JSON string that contains the coordinate system properties
a list that contains the 5 GXF coordinate system strings. For example: ['"WGS 84 / UTM zone 32N [geodetic]", "WGS 84", "UTM zone 32N", "", ""]
geosoft.gxapi.GXIPJ instance
Coordinate_system instance, returns a copy
None to create an unknown coordinate system.

For examples refer to tests

Dictionary Structure

Geosoft

{   "type": "Geosoft",
    "name": name
    "datum": datum
    "method": method
    "units": units
    "local_datum": local datum transform
    "orientation": x0, y0, z0, xR, yR, zR
    "vcs": "vertical coordinate system"
}

local

type “local” can be used to locate local coordinates in situations where one only has the (longitude, latitude) of a point on local coordinate system and the orientation of the local axis relative to geographic North. Internally an Oblique Stereographic projection is created with an origin at the defined origin point.

{   "type": "local",
    "lon_lat": (lon, lat) required longitude, latitude of "origin", in degrees
    "origin": (x0, y0) location of "lon_lat" on the local coordinate system, default is (0,0)
    "azimuth": azimuth of rotation of local axiz relative to North.
    "elevation": elevation of the origin in the vertical coordinate system, default is 0.
    "datum": datum, default is "WGS 84"        
    "local_datum": local datum transform, default is the default for the datum
    "scale_factor": local scale factor, default is 0.9996 to be similar to UTM locally
    "vcs": "vertical coordinate system" default is undefined.
}

Example: cs = geosoft.gxpy.Coordinate_system({‘type’: ‘local’, ‘lon_lat’: (-96, 43), ‘azimuth’: 25})

EPSG

(http://www.epsg.org/)

{   "type": "EPSG"
    "code": EPSG_code_number
    "orientation": x0, y0, z0, xR, yR, zR
}

ESRI

(http://webhelp.esri.com/arcgisserver/9.3/java/index.htm#geodatabases/the_ogc-607957855.htm)

{   "type": "ESRI",
    "wkt": wkt format string, starts with "PROJCS[" or "GEOGCS["
    "orientation": x0, y0, z0, xR, yR, zR
    "vcs": "vertical coordinate system"
}

New in version 9.2: supercedes ipj module.

__init__(coordinate_system=None)[source]¶: Initialize self. See help(type(self)) for accurate signature.

coordinate_dict()[source]¶: Returns “Geosoft” dictionary of coordinate system attributes.

New in version 9.2.

cs_name(what=None)[source]¶

Return requested name.

Parameters

what –

NAME
NAME_HCS
NAME_VCS
NAME_HCS_VCS
NAME_PROJECTION
NAME_METHOD
NAME_DATUM
NAME_ELLIPSOID
NAME_LDATUM
NAME_UNIT
NAME_UNIT_FULL
NAME_TYPE
NAME_LLDATUM
NAME_METHOD_PARMS
NAME_METHOD_LABEL
NAME_DATUM_PARMS
NAME_LDATUM_PARMS
NAME_GEOID
NAME_LDATUMDESCRIPTION
NAME_METHOD_PARMS_NATIVE
NAME_ORIENTATION

If ‘what’ is not specified, gxipj.NAME assumed, which returns the coordinate system display name.

Returns: The name requested

New in version 9.2.

property esri_wkt¶: ESRI Well-Known-Text (wkt) format coordinate string

New in version 9.3.

property gxf¶

The GXF string list from ipj. (http://www.geosoft.com/resources/goto/GXF-Grid-eXchange-File)

The first string (gxf[0]) is the coordinate system name in the form:

datum / projection <x0,y0,z0,rx,ry,rz> [vcs]

The orientation parameters are between the ‘<>’, and will be omitted if all 0.

‘vcs’ is the vertical coordinate system, and is omitted if the vcs is undefined.

New in version 9.2.

property gxipj¶: geosoft.gxapi.GXIPJ instance

property hcs¶: horizontal coordinate system name

property is_known¶: True if this is a known coordinate system.

New in version 9.3.

property is_oriented¶: True if the coordinate system has an orientation.

property json¶: JSON formatted coordinate system string.

New in version 9.3.

classmethod local(lon_lat=0, 0, origin=0, 0, azimuth=0, elevation=0, datum='WGS 84', local_datum=None, scale_factor=0.9996, vcs=None)[source]¶

Create an ad-hoc local coordinate system.

Parameters

lon_lat – (longitude, latitude) of the center
origin – (x, y) to assign to the center
azimuth – local rotation of the system relative to geographic North, in degrees azimuth
elevation – elevation for z = 0.
datum – datum, default is “WGS 84”
local_datum – local datum, default will be the default for the specified datum
scale_factor – central scale factor. The default is 0.9996 as the most common map system is UTM and thus relative distances in the local system will be similar, though not the same, as UTM.
vcs – name for the vertical coordinate system reference, default is unknown

Local coordinate systems are simple cartesian systems established for a specific purpose without complete geodetic control, but for which one knows or can estimate the longitude, latitude of a point on the local coordinate system. In this way local coordinates can be located reasonably well relative to the Earth and and other Earth-refeerenced data.

The local system will be constructed as an oblique stereographic projection centered at the system origin, which is similar to what one sees when looking at maps in Google maps.

New in version 9.3.1.

property metres_per_unit¶: the number metres per distance unit of the coordinate system.

property name¶: coordinate system name as ‘datum / projection <orientation> [vcs]’

property orientation_name¶: The name of an oriented section for display/reference purposes.

New in version 9.4.

oriented_from_xyz(xyz, column_ordered=False)[source]¶

Return oriented (x, y, z) coordinates from true base (x, y, z) coordinates.

Parameters

xyz – (x, y, z) or iterable
column_ordered – if xyz is iterable, and this is True, the data is assumed to be column ordered and the results are returned column ordered.

Returns

(x, y, z) in un-oriented space

New in version 9.2.

same_as(other)[source]¶: Return True if both coordinate systems (HCS and VCS) are the same.

New in version 9.2.

same_hcs(other)[source]¶: Return True if the HCS are the same.

New in version 9.2.

same_vcs(other)[source]¶: Return True if the VCS are the same.

New in version 9.2.

property unit_of_measure¶: same as units_name, provided for naming consistency with other usage in gxpy.

property units_name¶: name of the distance units (abbreviation)

property vcs¶: Vertical coordinate system name. Can be set.

property xml¶: xml of the coordinate system using Geosoft schema. Can be set.

New in version 9.4.

xyz_from_oriented(xyz, column_ordered=False)[source]¶

Return true base (x, y, z) coordinates from oriented (x, y, z) coordinates.

Parameters

xyz – (x, y, z) or iterable
column_ordered – if xyz is iterable, and this is True, the data is assumed to be column ordered and the results are returned column ordered.

Returns

(x, y, z) in oriented space

New in version 9.2.

class Coordinate_translate(cs_from, cs_to)[source]¶

Bases: object

Class to reproject coordinates between different coordinate systems.

Params cs_from: from Coordinate_system
Params cs_to: to Coordinate_system

New in version 9.2.

__init__(cs_from, cs_to)[source]¶: Initialize self. See help(type(self)) for accurate signature.

convert(xyz, in_place=False)[source]¶

Project data in array in which first columns are x,y or x,y,z.

Coordinates are reprojected in-place.

Parameters

xyz – numply shape (n,2) or (n,3+), or list, or a single (x, y, z) tuple. Array dimension (n,2) for (x, y), (n,3+) for x,y,z. Only numpy arrays may have dimensions above 3.
in_place – if True, numpy array data is converted in-place. Ignored for list or tuple

Example

Given an array shape (500,6), which represents 500 data records with 6 columns in which the first 3 columns are coordinates X, Y and Z.

data = np.zeros((10,5), dtype='float') #then fill the array with some data

xy_only = pj.convert(data[:,2])     #transform x,y
xyz_only = pj.convert(data[:,3])    #transform x,y and z
all = pj.convert(data)              #transform x,y and z with data returned

Returns

projected data in the same form as passed (numpy array, list, or (x,y,z))

New in version 9.2.

Changed in version 9.3.1: conversion methods will return results in the same type as the input data.

convert_vv(xvv, yvv, zvv=None)[source]¶

Project vv locations in-place.

Parameters

xvv – x locations as geosoft.gxpy.vv.GXvv instance
yvv – y locations as geosoft.gxpy.vv.GXvv instance
zvv – optional z locations as geosoft.gxpy.vv.GXvv instance

New in version 9.3.1.

class Wkt(wkt)[source]¶

Bases: object

Helper class to parse WKT-formatted spatial reference strings.

Parameters: wkt – wkt (well-known text) string that describes a coordinate system.

New in version 9.2.

__init__(wkt)[source]¶: Initialize self. See help(type(self)) for accurate signature.

find_key(k)[source]¶

Return the name and list of items for a key

Parameters: k – the key to look for in the wkt
Returns: name (‘’ if not found), list of parameters, ([] if no items)

New in version 9.2.

property name¶: Return the ESRI coordinate system WKT string

New in version 9.2.

find_key(wkt, k)[source]¶: Find a key in the wkt, return it’s name and items.

New in version 9.2.

hcs_orient_vcs_from_name(name)[source]¶: Split a full coordinate system name into its components. A name has the form “hcs <orient> [vcs]” :param name: :returns: hcs, orient, vcs

New in version 9.2.

is_known(coordinate_system)[source]¶: Return True if this is a known coordinate system

New in version 9.3.1.

list_from_wktsrs(wkt)[source]¶: Return a list from a wkt spatial reference string.

New in version 9.2.

name_from_hcs_orient_vcs(hcs, orient=None, vcs=None)[source]¶

Construct a coordinate system name from an hcs, orientation and vcs. If orient or vcs are None or empty, the name will not include these parts.

Parameters

hcs – horizontal coordinate system string
orient – orientation string
vcs – vertical coordinate system string

Returns

“hcs <orient> [vcs]”

New in version 9.2.

name_list(what, datum_filter='')[source]¶

Get a list of coordinate system names

Parameters

what –

LIST_COORDINATESYSTEM

LIST_DATUM

LIST_PROJECTION

LIST_UNITS

LIST_LOCALDATUMDESCRIPTION

LIST_LOCALDATUMNAME

LIST_UNITSDESCRIPTION
datum_filter – name of a datum to filter results

Returns

sorted list of names

New in version 9.2.

parameter_exists(what, key)[source]¶

Test if a parameter set exists in a coordinate system table.

Parameters

what – see parameters()
key – parameter key

Returns

True if table/key exists

New in version 9.2.

parameters(what, key)[source]¶

Get a dictionary of parameters for a coordinate system item. Parameters are maintained in csv coordinate system table files in the Geosoft Desktop Applications csv folder.

Parameters

what –

PARM_DATUM (from datum.csv)

PARM_PROJECTION (from transform.csv)

PARM_UNITS (from units.csv)

PARM_LOCAL_DATUM (from datumtrf.csv)
key – parameter key to find and return

Raises

CSException – if table or key not found.

New in version 9.2.

wkt_vcs(vcs)[source]¶: Compose a wkt VERTCS block from a Geosoft vcs string.

New in version 9.2.