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

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

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.

__init__(view, group_name, mode)[source]¶: Initialize self. See help(type(self)) for accurate signature.

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

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

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

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.

__init__(color, model=0)[source]¶: Initialize self. See help(type(self)) for accurate signature.

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

New in version 9.2.

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

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

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

class Color_map(cmap=None, title=None, unit_of_measure=None)[source]¶

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

__init__(cmap=None, title=None, unit_of_measure=None)[source]¶: Initialize self. See help(type(self)) for accurate signature.

property 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.

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

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

color_of_value(value)[source]¶

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.

property 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.

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

New in version 9.2.

property length¶: Number of color zones in the map.

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

save_file(file_name=None)[source]¶

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

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

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

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

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.

property 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.

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

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

__init__(view, group_name, **kwargs)[source]¶: Initialize self. See help(type(self)) for accurate signature.

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

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

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

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.

__init__(*args, **kwargs)[source]¶: Initialize self. See help(type(self)) for accurate signature.

contour(grid_file_name, parameters=None)[source]¶

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

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

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.

property group_opacity¶

Group opacity setting. Can be set

Returns: opacity 0. to 1. (opaque)

line(p2)[source]¶

Draw a line on the current plane

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

New in version 9.2.

new_pen(**kwargs)[source]¶

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.

property pen¶: the current drawing pen as a Pen instance

point(p)[source]¶

Draw a point.

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

New in version 9.3.

polygon(pp)[source]¶

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

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

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

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.

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

text_extent(str, text_def=None)[source]¶

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

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.

__init__(view, *args, render_backfaces=False, **kwargs)[source]¶: Initialize self. See help(type(self)) for accurate signature.

box_3d(p2, wireframe=False)[source]¶

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

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

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

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

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

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.

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

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

Bases: object

Geosoft group class.

Parameters

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_measure: 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

view: the geosoft.gxpy.view.View instance that contains this group
name: the name of the group
unit_of_measure: 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.

__init__(view, name='_', plane=None, view_lock=False, mode=0, unit_of_measure='', group_3d=False)[source]¶: Initialize self. See help(type(self)) for accurate signature.

close()[source]¶: Close the group, unlocks the view

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

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

extent_map_cm(extent=None)[source]¶

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.

property guid¶: The group GUID.

New in version 9.3.

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

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:

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

New in version 9.2.

property name¶: group name

property number¶: group number in the view

property 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

property view¶: view that contains this group.

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

exception GroupException(message)[source]¶

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.group.

New in version 9.2.

class Pen(**kwargs)[source]¶

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.

__init__(**kwargs)[source]¶: Initialize self. See help(type(self)) for accurate signature.

property fill_color¶

classmethod from_mapplot_string(cstr)[source]¶

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.

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

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

class Text_def(**kwargs)[source]¶

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.

__init__(**kwargs)[source]¶: Initialize self. See help(type(self)) for accurate signature.

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

property font¶: text font name, can be set.

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

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

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

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.

__init__(view3d, group_name, mode=3)[source]¶: Initialize self. See help(type(self)) for accurate signature.

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

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

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.

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

New in version 9.3.1.

color_from_string(cstr)[source]¶

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

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

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:

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

Returns

Point desired reference location as a Point

New in version 9.2.

face_normals_np(faces, verticies)[source]¶

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

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

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

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

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

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

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

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