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.

See also

geosoft.gxapi.GXIPJ

Note

Regression tests provide usage examples: coordinate_system tests

exception geosoft.gxpy.coordinate_system.CSException¶

Bases: Exception

Exceptions from geosoft.gxpy.coordinate_system.

New in version 9.2.

class geosoft.gxpy.coordinate_system.Coordinate_system(coordinate_system=None)¶

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:

cs –

Coordinate systems can be created from a number of different forms:

Geosoft name string (ie. “WGS 84 / UTM zone 32N [geodetic]”)
ESRI WKT string (ie. “PROJCS[“WGS_1984_UTM_Zone_35N”,GEOGCS[...”)
a dictionary that contains the coordinate system properties (see Dictionary Structure below.)
a JSON string that contains the coordinate system properties
a list that contains the 5 GXF coordinate system strings (eg: [‘“WGS 84 / UTM zone 32N [geodetic]”, “WGS 84”, “UTM zone 32N”, “”, “”])
geosoft.gxapi.GXIPJ instance
Coordinate_system instance, returns a copy

For examples refer to coordinate_system 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.

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

New in version 9.2.

cs_name(what=None)¶

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.

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.

gxipj¶: geosoft.gxapi.GXIPJ instance

hcs¶: horizontal coordinate system name

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

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

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

oriented_from_xyz(xyz, column_ordered=False)¶

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)¶: Return True if both coordinate systems (HCS and VCS) are the same.

New in version 9.2.

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

New in version 9.2.

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

New in version 9.2.

units_name¶: name of the distance units (abbreviation)

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

xyz_from_oriented(xyz, column_ordered=False)¶

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

Parameters:	xyz – (x, y, z) or irerable 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 geosoft.gxpy.coordinate_system.Coordinate_translate(cs_from, cs_to)¶

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.

convert(xyz, in_place=False)¶

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.

class geosoft.gxpy.coordinate_system.Wkt(wkt)¶

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.

find_key(k)¶

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.

name¶: Return the ESRI coordinate system WKT string

New in version 9.2.

geosoft.gxpy.coordinate_system.find_key(wkt, k)¶: Find a key in the wkt, return it’s name and items.

New in version 9.2.

geosoft.gxpy.coordinate_system.hcs_orient_vcs_from_name(name)¶: 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.

geosoft.gxpy.coordinate_system.list_from_wktsrs(wkt)¶: Return a list from a wkt spatial reference string.

New in version 9.2.

geosoft.gxpy.coordinate_system.name_from_hcs_orient_vcs(hcs, orient=None, vcs=None)¶

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.

geosoft.gxpy.coordinate_system.name_list(what, datum_filter='')¶

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.

geosoft.gxpy.coordinate_system.parameter_exists(what, key)¶

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.

geosoft.gxpy.coordinate_system.parameters(what, key)¶

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.

geosoft.gxpy.coordinate_system.wkt_vcs(vcs)¶: Compose a wkt VERTCS block from a Geosoft vcs string.

New in version 9.2.

Related Topics

Previous Topic

Next Topic

This Page

geosoft.gxpy.coordinate_system submodule¶