geosoft.gxpy.view submodule¶

Views, which can be 2D or 3D, contain groups of graphical elements that can be displayed to a user in a Geosoft Map viewer or a Geosoft 3D viewer. Geosoft maps can contain any number of 2D or 3D views.

Views contain one or more geosoft.gxpy.group.Group instances. 2D views can contain 2D groups, while 3D views can contain both 2D and 3D groups.

Classes:

`View`:	single 2D plane view
`View_3d`:	3D view in a `geosoft.3dv` file, or a 3D view on a 2D map.
`CrookedPath`:	defines the path for a crooked section.

Both 2D and 3D views can be placed on a geosoft.gxpy.map.Map, though 3D views are stored in a geosoft_3dv file which can also be viewed separately from a map.

Constants:

UNIT_VIEW_UNWARPED:
READ_ONLY:	`geosoft.gxapi.MVIEW_READ`
WRITE_NEW:	`geosoft.gxapi.MVIEW_WRITENEW`
WRITE_OLD:	`geosoft.gxapi.MVIEW_WRITEOLD`
UNIT_VIEW:	0
UNIT_MAP:	2
	3
GROUP_ALL:	0
GROUP_MARKED:	1
GROUP_VISIBLE:	2
GROUP_AGG:	3
GROUP_CSYMB:	4
GROUP_VOXD:	5
GROUP_VECTORVOX:
	6
GROUP_SURFACE:	7
EXTENT_ALL:	`geosoft.gxapi.MVIEW_EXTENT_ALL`
EXTENT_VISIBLE:	`geosoft.gxapi.MVIEW_EXTENT_VISIBLE`
EXTENT_CLIPPED:	`geosoft.gxapi.MVIEW_EXTENT_CLIP`

geosoft.geosoft.gxapi.GXMVIEW

Note

Regression tests provide usage examples: View tests

class CrookedPath(xy_path, log_z=False, **kw)¶

Bases: geosoft.gxpy.geometry.Geometry

Description of a crooked (x, y) path that defines a crooked-section view, or a crooked-section grid.

New in version 9.4.

distances¶: Distances along path points as an array (npoints) starting at 0.

extent¶: Object extent as a Point2 instance.

ppoint¶: Path trace as a geosoft.gxpy.geometry.PPoint instance.

set_in_geosoft_ipj(coordinate_system)¶

Set the crooked-path in the geosoft.gxapi.GXIPJ instance of the coordinate system.

Geosoft stores crooked-path information in the GXIPJ, from which views are able to

Parameters:	coordinate_system –

New in version 9.4.

xy¶: Path trace as an array (npoints, 2).

class View(map, name='_unnamed_view', mode=2, coordinate_system=None, map_location=(0, 0), area=(0, 0, 30, 20), scale=100, copy=None, **kwargs)¶

Bases: geosoft.gxpy.geometry.Geometry

Geosoft view class.

Constructors:

`open`:	open an existing view in a map
`new`:	create a new view in a map

New in version 9.2.

add_child_files(file_list)¶

Add files to the list of child files for this view.

Parameters:	file_list – file, or a list of files to add

aspect¶: view aspect ratio, usually 1.

clip¶: Current view clip mode for groups, applies to groups following in this stream. Can be set.

New in version 9.3.1.

close()¶: Close a view. Use to close a view when working outside of a with ... as: construct.

New in version 9.2.

coordinate_system¶: geosoft.gxpy.coordinate_system.Coordinate_system instance of the view.

crooked_path()¶: Return the CrookedPath instance for a crooked-path view.

delete_group(group_name)¶

Delete a group from a map. Nothing happens if the view does not contain this group.

Parameters:	group_name – Name of the group to delete.

New in version 9.2.

extent¶: View clip extent as a geosoft.gxpy.geometry.Point2.

New in version 9.3.1.

extent_all¶: extent of all groups in the view as (x_min, y_min, x_max, y_max)

extent_clip¶: clip extent of the view as (x_min, y_min, x_max, y_max)

extent_group(group, unit=0)¶

Extent of a group

Parameters:	group – group name unit – units: UNIT_VIEW UNIT_MAP
Returns:	extent as (x_min, y_min, x_max, y_max)

extent_map_cm(extent=None)¶

Return an extent in map cm.

Parameters:	extent – tuple returned from one of the extent properties. Default is `extent_clip`.

New in version 9.2.

extent_visible¶: extent of visible groups in the view as (x_min, y_min, x_max, y_max)

get_class_name(view_class)¶

Get the name associated with a view class.

Parameters:	view_class – desired class in this view

Common view class names are:

'Plane'     the name of the default 2D drawing plane
'Section'   a section view

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

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

New in version 9.2.

group_list¶: list of groups in this view

group_list_agg¶: list of geosoft.gxapi.GXAGG groups in this view

group_list_csymb¶: list of geosoft.gxapi.GXCSYMB groups in this view

group_list_marked¶: list of marked groups in this view

group_list_surface¶: list of surface groups in this view

group_list_vectorvoxel¶: list of voxel groups in this view

group_list_visible¶: list of visible groups in this view

group_list_voxel¶: list of voxel groups in this view

guid¶: The view GUID.

New in version 9.3.

gxview¶: The geosoft.gxapi.GXIPJ instance handle.

has_group(group)¶: Returns True if the map contains this group.

is_3d¶: True if this is a 3D view

is_crooked_path¶: True if this grid follows a crooked path section.

locate(coordinate_system=None, map_location=None, area=None, scale=None)¶

Locate and scale the view on the map.

Parameters:

coordinate_system:
	coordinate system as a class:`gxpy.coordinate_system.Coordinate_system` instance, or one of the Coordinate_system constructor types.
map_location:	New (x, y) view location on the map, in map cm.
area:	New (min_x, min_y, max_x, max_y) area in view units
scale:	New scale in view units per map metre, either as a single value or (x_scale, y_scale), defaults to the current x scale.

New in version 9.2.

lock¶: True if the view is locked by a group. Only one group may hold a lock on a view at the same time. When drawing with groups you should use a with gxgrp.Draw(...) as g: which will ensure group locks are properly created and released.

map¶: geosoft.gxpy.map.Map instance that contains this view.

map_cm_to_view(x, y=None)¶

Returns the location of this point on the map (in cm) to the view location in view units.

Parameters:	x – x, or a tuple (x,y), in map cm y – y if x is not a tuple

New in version 9.2.

map_scale¶

Map scale for this view.

Can be set, in which case the entire view will move on the map.

mdf(base_view=None)¶

Returns the Map Description File specification for this view as a data view.

Parameters:	base_view – name of the base view on the map from which to calculate margins. If not specified only the left and bottom margin is calculated based on the view clip minimum location and the right and top margins will be 0.
Returns:	((x_size, y_size, margin_bottom, margin_right, margin_top, margin_left), (scale, units_per_metre, x_origin, y_origin))

metadata¶: Return the view/map metadata as a dictionary. Can be set, in which case the dictionary items passed will be added to, or replace existing metadata. All views on a map share the metadata with the map.

New in version 9.2.

name¶: Name of the view

classmethod new(map=None, name='_unnamed_view', coordinate_system=None, map_location=(0, 0), area=(0, 0, 30, 20), scale=100, copy=None, crooked_path=None)¶

Create a new view on a map.

Parameters:

coordinate_system:
map:	`geosoft.gxpy.map.Map` instance, if not specified a new unique default map is created and deleted when this session finished.
name:	view name, default is “_unnamed_view”.
	coordinate system as a `geosoft.gxpy.coordinate_system.Coordinate_system` instance, or one of the Coordinate_system constructor types.
map_location:	(x, y) view location on the map, in map cm, default (0, 0)
area:	(min_x, min_y, max_x, max_y) area in view units, default (0, 0, 30, 20)
scale:	Map scale if a coordinate system is defined. If the coordinate system is not defined this is view units per map metre.
copy:	name of a view to copy into the new view.
crooked_path:	provide a `CrookedPath` instance to create a section view along a wandering path. Should the coordinate system already contain a crooked path it will be replaced.

New in version 9.2.

classmethod open(map, view_name, read_only=False)¶

Open an en existing view on a map.

Parameters:	map – `geosoft.gxpy.map.Map` view_name – name of the view read_only – True to open read-only

New in version 9.2.

scale¶: map scale for the view

set_class_name(view_class, name)¶

Set the name associated with a class.

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

Common view class names are:

'Plane'     the name of the default 2D drawing plane
'Section'   a section view

New in version 9.2.

units_name¶: name of the view distance units

units_per_map_cm¶: view units per map cm. (eg. a view in ft, with a scale of 1:12000 returns 393.7 ft/cm)

units_per_metre¶: view units per view metres (eg. a view in ‘ft’ will be 3.28084)

view_to_map_cm(x, y=None)¶

Returns the location of this point on the map in the view.

Parameters:	x – x, or a tuple (x,y), in view units y – y if x is not a tuple

New in version 9.2.

exception ViewException(message)¶

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.view.

New in version 9.2.

class View_3d(file_name, mode, _internal=False, **kwargs)¶

Bases: geosoft.gxpy.view.View

Geosoft 3D views, which contain 3D drawing groups.

Geosoft 3D views are stored in a file with extension geosoft_3dv. A 3d view is required to draw 3D elements using geosoft.gxpy.group.Draw_3d, which must be created from a geosoft.gxpy.view.View_3d instance.

3D views also contain 2D drawing planes on which geosoft.gxpy.group.Draw groups are placed. A default horizontal plane at elevation 0, named ‘plane_0’ is created when a new 3d view is created.

Planes are horizontal and flat by default, but can be provided a grid that defines the plane surface relief, which is intended for creating things like terrain surfaces on which 2d graphics are rendered.

Planes can also be oriented within the 3D space to create sections, or for other more esoteric purposes.

Constructors:

`open()`	open an existing geosoft_3dv
`new()`	create a new geosoft_3dv

New in version 9.2.

add_extent(extent)¶

Expand current extent to include this extent. :param extent: extent as a geosoft.gxpy.geometry.Geometry or Point2 constructor

TODO: review once issue #75 is resolved.

New in version 9.3.1.

close()¶: close the view, releases resources.

current_3d_drawing_plane¶: Current drawing plane name in a 3D view, None if not defined. Can be set to a plane number or name.

current_3d_drawing_plane_number¶: The current drawing plane number, can be set.

delete_plane(plane)¶

Delete a plane, and all content

Parameters:	plane – plane number or plane name

New in version 9.3.1.

extent¶

Extent of 3D objects in this view.

Returns:	`geosoft.gxpy.geometry.Point2` instance

TODO: review once issue #75 is resolved.

New in version 9.3.1.

file_name¶: the geosoft_3dv file name

groups_on_plane_list(plane=0)¶

List of groups on a plane.

Parameters:	plane – name of the plane or plane number
Returns:	list of groups on the plane

New in version 9.2.

has_plane(plane)¶

True if the view contains plane

Parameters:	plane – name of the plane
Returns:	True if the plane exists in the view

New in version 9.2.

name¶: the view name

classmethod new(file_name=None, area_2d=None, overwrite=False, **kwargs)¶

Create a new 3D view.

Parameters:	file_name – name for the new 3D view file (.geosoft_3dv added). If not specified a unique temporary file is created. area_2d – 2D drawing extent for the default 2D drawing plane overwrite – True to overwrite an existing 3DV

New in version 9.2.

new_drawing_plane(name, rotation=(0.0, 0.0, 0.0), offset=(0.0, 0.0, 0.0), scale=(1.0, 1.0, 1.0))¶

Create a new drawing plane in a 3d view.

Parameters:	name – name of the plane, overwritten if it exists rotation – plane rotation as (rx, ry, rz), default (0, 0, 0) offset – (x, y, z) offset of the plane, default (0, 0, 0) scale – (xs, ys, zs) axis scaling, default (1, 1, 1)

classmethod open(file_name, **kw)¶

Open an existing geosoft_3dv file.

Parameters:	file_name – name of the geosoft_3dv file

New in version 9.2.

plane_list¶: list of drawing planes in the view

plane_name(plane)¶: Return the name of a numbered plane

plane_number(plane)¶: Return the plane number of a plane, or None if plane does not exist.

set_plane_relief_surface(surface_grid_name, refine=2, base=0, scale=1, min=None, max=None)¶

Establish a relief surface for the current plane based on a grid.

Parameters:	surface_grid_name – grid file name refine – relief refinement between 1 (low) and 4 (high). Default is 2. base – base value in grid, will be at z=0. Default is 0. scale – scale to apply to grid after removing base, default is 1. min – minimum clip in unscaled grid values max – maximum clip in unscaled grid values

New in version 9.3.

delete_files(v3d_file)¶

Delete a v3d file with associated files. Just calls geosoft.gxpy.map.delete_files. The view must be closed.

Parameters:	v3d_file – View_3d file name

New in version 9.3.1.