geosoft.gxpy.group submodule¶

A Geosoft View (geosoft.gxpy.view.View or geosoft.gxpy.view.View_3d) contains graphical elements as Group instances. Groups are named and are available to a user in a Geosoft viewer, which allows groups to be turned on or off, modify the transparency, or be deleted.

2D views can only accept 2D groups, while a 3D view can accept both 2D and 3D groups. When a 2D group is placed in a 3D view, the group is placed on a the active plane inside the 3D view

Classes:

`Color_symbols_group`:
`Group`:	base class for named rendering groups in 2D and 3D views.
`Draw`:	2D drawing group, handles 2D drawing to a view or plane in a 3D view
`Draw_3d`:	3D grawing group for 3D objects placed in a 3d view
	group for 2D symbols rendered based on data values
`Aggregate_group`:
	group that contains a `geosoft.gxpy.agg.Aggregate_image` instance
`Color`:	colour definition
`Color_map`:	maps values to colors
`Pen`:	pen definition, includes line colour, thickness and pattern, and fill.
`Text_def`:	defined text characteristics
`VoxDisplayGroup`:
	a ‘geosoft.gxpy.vox.VoxDisplay` in a `geosoft.gxpy.view.View_3d`

Constants:

GROUP_NAME_SIZE:
	`geosoft.gxpy.view.VIEW_NAME_SIZE`
NEW:	`geosoft.gxapi.MVIEW_GROUP_NEW`
APPEND:	`geosoft.gxapi.MVIEW_GROUP_APPEND`
READ_ONLY:	max(NEW, APPEND) + 1
REPLACE:	READ_ONLY + 1
SMOOTH_NONE:	`geosoft.gxapi.MVIEW_SMOOTH_NEAREST`
SMOOTH_CUBIC:	`geosoft.gxapi.MVIEW_SMOOTH_CUBIC`
SMOOTH_AKIMA:	`geosoft.gxapi.MVIEW_SMOOTH_AKIMA`
TILE_RECTANGULAR:
	`geosoft.gxapi.MVIEW_TILE_RECTANGULAR`
TILE_DIAGONAL:	`geosoft.gxapi.MVIEW_TILE_DIAGONAL`
TILE_TRIANGULAR:
	`geosoft.gxapi.MVIEW_TILE_TRIANGULAR`
TILE_RANDOM:	`geosoft.gxapi.MVIEW_TILE_RANDOM`
UNIT_VIEW:	0
UNIT_MAP:	2
UNIT_VIEW_UNWARPED:
	3
GRATICULE_DOT:	0
GRATICULE_LINE:	1
GRATICULE_CROSS:
	2
LINE_STYLE_SOLID:
	1
LINE_STYLE_LONG:
	2
LINE_STYLE_DOTTED:
	3
LINE_STYLE_SHORT:
	4
LINE_STYLE_LONG_SHORT_LONG:
	5
LINE_STYLE_LONG_DOT_LONG:
	6
SYMBOL_NONE:	0
SYMBOL_DOT:	1
SYMBOL_PLUS:	2
SYMBOL_X:	3
SYMBOL_BOX:	4
SYMBOL_TRIANGLE:
	5
SYMBOL_INVERTED_TRIANGLE:
	6
SYMBOL_HEXAGON:	7
SYMBOL_SMALL_BOX:
	8
SYMBOL_SMALL_DIAMOND:
	9
SYMBOL_CIRCLE:	20
SYMBOL_3D_SPHERE:
	0
SYMBOL_3D_CUBE:	1
SYMBOL_3D_CYLINDER:
	2
SYMBOL_3D_CONE:	3
FONT_WEIGHT_ULTRALIGHT:
	1
FONT_WEIGHT_LIGHT:
	2
FONT_WEIGHT_MEDIUM:
	3
FONT_WEIGHT_BOLD:
	4
FONT_WEIGHT_XBOLD:
	5
FONT_WEIGHT_XXBOLD:
	6
CMODEL_RGB:	0
CMODEL_CMY:	1
CMODEL_HSV:	2
C_BLACK:	67108863
C_RED:	33554687
C_GREEN:	33619712
C_BLUE:	50266112
C_CYAN:	50331903
C_MAGENTA:	50396928
C_YELLOW:	67043328
C_GREY:	41975936
C_LT_RED:	54542336
C_LT_GREEN:	54526016
C_LT_BLUE:	50348096
C_LT_CYAN:	50331712
C_LT_MAGENTA:	50348032
C_LT_YELLOW:	54525952
C_LT_GREY:	54542400
C_GREY10:	51910680
C_GREY25:	54542400
C_GREY50:	41975936
C_WHITE:	50331648
C_TRANSPARENT:	0
REF_BOTTOM_LEFT:
	0
REF_BOTTOM_CENTER:
	1
REF_BOTTOM_RIGHT:
	2
REF_CENTER_LEFT:
	3
REF_CENTER:	4
REF_CENTER_RIGHT:
	5
REF_TOP_LEFT:	6
REF_TOP_CENTER:	7
REF_TOP_RIGHT:	8
GROUP_ALL:	0
GROUP_MARKED:	1
GROUP_VISIBLE:	2
GROUP_AGG:	3
GROUP_CSYMB:	4
GROUP_VOXD:	5
LOCATE_FIT:	`geosoft.gxapi.MVIEW_RELOCATE_FIT`
LOCATE_FIT_KEEP_ASPECT:
	`geosoft.gxapi.MVIEW_RELOCATE_ASPECT`
LOCATE_CENTER:	`geosoft.gxapi.MVIEW_RELOCATE_ASPECT_CENTER`
COLOR_BAR_RIGHT:
	0
COLOR_BAR_LEFT:	1
COLOR_BAR_BOTTOM:
	2
COLOR_BAR_TOP:	3
COLOR_BAR_ANNOTATE_RIGHT:
	1
COLOR_BAR_ANNOTATE_LEFT:
	-1
COLOR_BAR_ANNOTATE_TOP:
	1
COLOR_BAR_ANNOTATE_BOTTOM:
	-1
CYLINDER_OPEN:	0
CYLINDER_CLOSE_START:
	1
CYLINDER_CLOSE_END:
	2
CYLINDER_CLOSE_ALL:
	3
POINT_STYLE_DOT:
	0
POINT_STYLE_SPHERE:
	1
LINE3D_STYLE_LINE:
	0
LINE3D_STYLE_TUBE:
	1
LINE3D_STYLE_TUBE_JOINED:
	2
SURFACE_FLAT:	`geosoft.gxapi.MVIEW_DRAWOBJ3D_MODE_FLAT`
SURFACE_SMOOTH:	`geosoft.gxapi.MVIEW_DRAWOBJ3D_MODE_SMOOTH`

Note

Regression tests provide usage examples: group drawing tests

See also

geosoft.gxpy.view, geosoft.gxpy.map

geosoft.gxapi.GXMVIEW, geosoft.gxapi.GXMVU

class Aggregate_group(view, group_name, mode)¶

Bases: geosoft.gxpy.group.Group

Aggregate group in a view

Constructors:

`open()`	open an existing aggregate group
`new()`	create a new aggregate group

Properties:

name:	aggregate group name
agg:	`gxpy.agg.Aggregate_image` instance

New in version 9.2.

classmethod new(view, agg, name=None, mode=3, clip=True)¶

Create a new aggregate group in a view.

Parameters:	view – `geosoft.gxpy.view.View` or `geosoft.gxpy.view.View_3d` instance agg – `geosoft.gxpy.agg.Aggregate` instance. name – group name, default is the aggregate name mode – REPLACE (default) or NEW, which creates a unique name if the group exists clip – True to clip the agregare to the view clip limits

New in version 9.2.

Changed in version 9.3.1: added clip mode

classmethod open(view, group_name)¶

Open an existing aggregate group in a view.

Parameters:	view – `geosoft.gxpy.view.View` or `geosoft.gxpy.view.View_3d` instance group_name – group name (or number)

New in version 9.2.

class Color(color, model=0)¶

Bases: object

Colours, which are stored as a 32-bit color integer.

Parameters:

color –
string descriptor (eg. ‘R255G0B125’), color letter R, G, B, C, M, Y, H, S or V.; tuple (r, g, b), (c, m, y) or (h, s, v), each item defined in the range 0 to 255; 32-bit color number, which can be an item selected from the following list:
```
C_BLACK
C_RED
C_GREEN
C_BLUE
C_CYAN
C_MAGENTA
C_YELLOW
C_GREY
C_LT_RED
C_LT_GREEN
C_LT_BLUE
C_LT_CYAN
C_LT_MAGENTA
C_LT_YELLOW
C_LT_GREY
C_GREY10
C_GREY25
C_GREY50
C_WHITE
C_TRANSPARENT
```

model –

model of the tuple:

CMODEL_RGB (default)
CMODEL_CMY
CMODEL_HSV

New in version 9.2.

adjust_brightness(brightness)¶: Return a Color instance adjusted for brightness.

New in version 9.2.

cmy¶: color as an (cyan, magenta, yellow) tuple, can be set

int_value¶: color as a 32-bit color integer, can be set

rgb¶: color as an (red, green, brue) tuple, can be set

class Color_map(cmap=None, title=None, unit_of_measure=None)¶

Bases: object

Color map for establishing data color mapping for things like aggregates and color symbols.

Parameters:

cmap –
the name of a Geosoft color map file (tbl, .zon, .itr, .agg) from which to establish the initial colors. If the file does not have zone values, which is the case for a tbl file, the Color_map will be uninitialized and you can use one of the set methods to establish zone values.

You can also provide an int, which will create an uninitialized map of the the specified length, or a geosoft.gxapi.GXITR instance.

If not specified the Geosoft default color table is used.
title – Color map title which is displayed in the color map legend.
unit_of_measure – Unit of measure to be displayed in a color map legend.

New in version 9.2.

Changed in version 9.3: changed units to unit_of_measure for consistency across gxpy

brightness¶: Brightness is a value between -1 (black) and +1 (white), The default is 0. :returns: brightness, -1 to +1

New in version 9.2.

color_map¶: list of zone limts, colours in the color map

color_map_rgb¶: list of zone limits and (red, green, blue) colours

color_of_value(value)¶

Return the gxg.Color of a value. The mapping is determined with exclusive minima, inclusive maxima for each color level. Values <= level [0] are assigned the [0] color, and values greater than the the [n-2] level are assigned the [n-1] color.

Parameters:	value – data value
Returns:	`Color` instance

New in version 9.2.

data_limits¶

Data limits of color map

The limit values are for information only. Applications will assume that these values represent the largest and smallest values in a population represented by the ITR. If they are dummy, they have not been set.

Returns:	min/max tuple

New in version 9.4.

initialized¶: Returns True if the color_map has been initialized to have zone boundaries.

New in version 9.2.

length¶: Number of color zones in the map.

model_type¶: Geosoft colour model used in the Geosoft geosoft.gxapi.GXITR

save_file(file_name=None)¶

Save to a Geosoft file, tbl, itr or zon. If the file_name does not have an extension and the color_map has not been initialized a tbl file is created (colors only), otherwise a itr is created, which contains both zone boundaries and colors.

Parameters:	file_name – file name, if None a temporary file is created

This is useful for gxapi methods that require a colour map to be loaded from a file. Say you cave a Color_map instance named cmap and you want to create a GXCSYMB instance, which requires a colur map file:

cs = gxapi.GXCSYMB.create(cmap.save_file())

New in version 9.2.

set_linear(minimum, maximum, inner_limits=True, contour_interval=None)¶

Set the map boundaries based on a linear distribution between minimum and maximum.

Parameters:

minimum – minimum
maximum – maximum
inner_limits – True if the range specifies the inner limits of the color mappings, in which case values less than or equal to the minimum are mapped to the first color and colors greater than the maximum are mapped to the last color. If False, the minimum and maximum are at the outer-edges of the color map.
contour_interval – align color edges on this interval, which is useful for matching colors contour map, for example. The color map will be reduced in size by thinning of unneeded colors if necessary.

New in version 9.2.

set_logarithmic(minimum, maximum, contour_interval=None)¶

Set the color boundaries based on a logarithmic distribution between minimum and maximum.

Parameters:	minimum – minimum, must be > 0 maximum – maximum contour_interval – align color edges on this interval, 10 for powers of 10. unneeded colors if necessary.

New in version 9.2.

set_normal(standard_deviation, mean, expansion=1.0, contour_interval=None)¶

Set the color boundaries using a normal distribution around a mean.

Parameters:	standard_deviation – the standard deviation of the normal distribution. mean – maximum expansion – expand by this factor around the mean contour_interval – align color edges on this interval, 10 for powers of 10. unneeded colors if necessary.

New in version 9.2.

set_sequential(start=0, increment=1)¶

Set color map zones based on a start and increment between each color zone.

Parameters:	start – minimum zone boundary, values <= this value will have the first color increment – increment between each color.

New in version 9.2.

title¶: Title, usually the name of the data from which the color bar was made or is intended. None if no title

New in version 9.2.

unit_of_measure¶: Data unit of measure for the data from which the color bar was made or is intended. None if the unit of measure is unknown.

New in version 9.2.

class Color_symbols_group(view, group_name, **kwargs)¶

Bases: geosoft.gxpy.group.Group

Data represented as colored symbols based on a Color_map.

Constructors:

`new()`	create a new symbol group in a view
`open()`	open an existing symbol group in a view

color_map()¶: Return the geosoft.gxpy.group.Color_map of a color symbol group.

New in version 9.3.

classmethod new(view, name, data, color_map, symbol_def=None, symbol=20, mode=3, **kwargs)¶

Create a new color symbols group with color mapping. If the group exists a new unique name is constructed.

Parameters:

view – the view in which to place the group
name – group name
data – 2d numpy data array [[x, y, value], …] or an iterable that yields ((x, y), value), or ((x, y, z), value, ...). Only the first value is used, an in the case of an iterable that yields (x, y, z) the z is ignored.
color_map – symbol fill color Color_map. Symbols are filled with the color lookup using data.
symbol_def – Text_def defines the symbol font to use, normally symbols.gfn is expected, and if used the symbols defined by the SYMBOL manifest are valid. For other fonts you will get the symbol requested. The default is Text_def(font='symbols.gfn', color='k', weight=FONT_WEIGHT_ULTRALIGHT)
symbol – the symbol to plot, normally one of SYMBOL.
mode – REPLACE (default) or NEW, which creates a new unique name if group exists

Returns:

Color_symbols_group instance

New in version 9.2.

Changed in version 9.4: added support for passing data as a 2d numpy array

classmethod open(view, group_name)¶

Open an existing color symbols group.

Parameters:	view – view that contains the group group_name – name of the group, which must be a color symbols group
Returns:	`Color_symbols_group` instance

New in version 9.2.

class Draw(*args, **kwargs)¶

Bases: geosoft.gxpy.group.Group

Create (start) a drawing group for 2D drawing elements.

On a 3D view, 2D drawing elements are placed on the default drawing plane. Drawing groups will lock the view such that only one drawing group can be instantiated at a time.

Use with Draw() as group: to ensure correct unlocking when complete.

Inherits from the Group base class. See Group arguments.

contour(grid_file_name, parameters=None)¶

Draw contours for a grid file.

Parameters:	grid_file_name – Grid file name parameters – contour parameters, None for default contouring.

Parameters can be provided as a list of strings that correspond the contouring control file (starting at control file line 2) as defined on the Geosoft Desktop help topic ‘CONTCON’. The first ‘MDF’ line, which is used to specify the map scale and drawing location, is not required as the scale and location is fixed by the view.

Following are the control file parameters names as they would appear in a text control file:

border, lowtic, smooth, suppop, nth, gtitle     / 'general': {}
pdef, ptick, pxval, pframe, psidel              / 'special': {}
hlb, htl, hcr, htk, hxv, hsl                    / 'text': {}
ominl,cminl,skipa,skipb,skipc,skipd,skipe,skipf / 'line': {}
xval, digxv, minxv, markxv                      / 'hilo': {}
levopt, conbeg, conend, lbup, lbmult, logopt    / 'levels': {}
cint,lintyp,catt,label,dense,digits,conlo,conhi / 'contours': [{}, {}, ...]
 ...
 ...  up to 32 contour levels
 ...

Example parameters as text strings:

`parameter=`	Outcome
`None`	default contour based on the grid data range
`('','','','','','','10')`	multiples of 10
`('','','','','','','10','50','250')`	multiples of 10, 50 and 100, default attributes
`('','','','','','0','0,,,0')`	single contour (levopt=0) at value 0 (cint=0), no label (label=0)
`('','','','','','0','0,,a=rt500,0')`	red 500 micron thick contour at value 0, no label

Parameters may also be defined in a dictionary using explicit parameter names as shown in the text control file template above. Each line of parameters is defined by the key name to the right on the /, and the ‘contours’ entry is a list, and the values are dictionaries of the parameters to be defines. Parameters that are not defined will have the documented default behaviour.

Example parameters as a dictionary:

`parameter=`	Outcome
`{'contours':[{'cint':10}]}`	multiples of 10
`{'contours':[{'cint':10},{cint':50}]}`	multiples of 10 and 50, default attributes
`{'levels':{'levopt':0},[{'cint':10,'label':0}]}`	single contour at data value = 0, no label

New in version 9.2.

New in version 9.4: added parameter controls

drawing_coordinate_system¶: The coordinate of incoming spatial data, which are converted to the coordinate system of the view. This is normally the same as the view coordinate system, but it can be set to a different coordinate system to have automatic reprojection occur during drawing.

graticule(dx=None, dy=None, ddx=None, ddy=None, style=1)¶

Draw a graticule reference on a view.

Parameters:	style – `GRATICULE_LINE`, `GRATICULE_CROSS` or `GRATICULE_DOT` dx – vertical line separation dy – horizontal line separation ddx – horizontal cross size for `GRATICULE_CROSS` ddy – vertical cross size for `GRATICULE_CROSS`

New in version 9.2.

group_opacity¶

Group opacity setting. Can be set

Returns:	opacity 0. to 1. (opaque)

line(p2)¶

Draw a line on the current plane

Parameters:	p2 – `geometry.Point2`, or (p1, p2)

New in version 9.2.

new_pen(**kwargs)¶

Returns a pen that inherits default from the current view pen. Arguments are the same as the Pen constructor. This using this ensures that default sizing of view unit-based dimensions (such as line_thick) are not lost when new pens are created.

Parameters:	kwargs – see `Pen`
Returns:	`Pen` instance

New in version 9.2.

pen¶: the current drawing pen as a Pen instance

point(p)¶

Draw a point.

Parameters:	p – point location as `geosoft.gxpy.geometry.Point`

New in version 9.3.

polygon(pp)¶

Draw a polygon on the current plane.

Parameters:	pp – `geosoft.gxpy.geometry.PPoint`

Note

Smooth-line polygons must have at least 6 points for the closure to appear continuous.

New in version 9.2.

polyline(pp, close=False)¶

Draw a polyline the current plane

Parameters:	pp – `geosoft.gxpy.geometry.PPoint` instance or something that can be constructed, or a pair of `geosoft.gxpy.vv.GXvv` (xvv, yvv) close – if True, draw a polygon, default is a polyline

Note

Smooth-line polygons must have at least 6 points for the closure to appear continuous.

New in version 9.2.

polypoint(pp)¶

Draw many points.

Parameters:	pp – point location as `geosoft.gxpy.geometry.PPoint`, or a pair of VVs (vvx, vvy), or something that `gxpy.geometry.PPoint` can construct into a PP.

New in version 9.3.

rectangle(p2)¶: Draw a 2D rectangle on the current plane :param p2: geometry.Point2, or (p1, p2), or (x0, y0, x2, y2)

New in version 9.2.

text(text, location=(0, 0), reference=0, angle=0.0, text_def=None)¶

Draw text in the view.

Parameters:

text – text string. Use line-feed characters for multi-line text.
location – (x, y) or a gxpy.geomerty.Point location

reference –

Text justification point relative text outline box. The points are:

7 8   top left, center, right
4 5   middle left, center, right
1 2   bottom left, center, right

angle – baseline angle in degrees clockwise
text_def – text definition, if not set the current definition is used

New in version 9.2.

text_def¶: the current text definition as a Text_def instance, can be set.

text_extent(str, text_def=None)¶

Return the extent of a text string in view units relative to the current text text_def setting, or the specified text_def setting.

Parameters:	str – text string text_def – `text_def` instance, None for the current setting
Returns:	`geosoft.geometry.Point2` instance

New in version 9.4.

class Draw_3d(view, *args, render_backfaces=False, **kwargs)¶

Bases: geosoft.gxpy.group.Draw

Create a 3D drawing group within a 3D view.

3D drawing groups accept 3D drawing objects that can be created using methods of this class. 2D objects can also be drawn to a 3D group and will be placed on the default drawing plane within the 3D view.

Parameters:	render_backfaces – True to turn backface rendering on.

New in version 9.2.

box_3d(p2, wireframe=False)¶

Draw a 3D box

Parameters:	p2 – box corners as geometry.Point2, or (p0, p1), or (x0, y0, z0, x1, y1, z1) wireframe – True to draw edges only

New in version 9.2.

cone_3d(p2, radius)¶

Draw a cone.

Parameters:	p2 – end points as geometry.Point2, or (p0, p1), or (x0, y0, z0, x1, y1, z1). radius – cone base radius, base is as the the first point of p2.

New in version 9.2.

cylinder_3d(p2, radius, r2=None, close=3)¶

Draw a cylinder.

Parameters:	p2 – end points as geometry.Point2, or (p0, p1), or (x0, y0, z0, x1, y1, z1) radius – cylinder radius. r2 – end radius if different from the start close – one of: CYLINDER_OPEN CYLINDER_CLOSE_START CYLINDER_CLOSE_END CYLINDER_CLOSE_ALL

New in version 9.2.

polydata_3d(data, render_info_func=None, passback=None)¶

Create 3D objects rendered using data attributes.

Parameters:

data – iterable that yields items passed to your render_info_func callback

render_info_func –

a callback that given (item, passback) returns the rendering (symbol_type, geometry, color_integer, attribute):

Symbol	Geometry	Color	Attribute
SYMBOL_3D_SPHERE	Point	Color.int_value	radius
SYMBOL_3D_CUBE	Point2	Color.int_value	None
SYMBOL_3D_CYLINDER	Point2	Color.int_value	radius
SYMBOL_3D_CONE	Point2	Color.int_value	radius

passback – something passed back to your render_info_func function, default None.

Example

import geosoft.gxpy.geometry as gxgm
import geosof.gxpy.view as gxv
import geosogt.gxpy.group as gxg

def render_spheres(xyz, cmap_radius):
    color, radius = cmap_radius
    return gxg.SYMBOL_3D_SPHERE, xyz, color.int_value, radius

data = gxgm.PPoint(((5, 5, 5), (7, 5, 5), (7, 7, 7)))
with gxv.View_3d.new('example_polydata') as v:
    with gxg.Draw_3d(v, 'red_spheres') as g:
        g.polydata_3d(data, render_spheres, (gxg.Color('r'), 0.25))

New in version 9.2.

polyline_3d(points, style=0)¶

Draw a polyline.

Parameters:	points – verticies of the polyline, `geosoft.gxpy.geometry.PPoint` instance, or array-like [x,y,z] style – LINE3D_STYLE_LINE, LINE3D_STYLE_TUBE or LINE3D_STYLE_TUBE_JOINED. Lines are single-pixel-wide. Tubes have width defined by the pen line thickness. Joined tubes have a joints and rounded ends.

New in version 9.2.

polypoint_3d(points, style=0)¶

Draw multiple points.

Parameters:	points – points to draw, `geosoft.gxpy.geometry.PPoint` instance, or array-like [x,y,z] style – POINT_STYLE_DOT or POINT_STYLE_SPHERE. Dots are fast and intended for point clouds. The current pen thickness is used as the sphere sizes.

New in version 9.2.

render_backfaces¶: True if backface rendering is on, default is off (False). Backface rendering controls the rendering of parts of solid objects that would normally be hidden from view. If drawing solid objects that have an open face, such as cylinders with an open end, backface rendering will be be turned on. Once on it cannot be turned off for a view.

New in version 9.2.

sphere(p, radius)¶

Draw a sphere.

Parameters:	p – location as geometry.Point, or (x, y, z) radius – sphere radius

New in version 9.2.

class Group(view, name='_', plane=None, view_lock=False, mode=0, unit_of_measure='', group_3d=False)¶

Bases: object

Geosoft group class.

Parameters:

unit_of_measure:
view:	gxpy.View
name:	group name, default is “_”.
plane:	plane number, or plane name if drawing to a 3D view. Default is plane number 0.
view_lock:	True to lock the view for a single-stream drawing group. Default is False.
	unit of measurement for data in this group, default is ‘’
group_3d:	True for a 3D drawing group, default assumes a 2D drawing group to a plane.
mode:	`APPEND` (default), `NEW` or `READ_ONLY`

Properties:

unit_of_measure:
view:	the `geosoft.gxpy.view.View` instance that contains this group
name:	the name of the group
	the unit of measurement (uom) for this data in this group
name_uom:	uom decorated group name as it appears in a view
extent:	extent of the group in view units
extent_map_cm:	extent of the group in map cm
drawing_coordinate_system:
	the coordinate system of drawing coordinates. Setting to None will reset drawing coordinates to the view cs. If `drawing_coordinate_system` is set to some other cs the drawing coordinates will be transformed into the view cs.

New in version 9.2.

Changed in version 9.3: added support for unit_of_measure

Changed in version 9.3.1: added mode=REPLACE and changed mode=NEW to always create a new unique group.

close()¶: Close the group, unlocks the view

drawing_plane¶: drawing plane of this group, None for a group in a 2D view.

extent¶: group extent as (xmin, ymin, xmax, ymax) in view units

extent_map_cm(extent=None)¶

Return an extent in map cm.

Parameters:	extent – an extent in view units as a tuple (xmin, ymin, xmax, ymax), Default is the group extent.

New in version 9.2.

guid¶: The group GUID.

New in version 9.3.

gx_metadata¶

The group metadata as a Geosoft geosoft.gxpy.metadata.Metadata instance. This metadata may contain standard Geosoft metadata, such as unit_of_measure for data contained in the group, and you can add your own metadata spexific to your application. See geosoft.gxpy.metadata.Metadata for information about working with metadata.

Can be set, in which case the metadata is replaced by the new metadata. Normally you will get the current metadata, add to or modify, then set it back.

New in version 9.3.

locate(location, reference=4)¶

Locate the group relative to a point.

Parameters:	location – location (x, y) or a `geosoft.gxpy.geometry.Point` reference – reference point relative to the clip limits of the view to which reference location. The points are: 6 7 8 top left, center, right 3 4 5 center left, center, right 0 1 2 bottom left, center, right

New in version 9.2.

name¶: group name

number¶: group number in the view

unit_of_measure¶

Unit of measure for scalar data contained in this group. This is only relevant for groups that contain scalar data, such as a Colour_symbols_group. For the spatial unit_of_measure use drawing_coordinate_system.unit_of_measure

Can be set.

..versionadded:: 9.3

view¶: view that contains this group.

visible¶: True if group is visible, can be set.

exception GroupException(message)¶

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.group.

New in version 9.2.

class Pen(**kwargs)¶

Bases: object

Geosoft Pen class.

The default dimensioned properties (line_thick, line_pitch, pat_size and pat_thick) assume the view units are cm, and this is usually only the case for the base view. For views in other units either explicitly define the dimention in view units, or pass factor set the the view geosoft.gxpy.view.View.units_per_map_cm.

Parameters:

line_color – line Color instance, default is black
fill_color – fill Color instance, default is transparent
line_thick – line thickness, default is 0.01

line_style –

line pattern style

LINE_STYLE_SOLID (default)
LINE_STYLE_LONG
LINE_STYLE_DOTTED
LINE_STYLE_SHORT
LINE_STYLE_LONG_SHORT_LONG
LINE_STYLE_LONG_DOT_LONG

line_pitch – line style pitch, default is 0.5

line_smooth –

smooth line:

SMOOTH_NONE (default)
SMOOTH_AKIMA
SMOOTH_CUBIC

pat_number – pattern number for filled patterns (refer to etc/default.pat) default 0, flood fill
pat_angle – pattern angle, default 0
pat_density – pattern density, default 1
pat_size – pattern size, default 1.0

pat_style –

pattern style:

TILE_RECTANGULAR (default)
TILE_DIAGONAL
TILE_TRIANGULAR
TILE_RANDOM

pat_thick – pattern line thickness, default 0.01
default – default Pen instance, if specified defaults are established from this
factor – default spatial properties are multiplied by this factor. This is useful for creating pens scaled to the units of a view. The default pen properties are scaled to cm. Typically you will pass geosoft.gxpy.view.View.units_per_map_cm.

fill_color¶

classmethod from_mapplot_string(cstr)¶

Create a Pen instance from a mapplot-style string descriptor using either a krgbKRGB or kcmyKCMY color model. Lower case letters indicate line color, uppercase indicates fill color, ‘k’, ‘K’ for black. Each letter may be followed by an intensity between 0 and 255. If an intensity is not specified 255 is assumed.

Line thickness can be defined by ‘t’ followed by a thickness in 1000’th of the view unit, which for the default ‘base’ view would be microns.

Parameters:	cstr – mapplot-style color definition

Examples:

‘r’ red line

‘R’ red fill

‘rG64’ red line, light-green fill

‘c64’ light cyan line, equivalent to ‘R191G255B255’

‘c64K96’ light cyan line, light-grey fill

‘bt500’ blue line, 0.5 units thick

New in version 9.2.

line_color¶: pen line color as a color instance, can be set.

mapplot_string¶: line/fill colour and thickness string suing mapplor format, eg. ‘kR125B64t1000’

class Text_def(**kwargs)¶

Bases: object

Text definition:

Parameters:

font – font name. TrueType fonts are assumed unless the name ends with ‘.gfn’, which is a Geosoft gfn font.

weight –

one of:

FONT_WEIGHT_ULTRALIGHT
FONT_WEIGHT_LIGHT
FONT_WEIGHT_MEDIUM
FONT_WEIGHT_BOLD
FONT_WEIGHT_XBOLD
FONT_WEIGHT_XXBOLD

line_thick – line thickness from which to determine a weight, which is calculated from the ratio of line thickness to height.
italics – True for italics fonts
height – text height, default 0.25
factor – default spatial properties are multiplied by this factor. This is useful for creating text scaled to the units of a view. The default text properties are scaled to cm.

Properties:

height:	font height in view units
font:	font name
weight:	font weight, one of FONT_WEIGHT
line_thick:	font line thickness for gfn stroke fonts
italics:	True for italics
slant:	Slant angle for stroke fonts, 0 if normal, 15 for italics
mapplot_string:	mapplot compatible text definition string

New in version 9.2.

color¶: text color as a Color instance, can be set

font¶: text font name, can be set.

line_thick¶: text line thickness determined from the font weight, can be set.

mapplot_string¶: Mapplot text definition string, assumes scaling in cm.

slant¶: text slant, 15 for italics, 0 for not italics, can be set. If set, any slant greater than 5 will result in a 15 degree slant to create italics.

class VoxDisplayGroup(view3d, group_name, mode=3)¶

Bases: geosoft.gxpy.group.Group

Vox display group in a view. Use class methods new() and open() to create instances of VoxDisplayGroup.

Constructors:

open() open an existing vox_display group

new() create a new vox_display group

New in version 9.3.1.

classmethod new(view3d, voxd, name=None, mode=3)¶

Add a VoxDisplay as a new group in the view

Parameters:	view3d – `geosoft.gxpy.view.View_3d` instance voxd – `geosoft.gxpy.vox_display.VoxDisplay` instance name – group name, default is the voxd name mode – REPLACE (default) or NEW, which creates a unique name if the group exists

New in version 9.3.1.

classmethod open(view, group_name)¶

Open an existing VoxDisplayGroup in a 3d view.

Parameters:	view – the 3d view group_name – the name of the group to open, must be a `gxapi.GXVOXD` or `gxapi.GXVECTOR3D`.

voxd¶: The geosoft.gxpy.vox_display.VoxDisplay for this vox group.

New in version 9.3.1.

color_from_string(cstr)¶

Return a Geosoft color number from a color string.

Parameters:	cstr – color string (see below)
Returns:	color

Colour strings may be “R”, “G”, “B”, “C”, “M”, “Y”, “H”, “S”, “V”, or “K” or a combination of these characters, each followed by up to three digits specifying a number between 0 and 255. An empty string will produce C_ANY_NONE.

You must stay in the same color model, RGB, CMY, HSV or K.

For example “R”, “R127G22”, “H255S127V32”

Characters are not case sensitive.

New in version 9.3.

contour(view, group_name, grid_file_name, parameters=None)¶

Create a contour group from a grid file. A default contour interval is determined from the grid.

Parameters:	view – `geosoft.gxpy.view.View` instance group_name – name for the contour group grid_file_name – Grid file name

New in version 9.3.

edge_reference(area, reference)¶

Location of a reference point of an area.

Parameters:	area – `Point2` instance, or (x0, y0, x1, y1) reference – reference point relative to the clip limits of the view to which reference location. The points are: 6 7 8 top left, center, right 3 4 5 middle left, center, right 0 1 2 bottom left, center, right
Returns:	Point desired reference location as a Point

New in version 9.2.

face_normals_np(faces, verticies)¶

Return normals of the verticies based on tringular faces, assuming right-hand winding of vertex for each face.

Parameters:	faces – faces as array of triangle indexes into verticies, shaped (-1, 3) verticies – verticies as array of (x, y, z) shaped (-1, 3)
Returns:	face normals shaped (-1, 3)

The normal of a zero area face will be np.nan

New in version 9.3.1.

font_weight_from_line_thickness(line_thick, height)¶

Returns font weight for a text height and line thickness.

Parameters:

line_thick – line thickness in same units as the text height
height – text height

Returns:

one of:

FONT_WEIGHT_ULTRALIGHT
FONT_WEIGHT_LIGHT
FONT_WEIGHT_MEDIUM
FONT_WEIGHT_BOLD
FONT_WEIGHT_XBOLD
FONT_WEIGHT_XXBOLD

New in version 9.2.

legend_color_bar(view, group_name, cmap, cmap2=None, bar_location=0, location=None, decimals=None, annotation_height=0.2, annotation_offset=None, annotation_side=1, box_size=None, bar_width=None, max_bar_size=None, minimum_gap=0, post_end_values=False, annotate_vertical=False, division_line=1, interval_1=None, interval_2=None, title=None)¶

Draw a color bar legend from :class:Color_map coloring definitions.

Parameters:

view – gxpy.view.View instance in which to place the bar
group_name – name for the color_bar group, overwrites group if it exists.
cmap – Color_map instance
cmap2 – optional orthogonal blended Color_map instance. If making a shaded-color legend, provide the shaded color map here.

bar_location –

one of:

COLOR_BAR_RIGHT = 0
COLOR_BAR_LEFT = 1
COLOR_BAR_BOTTOM = 2
COLOR_BAR_TOP = 3

location – offset or (x, y) offset from bar_location reference point, in cm. The default is determined to center the bar off the location side specified.
decimals – annotation decimal places
annotation_height – annotation number height (cm)
annotation_offset – offset of annotations from the bar (cm)

annotation_side –

side of the bar for annotations

COLOR_BAR_ANNOTATE_RIGHT = 1
COLOR_BAR_ANNOTATE_LEFT = -1
COLOR_BAR_ANNOTATE_TOP = 1
COLOR_BAR_ANNOTATE_BOTTOM = -1

box_size – box size, height for vertical bars, width for horizontal bars
bar_width – width of the color boxes, horizontal for vertical bars, vertical for horizontal bars
max_bar_size – maximum bar size, default is the size of the view edge
minimum_gap – minimum gap to between annotations. Annotations are dropped in necessary.
post_end_values – post the maximum and minimum values
annotate_vertical – True to orient labels vertically
division_line – 0, no division lines, 1 - line, 2 - tick
interval_1 – Major annotation increment, default annotates everything
interval_2 – secondary smaller annotations, reduced to 1/10, 1/5, 1/4 or 1/2 of interval_1. Default chooses something reasonable.
title – bar title, use new-lines for sub-titles. Default uses the title and unit_of_measure from cmap.

New in version 9.2.

surface_group_from_file(v3d, file_name, group_name=None, overwrite=False)¶

Create a 3D surface group from a surface dataset file.

Parameters:	v3d – `geosoft.gxpy.view.View_3d` instance file_name – surface dataset file name (extension .geosoft_surface). See `geosoft.gxpy.surface.SurfaceDataset`. group_name – group name, default is the base file name. overwrite – True to overwrite existing group

New in version 9.3.1.

thickness_from_font_weight(weight, height)¶

Returns the line thickness appropriate for a text weight.

Parameters:	weight – one of: FONT_WEIGHT_ULTRALIGHT FONT_WEIGHT_LIGHT FONT_WEIGHT_MEDIUM FONT_WEIGHT_BOLD FONT_WEIGHT_XBOLD FONT_WEIGHT_XXBOLD height – font height

New in version 9.2.

vertex_normals_np(faces, verticies, normal_area=True)¶

Return normals of the verticies based on tringular faces, assuming right-hand winding of vertex for each face.

Parameters:	faces – faces as array of triangle indexes into verticies, shaped (-1, 3) verticies – verticies as array of (x, y, z) shaped (-1, 3) normal_area – True to weight normals by the area of the connected faces.
Returns:	vertex normals shaped (-1, 3)

New in version 9.3.1.

vertex_normals_vv(faces, verticies, normal_area=True)¶

Return normals of the verticies based on tringular faces, assuming right-hand winding of vertex for each face.

Parameters:	faces – (i1, i2, i3) `geosoft.gxpy.vv.GXvv` faces as array of triangle indexes into verticies verticies – (vx, vy, vz) `geosoft.gxpy.vv.GXvv` verticies normal_area – True to weight normals by the area of the connected faces.
Returns:	(nx, ny, nz) `geosoft.gxpy.vv.GXvv` normals

New in version 9.3.1.

‘r’	red line
‘R’	red fill
‘rG64’	red line, light-green fill
‘c64’	light cyan line, equivalent to ‘R191G255B255’
‘c64K96’	light cyan line, light-grey fill
‘bt500’	blue line, 0.5 units thick