geosoft.gxpy.surface submodule¶

Geosoft surfaces

Classes:

`SurfaceDataset`:	Geosoft_surface dataset, contains zero or more `Surface` instances
`Surface`:	Surfaces defined by one or more `geosoft.geometry.Mesh` instances

Constants:

MODE_READ:	`geosoft.gxpy.spatialdata.MODE_READ`
MODE_READWRITE:	`geosoft.gxpy.spatialdata.MODE_READWRITE`
MODE_NEW:	`geosoft.gxpy.spatialdata.MODE_NEW`
MODE_APPEND:	MODE_READWRITE
STYLE_FLAT:	`geosoft.gxapi.SURFACERENDER_FILL`
STYLE_SMOOTH:	`geosoft.gxapi.SURFACERENDER_SMOOTH`
STYLE_EDGE:	`geosoft.gxapi.SURFACERENDER_EDGES`

Note

Regression tests provide usage examples: Tests

class Surface(surface, surface_type='none', surface_dataset=None, mesh=None, coordinate_system=None, render_properties=None)¶

Bases: geosoft.gxpy.spatialdata.SpatialData, collections.abc.Sequence

A single surface, which contains one or more geosoft.gxpy.geometry.Mesh instances.

Parameters:

surface – surface name or a geosoft.gxapi.GXSURFACEITEM instance.
surface_type – surface type as a descriptive name, such as “ISOSURFACE”
surface_dataset – optional SurfaceDataset instance in which to place a new Surface
mesh – optional geosoft.gxpy.geometry.Mesh instance, or tuple (faces, verticies).
coordinate_system – mesh coordinate system, which will become the surface coordinate system.
render_properties – (color, opacity, style), default is (geosoft.gxpy.group.C_GREY, 1.0, STYLE_FLAT)

Iterating yields component geosoft.gxpy.geometry.Mesh instances.

New in version 9.3.1.

add_mesh(mesh, render_properties=None, coordinate_system=None)¶

Add a vv mesh to a new surface.

Parameters:

mesh – mesh as ((f1vv, f2vv, f3vv), (xvv, yvv, zvv))
render_properties – (color, opacity, style), where colour is a geosoft.gxpy.group.Color instance or a 32-bit Geosoft color integer, opacity is a value between 0. (invisible) and 1. (opaque), and style is STYLE_FLAT, STYLE_SMOOTH or STYLE_EDGE.
coordinate_system – coordinate system for the verticies, default is the same as the surface

Returns:

component number, which will always be the last component.

New in version 9.3.

component_count¶: number of components to this surface, usually 1

computed_properties(refresh=False)¶

Surface properties, see: geosoft.gxapi.GXSURFACEITEM.compute_extended_info.

Parameters:	refresh – if True, computed properties will be refreshed on next access.
Returns:	dictionary of properties, ‘components’, ‘verticies’, edges’, ‘triangles’, ‘inconsistent’, ‘invalid’, ‘intersect’

New in version 9.3.1.

extent¶: Return the surface extent as a geosoft.gxpy.geometry.Point2 instance.

New in version 9.3.1.

faces_count¶: number of triangular faces

guid¶: The GUID of this surface

gxsurfaceitem¶: the geosoft.gxapi.GXSURFACEITEM instance

mesh(component=0)¶

Returns a component mesh as geosoft.gxpy.geometry.Mesh instance

Parameters:	component – component number from a multi-component surface
Returns:	(triangle_index_1, triangle_index_2, triangle_index_3), (vertex_x, vertex_y, vertex_z) as `geosoft.gxpy.vv.GXvv` instances

New in version 9.3.1.

metadata¶: Return the parent surface dataset metadata as a dictionary.

name¶: the name of this surface

properties(refresh=False)¶

Surface properties from geosoft.gxapi.GXSURFACEITEM.get_properties_ex.

Parameters:	refresh – if True, computed properties will be refreshed on next access.

New in version 9.3.1.

render_color¶: rendering colour as a geosoft.gxpy.group.Color instance

render_opacity¶: group opacity, 0.0 (transparent) to 1.0 (opaque)

render_properties¶: The rendering properties for this surface as (color, opacity, style). Can be set.

render_style¶: surface rendering style, one of STYLE constants

source_dataset¶: the source dataset from which this surface was derived

source_measure¶: the source measure

surface_type¶: the defined surface type string

unit_of_measure¶: the unit of measure for data defined by this surface, often the isosurface value

verticies_count¶: number of verticies

class SurfaceDataset(name, file_name=None, gxsurface=None, mode=None, overwrite=False)¶

Bases: geosoft.gxpy.spatialdata.SpatialData, collections.abc.Sequence

Surface dataset, which contains one or more Surface instances.

A Surface dataset is stored in a .geosoft_surface file.

Iterating yields Surface instances.

Constructors:

`open()`	open an existing surface dataset
`new()`	create a new surface dataset
`vox_surface()`	isosurfaces created from a vox.

New in version 9.3.1.

add_surface(surface)¶

Add a surface to the surface dataset. One can only add surfaces to new datasets.

Parameters:	surface – `Surface` instance to add

New in version 9.3.1.

add_surface_dataset(surface_dataset)¶

Add the surfaces from an existing surface dataset.

Parameters:	surface_dataset – `SurfaceDataset` instance or a file name

New in version 9.3.1.

figure_map(file_name=None, overwrite=True, title=None, legend_label=None, features=('LEGEND', 'NEATLINE'), **kwargs)¶

Create a figure view file from an SurfaceDataset.

Parameters:

file_name – the name of a file for the 3d view. If None a temporary 3d view created.
overwrite – True to overwrite existing file
title – Title added to the image
legend_label – If plotting a legend make this the legend title. The default is the unit_of_measure.
features –
list of features to place on the map, default is (‘LEGEND’, ‘NEATLINE’)

’LEGEND’ draw a surface legend

’NEATLINE’ draw a neat-line around the image
kwargs – passed to geosoft.gxpy.map.Map.new

New in version 9.3.

gxsurface¶: geosoft.gxapi.GXSURFACE instance handle

has_surface(name)¶: returns True if this surface name or guid exists in the surface dataset.

is_new¶: True if this is a new surface dataset. Can only add to new datasets.

classmethod new(name=None, temp=False, overwrite=False, coordinate_system=None)¶

Create a new surface dataset.

Parameters:	name – dataset name, or a path to a persistent file. If None a temporary dataset is created. temp – True to create a temporary surface dataset. overwrite – True to overwrite existing persistent surface dataset file coordinate_system – coordinate system as required to create from `geosoft.gxpy.Coordinate_system`

New in version 9.3.1.

classmethod open(name, file_name=None, mode=0, gxapi_surface=None)¶

Open an existing surface dataset.

Parameters:	name – name of the surface dataset. file_name – file name of the surface dataset file, default is name.geosoft_surface. mode – open mode: MODE_READ or MODE_READWRITE gxapi_surface – `geosoft.gxapi.GXSURFACE` instance, or None to open the named surface file.

New in version 9.3.1.

surface_count¶: number of surfaces in the dataset

surface_dict¶: dictionary of surfaces keyed by GUID, values are the surface names

surface_guid(name)¶

Return the guid of a surface based on the name.

Parameters:	name – Name of the surface. The first matching surface name is returned.
Returns:	guid of the surface, or None if the surface not found

New in version 9.3.1.

surface_name_list¶: list of surface names

view_3d(file_name=None, overwrite=True, plane_2d=False)¶

Create a 3d view (geosoft.gxpy.view.View_3d) that contains this SurfaceDataset.

Parameters:	file_name – the name of a file for the 3d view. If None a temporary 3d view created. overwrite – True to overwrite existing file plane_2d – True to keep the 2D plane. Only keep it if you intend to draw on it otherwise a grey plane will appear in the view.

New in version 9.3.

classmethod vox_surface(vox, surfaces, name=None, file_name=None, color=None, opacity=None, mode=2, temp=False, overwrite=False)¶

Add voxel isosurfaces to a surface dataset.

Parameters:

vox – geosoft.gxpy.Vox instance
surfaces – surface value, or a list of surface values
name – Surface dataset name. The default will be vox.name.
file_name – optional file name if different from name root, ignored if temp=True
color – surface color, or a list of colors, For a list of surfaces, the default colour of each surface cycles through a list of (C_GREY, C_GREEN, C_YELLOW, C_BLUE, C_MAGENTA, C_RED, C_CYAN). If only one surface the default color is gxgroup.C_GREY.
opacity – opacity 0 t0 1. (1. is opaque), or a list of opacities. For a list of surfaces default opacity is applied in increasingly opaque steps in the order of the surface list, such that the 5’th and higher surfaces are opaque.
mode – MODE_NEW to create a new surface dataset. MODE_APPEND to append to existing dataset.
temp – True to create a temporary surface dataset.
overwrite – True to overwrite if dataset exists and MODE_NEW.

New in version 9.3.1.

exception SurfaceException(message)¶

Bases: geosoft.GXRuntimeError

Exceptions from geosoft.gxpy.surface.

delete_files(surface_name)¶

Delete all files associated with this surface dataset.

Parameters:	surface_name – name of the surface dataset file

New in version 9.3.1.

render(view, surface, group_name=None, overwrite=False)¶

Render a surface, surface dataset or surface dataset file in a 3D view.

Parameters:	view – `geosoft.view.View_3d` instance surface – `Surface` instance, `SurfaceDataset` instance or a geosoft_surface file name. group_name – name for the group, which defaults to the source name overwrite – True to overwrite existing group

Note

For a Surface or a SurfaceDataset instance a surface dataset file is created with a name constructed from the view name and the fies name: view_name.group_name.geosoft_surface.

New in version 9.3.1.