geosoft.gxpy.map submodule¶

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

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.

Classes

Map: map class

Constants

WRITE_NEW: geosoft.gxapi.MAP_WRITENEW
WRITE_OLD: geosoft.gxapi.MAP_WRITEOLD
LIST_ALL: geosoft.gxapi.MAP_LIST_MODE_ALL
LIST_3D: geosoft.gxapi.MAP_LIST_MODE_3D
LIST_2D: geosoft.gxapi.MAP_LIST_MODE_NOT3D
VIEW_NAME_SIZE: 2080
TEXT_BOTTOM_LEFT: -1
TEXT_BOTTOM_CENTER: 0
TEXT_BOTTOM_RIGHT: 1
TEXT_ALL_CENTER: 2
TEXT_BASE_LEFT: 3
TEXT_BASE_CENTER: 4
TEXT_BASE_RIGHT: 5
TEXT_BASE_ALL_CENTER: 6
TEXT_BASE_FIT_BY_CHARACTER_WIDTH: 7
TEXT_BASE_FIT_BY_CHARACTER_SIZE: 8
MAP_LANDSCAPE: 0
MAP_PORTRAIT: 1
TOP_IN: 1
TOP_OUT: -1
GRID_NONE: 0
GRID_DOTTED: 1
GRID_CROSSES: 2
GRID_LINES: 3
GROUP_NEW: 0
GROUP_APPEND: 1
VIEW_BASE: 0
VIEW_DATA: 1
STYLE_FIGURE: 0
STYLE_MAP: 1
RASTER_FORMAT_EMF: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_EMF
RASTER_FORMAT_BMP: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_BMP
RASTER_FORMAT_JPEGL: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_JPEGL
RASTER_FORMAT_JPEG: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_JPEG
RASTER_FORMAT_JPEGH: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_JPEGH
RASTER_FORMAT_GIF: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_GIF
RASTER_FORMAT_PCX: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_PCX
RASTER_FORMAT_PNG: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_PNG
RASTER_FORMAT_EPS: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_EPS
RASTER_FORMAT_TIFF: geosoft.gxapi.MAP_EXPORT_RASTER_FORMAT_TIFF

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

Note

Regression tests provide usage examples: map tests

class Map(file_name, mode=1, _internal=False, gxmap=None)[source]¶

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 groups of 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, and the geosoft.gxpy.group modules contains classes that deal with drawing groups..

Geosoft maps will always have a 2D ‘base’ view 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 ia at location (0, 0) and the upper-right corner is defined by the media size and may be adjusted to fit the data view.

When drawing to the base view the native unit is millimetres and locations and graphic entity sizes are assumed to be mm. When drawing to the map using map methods the units are in map cm, including graphic entity scaling.

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.

__init__(file_name, mode=1, _internal=False, gxmap=None)[source]¶: Initialize self. See help(type(self)) for accurate signature.

aggregate_list(mode=0)[source]¶

List of all aggregates in the map as ‘view_name/group_name’ (mode=0) or ‘view_name/group_name/layer’ (mode=1).

..versionadded:: 9.2

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

Annotate the 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.
sep – separation between annotations, default is calculated from data
top – TOP_IN or TOP_OUT (default) for vertical annotations

grid –

GRID_NONE       no grid
GRID_DOTTED     dotted lines
GRID_CROSSES    crosses at intersections
GRID_LINES      lines

text_def – geosoft.gxpy.group.Text_def, units cm
edge_pen – geosoft.gxpy.group.Pen, units cm
grid_pen – geosoft.gxpy.group.Pen, units cm

New in version 9.2.

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

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 map 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 to append compass direction to annotations, default True if known coordinate system.

grid –

GRID_NONE       no grid
GRID_DOTTED     dotted lines
GRID_CROSSES    crosses at intersections
GRID_LINES      lines

text_def – geosoft.gxpy.group.Text_def
edge_pen – geosoft.gxpy.group.Pen
grid_pen – geosoft.gxpy.group.Pen

New in version 9.2.

classview(name)[source]¶

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()[source]¶: Close the map and release resources.

commit_changes()[source]¶: Commit changes to the map.

copy_view(old, new, overwrite=False, copy_all=True)[source]¶

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.

New in version 9.2.

crc_image(pix_width=1000)[source]¶

Return the CRC of a map based on the output bitmap image.

Parameters: pix_width – image pixel width - use a higher resolution to test more detail
Returns: CRC as an int

New in version 9.3.

create_linked_3d_view(view, name='3D', area_on_map=0, 0, 300, 300)[source]¶

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

Parameters

view – geosoft.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.

property current_base_view¶

Name of 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.

property current_data_view¶

Name of the current default data view which accepts drawing groups from Geosoft methods that do not explicitly identify a view.

Set this to a view name that should accept default drawing groups.

If this is a 3D view, new 2D groups are placed on the default drawing plane of the view.

property current_section_view¶

Name of the current default section view which accepts drawing commands to a section from Geosoft methods.

Can be set.

delete_view(name)[source]¶

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

Parameters: name – name of the view to delete

New in version 9.2.

export_geotiff(geotiff, dpi=96)[source]¶

Export map as a GeoTIFF image

Parameters

geotiff – GeoTIFF file name
dpi – resolution in dots-per-inch, default is common screen resolution of 96 dpi.

New in version 9.3.

extent_data_views()[source]¶: Returns the extent of all data views on the map in map cm.

New in version 9.2.

classmethod figure(data_area, file_name=None, overwrite=False, title=None, features='SCALE', 'NEATLINE', 'ANNOT_XY', **kwargs)[source]¶

Create a figure-style map.

Parameters

data_area – the area extend for the data view as (xmin, ymin, xmax, ymax)
file_name – map file name, default creates a temporary map
overwrite – True to overwrite file should it exist
title – figure title

features –

list of features to place on the map, default is (‘SCALE’, ‘NEATLINE’, ‘ANNOT_XY’)

’ALL’	all features
’SCALE’	show a scale bar
’NEATLINE’	draw a neat-line around the image
’ANNOT_XY’	annotate map coordinates
’ANNOT_LL’	annotate map Latitude, Longitude

Returns

Map instance with ‘base’ and ‘data’ views.

See also

Map.new arguments to modify map layout requirements

New in version 9.3.

property file_name¶: full map file path name.

classmethod from_gxapi(gxmap)[source]¶

Instantiate Map from gxapi instance.

Parameters: gxmap – a gxapi.CGXMAP

New in version 9.9.

get_class_name(view_class)[source]¶

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.

property gxmap¶: The geosoft.gxapi.GXMAP instance handle.

has_view(view)[source]¶: Returns True if the map contains this view.

image_file(imagefile=None, type='PNG', pix_width=1000, pix_height=0, pix_32_bit=False)[source]¶

Save a map to an image file

Parameters

mapfile – map or geosoft_3dv file name
imagefile – name of the output raster file, default will be a temporary png file.
type – one of the RASTER_FORMAT types, default`RASTER_FORMAT_PNG`
pix_width – image pixel width, if 0 use pix_height only
pix_height – image pixel height, if 0 use pix_width only
pix_32_bit – make 32-bit image (with 8-bit alpha background)

Returns

image file name

New in version 9.3.

property map_scale¶

Map scale, based on the current default “data” view if it exists.

WARNING: If the “data” view is open this returns 1000. TODO - add test for open views.

Can be set, but must not be called if any views are open. Resetting the map scale changes the scale of all views in the map.

mdf()[source]¶

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))

property metadata¶: Return the map file 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.

property name¶: map name, which is to root 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)[source]¶

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 string contains ‘portrait’, the 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 map file should it exist
no_data_view: True to create a map without a ‘data’ view. Use geosoft.gxpy.view.View and geosoft.gxpy.view.View_3d to add data views to a map.

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)[source]¶

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 map 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 on the map.
inclination – magnetic inclination, not shown if not specified
declination – magnetic declination, not shown if not specified
text_def – geosoft.gxpy.group.Text_def instance, or None for the default.
pen – geosoft.gxpy.group.Pen instance, or None for the default

New in version 9.2.

classmethod open(file_name)[source]¶

Open an existing map file.

Parameters: file_name – name of the map file

New in version 9.2.

remove_on_close(remove=True)[source]¶

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)[source]¶

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 in map cm, default is 5 cm. 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 – geosoft.gxpy.view.Text_def instance.
pen – geosoft.gxpy.view.Pen instance.

New in version 9.2.

set_class_name(view_class, name)[source]¶

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)[source]¶

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 (cm)
inner_pen – inner-line pen attributes (cm)
gap – gap between the outer and inner line in cm. If 0, only the outer line is drawn.

New in version 9.2.

property view_list¶: list of views in the map, both 2D and 3D

property view_list_2D¶: list of 2D views in the map

property view_list_3D¶: list of 3D views in the map

exception MapException(message)[source]¶

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.map.

New in version 9.2.

crc_map(mapfile, pix_width=1000)[source]¶

Return the CRC of a map based on the output bitmap image.

Parameters

mapfile – name of the map file
pix_width – image pixel width - use a higher resolution to test more detail

Returns

CRC as an int

New in version 9.2.

delete_files(file_name)[source]¶

Delete all files associated with this map name.

Parameters: file_name –

New in version 9.2.

map_file_name(file_name, file_type='map')[source]¶

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

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.

save_as_image(mapfile, imagefile=None, type='PNG', pix_width=1000, pix_height=0, pix_32_bit=False)[source]¶

Save a map file to an image file

Parameters

mapfile – map or geosoft_3dv file name
imagefile – name of the output raster file, default is a temporary png file.
type – one of the RASTER_FORMAT types, default`RASTER_FORMAT_PNG`
pix_width – image pixel width, if 0 use pix_height only
pix_height – image pixel height, if 0 use pix_width only
pix_32_bit – make 32-bit image (with 8-bit alpha background)

New in version 9.2.