geosoft.gxpy.map submodule

Geosoft maps contain one or more 2D and 3D views.

Classes:
Map map class

Each 2D view has a specific coordinate system and clip region. Each 3D view is a link to a separate geosoft_3dv file, which can be placed in the map as a 2D perspective of the last viewing state of the 3D view.

See also

geosoft.gxpy.view, geosoft.gxpy.group

geosoft.gxapi.GXMAP, geosoft.gxapi.GXMVIEW, geosoft.gxapi.GXMVU

Note

Regression tests provide usage examples: map tests

class geosoft.gxpy.map.Map(file_name, mode=1, _internal=False)

Bases: object

Geosoft map files.

A Geosoft map is a container for views. A view has a defined coordinate system (2D or 3D) and contains graphical elements defined relative to the coordinate system of the view. The geosoft.gxpy.view module provides classes and methods for working with individual 2D or 3D views.

Geosoft maps will always have a 2D ‘base’ view, which uses map cm as the coordinate system and is intended for drawing map annotations, such as titles, a scale bar, North arrow and legends. The lower-left corner of the base view at location (0, 0) and the upper-right corner is defined by the media size and may be adjusted to fit the data view.

Geosoft maps will also have one or more data views, each with it’s own defined coordinate system and graphical content. Creating a new map will create one data view, which will become the map’s current_data_view, within which any spatial data drawn by Geosoft 2D drawing applications will be placed. Maps may have more than one data view, including 3D data views, and the current_data_view can be changed to any 2D or 3D view, and subsequent drawing will be placed in that view.

3D views define a 3D spatial volume and accept both 2D and 3D drawing elements. A 3D view will always contain a plane or surface on which 2D elements are drawn, and when a 3D view is the default data view, 2D elements will be drawn to the identified plane or surface. When a 3D view is rendered on a map, which is a flat surface, the view is rendered from the last use point of view. Geosoft map viewing applications allow a user to open a 3D view in a 3D viewer, which provides for 3D viewing, 3D navigation and 3D drawing capabilities.

Constructors:
open() open an existing map
new() create a new map

New in version 9.2.

aggregate_list(mode=0)

list of aggregates on the map as ‘view_name/group_name’

annotate_data_ll(view_name='*data', tick='', offset='', sep='', top=-1, text_def=None, edge_pen=None, grid=3, grid_pen=None)

Annotate the data view axis

Parameters:
  • tick – inner tick size in cm
  • offset – posting offset from the edge in cm
  • sep – separation between annotations, default is calculated from data
  • top – TOP_IN or TOP_OUT (default) for vertical annotations
  • grid –

    Plot grid lines:

    GRID_NONE       no grid
GRID_DOTTED     dotted lines
GRID_CROSSES    crosses at intersections
GRID_LINES      lines
  • grid_pen – color-thickness string

New in version 9.2.

annotate_data_xy(view_name='*data', tick='', offset='', x_sep='', x_dec='', y_sep='', y_dec='', compass=True, top=-1, text_def=None, edge_pen=None, grid=0, grid_pen=None)

Annotate a data view axis

Parameters:
  • view_name – name of the data view to annotate
  • tick – inner tick size in cm
  • offset – posting offset from the edge in cm. The posting edge is adjusted to be outside character height for a subsequent call to an edge annotation. This allows one to annotate both geographic and projected coordinates.
  • top – TOP_IN or TOP_OUT (default) for vertical annotations
  • x_sep – separation between X annotations, default is calculated from data
  • x_dec – X axis label decimals, default is 0
  • y_sep – separation between Y annotations, default is calculated from data
  • y_dec – Y axis label decimals, default is 0
  • compass – True (default) to append compass direction to annotations
  • grid –

    Plot grid lines:

    GRID_NONE       no grid
GRID_DOTTED     dotted lines
GRID_CROSSES    crosses at intersections
GRID_LINES      lines
  • text_def – gxg.Text_def
  • edge_pen – gxg.Pen
  • grid_pen – gxg.Pen

New in version 9.2.

classview(name)

Given a view name that may be a class name (‘*’ prefix), return the view name for that class. if not class decorated, the name passed is returned.

Parameters:name – view name, ‘*data’ will return the name associated with the ‘data’ class, while ‘my_view’ will return ‘my_view’.
Returns:the name, or if a class name, the view name associated with that class.
close()

Close the map and release resources.

commit_changes()

Commit changes to the map.

copy_view(old, new, overwrite=False, copy_all=True)

Copy an existing view into a new view.

Parameters:
  • old – name of the existing view
  • new – name for the new view
  • overwrite – True to overwrite an existing view if it exists
  • copy_all – True to copy content of old to new, false to create an empty new view with the same coordinate system, scale and clipping as the old view.
create_linked_3d_view(view, name='3D', area_on_map=(0, 0, 300, 300))

Create a linked 3D view inside a 2D map to a gxpy.view.View_3d in a 3DV

Parameters:
  • view – gxpy.view.View_3d instance
  • name – name of the linked view to create
  • area_on_map – min_x, min_y, max_x, max_y) placement of view on map in mm

New in version 9.2.

current_base_view

The current default base view which accepts map annotation drawing groups (like titles, North arrow, etc.) from Geosoft methods. This can be set, though Geosoft uses the ‘base’ view in most standard cases.

current_data_view

Current default data view which accepts drawing groups from Geosoft methods that do not explicitly identify a view. Set this to a view that should accept default drawing groups. If this is a 3D view, new groups are placed on the default drawing plane of the view.

current_section_view

The current default base view which accepts drawing commands from Geosoft methods.

delete_view(name)

Delete a view from a map. You cannot delete the last view in a mep.

Parameters:name – name of the view to delete

New in version 9.2.

extent_data_views()

Returns the extent of all data views on the map in map cm.

New in version 9.2.

file_name

full map file path name.

get_class_name(view_class)

Get the view name associated with a class.

Parameters:view_class – desired class

Common view class names are:

'Base'      the base map/figure view, uses map cm
'Data'      the default data view for drawing spatial data.
'Section'   the default section view for things drawn in section

Other class names may be defined, though they are not used by Geosoft.

Returns:view name associated with the class, ‘’ if not defined.

New in version 9.2.

has_view(view)

Returns True if the map contains this view.

map_reference_location(refp, view_name='base')

Return the location of a reference point relative to the current clipping window extent of a view on the map.

Parameters:
  • refp –

    One of:

    REF_BOTTOM_LEFT
REF_BOTTOM_CENTER
REF_BOTTOM_RIGHT
REF_CENTER_LEFT
REF_CENTER
REF_CENTER_RIGHT
REF_TOP_LEFT
REF_TOP_CENTER
REF_TOP_RIGHT
  • view_name – the name of the view, default is the base view which returns the extent in map cm.
Returns:

(x, y) in view units

New in version 9.2.

mdf()

Returns the Map Description File specification for maps that contain both a base view and a data view:

((x_size, y_size, margin_bottom, margin_right, margin_top, margin_left), (scale, units_per_metre, x_origin, y_origin))

metadata

Return the map metadata as a dictionary. Can be set, in which case the dictionary items passed will be added to, or replace existing metadata.

New in version 9.2.

name

map name, base name of the map file

classmethod new(file_name=None, data_area=(0.0, 0.0, 100.0, 100.0), scale=None, coordinate_system=None, media=None, layout=None, fixed_size=False, map_style=None, margins=None, inside_margin=1.0, overwrite=False, no_data_view=False)

Create and open a new Geosoft map.

Parameters:
file_name:Map file name. If not specified a temporary file is created in the instance temporary folder. Use file_name() to get the file name if needed. The temporary map file will be unique and will exist through the life of the Python GX instance, but will be deleted along with all temporary files when the GX loses context.
data_area:(min_x, min_y, max_x, max_y) data area for a 2D data view on the map
scale:required scale, default will fit data to the map media
coordinate_system:
 coordinate system, default is an unknown coordinate system. You may pass a geosoft.gxpy.coordinate_system.Coordinate_system instance, a string descriptor, such as ‘WGS 84 / UTM zone 15N‘, or another valid constructor supported by geosoft.gxpy.coordinate_system.Coordinate_system.
media:media size as a tuple(x_cm, y_cm), or as a standard media name string. If the media name contains ‘portrait’, the media is media aspect will be portrait. Named media sizes are read from media.csv, which includes A4, A3, A2, A1, A0, letter, legal, ledger, A, B, C, D, E. For example media=’A4 portrait’.
layout:MAP_PORTRAIT or MAP_LANDSCAPE, overrides media setting. If the layout is not defined by media or this parameter, the layout is determined by the aspect ratio of the data area.
map_style:STYLE_FIGURE or STYLE_MAP (default). A MAP style is intended for A3 or larger media with a larger right or left margin for map annotations. A FIGURE style is intended for smaller media with a larger bottom margin for a title and limited annotations.
fixed_size:True for fixed media size, if, and only if, a media size is defined. If False, the base view boundary will be reduced to the data view plus margins. If True, the base view boundary is fixed to the media size and margins are adjusted to locate the data view proportionally relative to the requested margins.
margins:(left, right, bottom, top) map margins in map cm. The default for STYLE_MAP is (3, 14, 6, 3), and for figure (1, 4, 1, 1).
inside_margin:additional margin (cm) inside the base view. This margin effectively expands the data_area to allow room for graphical elements related to spatial data near the edge of the defined data area.
overwrite:True to overwrite an existing map. If False and map exists, raises MapException.
no_data_view:True to omit data view during map creation.

New in version 9.2.

north_arrow(location=(1, 2.0, 2.7), direction=None, length=3, inclination=None, declination=None, text_def=None, pen=None)

Add a North arrow to the base view of the map.

Parameters:
  • location – (reference, x_offset, y_offset) reference is a reference point relative to the base map extents (1 through 9) nd the offsets are the offset from that reference point in cm.
  • direction – North direction in degrees azimuth (clockwise from map Y axis). The efault is calculated direction of North at the center of the data view.
  • length – arrow length in cm
  • inclination – magnetic inclination, not shown if not specified
  • declination – magnetic declination, not shown if not specified
  • text_def – gxpy.group.Text_def instance, or None for the default.
  • pen – gxpy.group.Pen instance, or None for the default

New in version 9.2.

classmethod open(file_name)

Open an existing map file.

Parameters:file_name – name of the map file

New in version 9.2.

remove_on_close(remove=True)
Parameters:remove – if True (the default), remove the map file when finished.
scale_bar(location=(1, 5, 2), length=5, sections=None, post_scale=False, text_def=None, pen=None)

Draw a scale bar.

Parameters:
  • location – (ref_point, x_off, y_off) bar location reference point an offset from that point
  • length – maximum scale bar length, default is 5 cm. scale=0.0 will suppress drawing of the bar.
  • sections – number of major sections in the bar, default is determined automatically.
  • post_scale – True to post the actual scale as a string, e.g. ‘1:50,000’. Note that a posted scale is only relevant for printed maps. The default does not post the scale.
  • text_def – gxpy.view.Text_def instance.
  • pen – gxpy.view.Pen instance.

New in version 9.2.

set_class_name(view_class, name)

Set the view name associated with a class.

Parameters:
  • view_class – class name
  • name – name of the view associated with this class.

Common view class names are:

'Base'      the base map/figure view, uses map cm
'Data'      the default data view for drawing spatial data.
'Section'   the default section view for things drawn in section

New in version 9.2.

surround(outer_pen=None, inner_pen=None, gap=0)

Draw a map surround. This will draw a single or a double neat-line around the base view of the map.

Parameters:
  • outer_pen – outer-line pen attributes
  • inner_pen – inner-line pen attributes
  • gap – gap between the outer and inner line in cm. If 0, only the outer line is drawn.

New in version 9.2.

view_list

list of views in the map, both 2D and 3D

view_list_2D

list of 2D views in the map

view_list_3D

list of 3D views in the map

exception geosoft.gxpy.map.MapException

Bases: Exception

Exceptions from geosoft.gxpy.map.

New in version 9.2.

geosoft.gxpy.map.crc_map(mapfile, pix_width=1000)

Return the CRC of a map based on the output bitmap image. :param mapfile: name of the map file :param pix_width: image pixel width - use a higher resolution to test more detail :returns: CRC as an int

New in version 9.2.

geosoft.gxpy.map.delete_files(file_name)

Delete all files associates with this map name. :param file_name:

New in version 9.2.

geosoft.gxpy.map.map_file_name(file_name, file_type='map')

Return a fully resolved map file path using the file name, with .map extyension

Parameters:
  • file_name – file name, with ot without path and/or extension
  • file_type – Geosoft file type, ‘map’ or ‘geosoft_3dv’ expected. Default is ‘map’
Returns:

file name path with extension .map

New in version 9.2.

geosoft.gxpy.map.save_as_image(mapfile, imagefile, type='PNG', pix_width=1000, pix_height=0)

Save a map to an image file :param mapfile: mapfile name :param imagefile: name of the output raster file :param type: one of type list below :param pix_width: image pixel width, if 0 use pix_height only :param pix_height: image pixel height, if 0 use pix_width only :return:

New in version 9.2.

geosoft.gxpy.map.unique_temporary_file_name(temproot, file_type='map')

Create a unique temporary file name.

Parameters:
  • temproot – root base name
  • file_type – Geosoft file type, ‘map’ or ‘geosoft_3dv’ expected. Default is ‘map’

New in version 9.2.