geosoft.gxpy.map submodule¶
Geosoft maps contain one or more 2D and 3D views.
Classes: |
|
---|
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
-
GRID_CROSSES
= 2¶
-
GRID_DOTTED
= 1¶
-
GRID_LINES
= 3¶
-
GRID_NONE
= 0¶
-
GROUP_APPEND
= 1¶
-
GROUP_NEW
= 0¶
-
LIST_2D
= 2¶
-
LIST_3D
= 1¶
-
LIST_ALL
= 0¶
-
MAP_LANDSCAPE
= 0¶
-
MAP_PORTRAIT
= 1¶
-
class
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 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 thegeosoft.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 thecurrent_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 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)¶ 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)¶ 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)¶ 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.
New in version 9.2.
-
crc_image
(pix_width=1000)¶ 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))¶ Create a linked 3D view inside a 2D map to a
geosoft.gxpy.view.View_3d
in a 3DVParameters: - 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.
- view –
-
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 2D groups are placed on the default drawing plane of the view.
-
current_section_view
¶ The current default section view which accepts drawing commands to a section from Geosoft methods.
Can be set.
-
delete_view
(name)¶ 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)¶ 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
()¶ 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, title=None, features=('SCALE', 'NEATLINE', 'ANNOT_XY'), **kwargs)¶ 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
- 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 requirementsNew in version 9.3.
-
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.
-
gxmap
¶ The
geosoft.gxapi.GXMAP
instance handle.
-
has_view
(view)¶ Returns True if the map contains this view.
-
image_file
(imagefile=None, type='PNG', pix_width=1000, pix_height=0)¶ 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
Returns: image file name
New in version 9.3.
-
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
()¶ 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 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.
-
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)¶ 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 bygeosoft.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 an existing map. If False and map exists, raises MapException
.no_data_view: True to create a map without a ‘data’ view. Use geosoft.gxpy.view.View
andgeosoft.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)¶ 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, orNone
for the default. - pen –
geosoft.gxpy.group.Pen
instance, orNone
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 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)¶ 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 (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.
-
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
MapException
¶ Bases:
Exception
Exceptions from
geosoft.gxpy.map
.New in version 9.2.
-
RASTER_FORMAT_BMP
= 'BMP'¶
-
RASTER_FORMAT_EMF
= 'EMF'¶
-
RASTER_FORMAT_EPS
= 'EPS'¶
-
RASTER_FORMAT_GIF
= 'GIF'¶
-
RASTER_FORMAT_JPEG
= 'JPEG'¶
-
RASTER_FORMAT_JPEGH
= 'JPEGH'¶
-
RASTER_FORMAT_JPEGL
= 'JPEGL'¶
-
RASTER_FORMAT_PCX
= 'PCX'¶
-
RASTER_FORMAT_PNG
= 'PNG'¶
-
RASTER_FORMAT_TIFF
= 'TIFF'¶
-
STYLE_FIGURE
= 0¶
-
STYLE_MAP
= 1¶
-
TEXT_ALL_CENTER
= 2¶
-
TEXT_BASE_ALL_CENTER
= 6¶
-
TEXT_BASE_CENTER
= 4¶
-
TEXT_BASE_FIT_BY_CHARACTER_SIZE
= 8¶
-
TEXT_BASE_FIT_BY_CHARACTER_WIDTH
= 7¶
-
TEXT_BASE_LEFT
= 3¶
-
TEXT_BASE_RIGHT
= 5¶
-
TEXT_BOTTOM_CENTER
= 0¶
-
TEXT_BOTTOM_LEFT
= -1¶
-
TEXT_BOTTOM_RIGHT
= 1¶
-
TOP_IN
= 1¶
-
TOP_OUT
= -1¶
-
VIEW_BASE
= 0¶
-
VIEW_DATA
= 1¶
-
VIEW_NAME_SIZE
= 2080¶
-
WRITE_NEW
= 1¶
-
WRITE_OLD
= 2¶
-
crc_map
(mapfile, pix_width=1000)¶ 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)¶ Delete all files associated with this map name.
Parameters: file_name – New in version 9.2.
-
map_file_name
(file_name, file_type='map')¶ 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)¶ 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
New in version 9.2.