GXIMG class

class GXIMG(handle=0)[source]

GXIMG class.

The GXIMG class performs read and write operations on grid file data. When efficient access along both rows and columns is desired the GXPG class is recommended (see GXPG and GXPGU); the GXIMG is first created, then the GXPG is obtained from the GXIMG using get_pg.

Note:

The GXIMG methods use the XGD DATs to access grid files in different formats. The characteristics of a grid can be controlled using decorations on a grid file name. For example:

create_new_file,1,100,100,”mag.grd”); -> creates a new grid file “mag.grd” with all defaults.

create_new_file,1,100,100,”mag.grd(GRD;comp=none)”); -> creates a new grid file “mag.grd” with no compression.

create_new_file,1,100,100,”mag.grd(GRD;comp=size;type=short”); -> creates a new grid file “mag.grd” compressed for size, numbers stored as 2-byte integers..

See DAT_XGD constants.DOC for information about file name decorations available for all GXDAT types.

Different grid types support different features. For example, not all grid types support projection information. Geosoft will always create a *.gi file that is used to store all such information that we require from a grid. If the grid does support this information, both the grid and the *.gi file will contain the information.

__init__(handle=0)[source]

Initialize self. See help(type(self)) for accurate signature.

add_fault(xVV, yVV, type)[source]

Add a fault trace

Parameters
Returns

index of the added fault

Return type

int

New in version 9.10.

License: Geosoft Open License

Note: The X and Y values cannot be dummies. Polygons require at least three locations, Polylines require at least two.

classmethod average2(grid_in, grid_out)[source]

Reduce the dimensions in a 2D pager by a factor of 2

Parameters
  • grid_in (str) – Name of source Grid

  • grid_out (str) – Name of output Grid

New in version 5.0.

License: Geosoft Open License

Note: This method is useful for reducing the dimensions in a 2D pager by a factor of 2. The output pager retains the same origin, but the X and Y spacing is double that of the original. Essentially, the process removes all the even-indexed rows and columns, while leaving the locations of all the remaining data points in the “odd” rows and columns unchanged.

The output values at the output data locations are created by performing an average of the original data point and its valid surrounding data points; what is essentially a 3x3 smoothing filter.

copy(im_go)[source]

Copy IMGs.

Parameters

im_go (GXIMG) – Target GXIMG

New in version 5.0.

License: Geosoft Open License

classmethod create(type, kx, width, height)[source]

Creates an GXIMG not tied to a file at all

Parameters
  • type (int) – Data type GS_TYPES constants

  • kx (int) – Grid orientation (KX): 1 (rows in X) -1 (rows in Y)

  • width (int) – Grid width

  • height (int) – Grid height

Returns

GXIMG object

Return type

GXIMG

New in version 5.0.3.

License: Geosoft Open License

Note: Once destroyed all the data in this GXIMG is lost.

classmethod create_file(type, grid, mode)[source]

Creates an Image object tied to a grid file.

Parameters
Returns

GXIMG object

Return type

GXIMG

New in version 5.0.

License: Geosoft Open License

Note: When the GS_DOUBLE data type is chosen the actual on-disk type of the input image will be used instead of GS_DOUBLE if the on-disk values represent color data as opposed to real numbers.

classmethod create_mem(type, kx, width, height)[source]

Creates an GXIMG object that is backed only by memory.

Parameters
  • type (int) – Data type, GS_TYPES constants

  • kx (int) – Grid orientation (KX): 1 (rows in X) -1 (rows in Y)

  • width (int) – Grid width

  • height (int) – Grid height

Returns

GXIMG object

Return type

GXIMG

New in version 5.0.6.

License: Geosoft Open License

Note: Once destroyed all the data is lost. This is temporary.

classmethod create_new_file(type, kx, width, height, grid)[source]

Creates a new image file

Parameters
  • type (int) – Data type, GS_TYPES constants Cannot be GS_TYPE_DEFAULT

  • kx (int) – Grid orientation (KX): 1 (rows in X) -1 (rows in Y)

  • width (int) – Grid width

  • height (int) – Grid height

  • grid (str) – Name of the Grid to link to

Returns

GXIMG object

Return type

GXIMG

New in version 5.0.

License: Geosoft Open License

classmethod create_out_file(type, grid, img)[source]

Creates an output image file using input image info.

Parameters
Returns

GXIMG object

Return type

GXIMG

New in version 5.0.

License: Geosoft Open License

Note: When the GS_DOUBLE data type is chosen the actual on-disk type of the input image will be used instead of GS_DOUBLE if the on-disk values represent color data as opposed to real numbers.

create_projected(ipj)[source]

Applies a projection to an image.

Parameters

ipj (GXIPJ) – Projection to apply

New in version 5.0.

License: Geosoft Open License

Note: The GXIMG now appears to be in the projected coordinate system space.

create_projected2(ipj, cell_size)[source]

Applies a projection to an image, specify cell size.

Parameters
  • ipj (GXIPJ) – Projection to apply

  • cell_size (float) – Cell size

New in version 5.0.

License: Geosoft Open License

Note: The GXIMG now appears to be in the projected coordinate system space, with the specified cell size. If the cell size is rDUMMY (GS_R8DM), one is automatically calculated, as with create_projected.

create_projected3(ipj, cell_size, exp_pct)[source]

Same as create_projected2, but set expansion of bounds.

Parameters
  • ipj (GXIPJ) – Projection to apply

  • cell_size (float) – Cell size

  • exp_pct (float) – Expansion percent (>=0).

New in version 6.3.1.

License: Geosoft Open License

Note: The GXIMG now appears to be in the projected coordinate system space, with the specified cell size. If the cell size is rDUMMY (GS_R8DM), one is automatically calculated, as with create_projected. The expansion percent expands the bounds of the projected grid in order to allow for the curving of bounding edges. Normally, edges are sampled in order to allow for curving, but this parameter is set to 1.0 (for 1 percent) in the create_projected and create_projected2 wrappers, and will generally create a white/dummy border around the new grid. This new method allows you to specify the expansion, or turn it off (by setting it to 0). If the value is set to rDUMMY, then expansion is left at 1.0, the legacy behaviour.

delete_fault(index)[source]

Delete a fault trace

Parameters

index (int) – Fault index (0 to N-1)

New in version 9.10.

License: Geosoft Open License

e_type()[source]

Returns the element type.

Returns

Element type

Return type

int

New in version 5.0.

License: Geosoft Open License

Note: Same as sElementType_IMG(img,1)

element_type(xg_dor_img)[source]

Returns the element type.

Parameters

xg_dor_img (int) – 0 for XGD, 1 for GXIMG

Returns

Element type

Return type

int

New in version 5.0.5.

License: Geosoft Open License

extent(min_x, min_y, max_x, max_y)[source]

Get the img extents

Parameters

New in version 9.7.

License: Geosoft Open License

get_def_itr(itr)[source]

Get default transform, if it exists

Parameters

itr (GXITR) – Transform

Returns

0 - Okay 1 - No default possible/available

Return type

int

New in version 5.0.2.

License: Geosoft Open License

get_display_property(query)[source]

Gets display information about this image.

Parameters

query (int) – IMG_DISPLAY_PROPERTY constants

Return type

float

New in version 2021.2.

License: Geosoft Open License

Note: These values do not necessarily match the grid as currently displayed; they are retrieved and used whenever the grid is displayed in a viewer or map, and are used (for instance) to set the default values in the Display Grid GX. Some values return only values of 0 or 1.

get_double_parameter(name)[source]

Store a real parameter in an GXIMG object

Parameters

name (str) – Parameter name (case insensitive)

Returns

Parameter value, rDUMMY if not found.

Return type

float

New in version 8.2.

License: Geosoft Open License

get_fault(index, xVV, yVV, type)[source]

Retrieve a fault trace

Parameters

New in version 9.10.

License: Geosoft Open License

get_info(dx, dy, xo, yo, rot)[source]

Retrieves location information about this image.

Parameters
  • dx (float_ref) – X element separation

  • dy (float_ref) – Y element separation

  • xo (float_ref) – X location of first point

  • yo (float_ref) – Y location of first point

  • rot (float_ref) – Grid X axis rotation deg. CCW from reference X

New in version 5.0.

License: Geosoft Open License

get_ipj(ipj)[source]

Get the projection of a grid.

Parameters

ipj (GXIPJ) – Projection of the grid

New in version 5.0.

License: Geosoft Open License

get_meta(meta)[source]

Get the metadata of a grid.

Parameters

meta (GXMETA) – Metadata of the grid

New in version 5.0.8.

License: Geosoft Open License

get_pg(pg)[source]

Get a copy of the pager of a grid.

Parameters

pg (GXPG) – GXPG object to hold pager of the grid

New in version 5.0.

License: Geosoft Open License

See also

geth_pg to get the actual pager of the grid.

get_projected_cell_size(ipj, cell)[source]

Returns default cell size from projected image.

Parameters
  • ipj (GXIPJ) – Projection to apply

  • cell (float_ref) – Returned cell size

New in version 5.0.

License: Geosoft Open License

Note: Returns the cell size calculated by CreateProjected_PJIMG, or by create_projected2 when GS_R8DM is entered as the optional cell size. No inheritance is actually performed to the input GXIMG.

get_shadow_grid_path(path)[source]

Gets the name of a view.

Parameters

path (str_ref) – Shadow grid path name returned

New in version 2021.2.

License: Geosoft Open License

get_tr(tr)[source]

Get the trend information from a grid.

Parameters

tr (GXTR) – Trend information from the grid

New in version 5.0.

License: Geosoft Open License

get_z(x, y)[source]

Gets the grid value at a point

Parameters
  • x (float) – X location in the grid projection

  • y (float) – Y location in the grid projection

Returns

Grid value

Return type

float

New in version 5.0.

License: Geosoft Open License

geth_pg()[source]

Get the actual pager of a grid.

Returns

GXPG Object

Return type

GXPG

New in version 5.0.8.

License: Geosoft Open License

See also

get_pg to get just a copy of the grid’s pager.

inherit(ipj, cell)[source]

Inherit a projection/new cell size on the GXIMG.

Parameters
  • ipj (GXIPJ) – Projection

  • cell (float) – Optional cell size

New in version 5.0.

License: Geosoft Open License

Note: If cell size is GS_R8DM, then “nice” values for the cell size of the new projected grid will be determined so that the new grid has about the same number of cells as the old. If the cell size is specified, the inheritance will always work, even if the input GXIPJ is identical to the original GXIPJ, and the cell boundaries will be forced to be aligned with the new cell size.

inherit_img(im_gs)[source]

Make a grids match in size and coordinate system

Parameters

im_gs (GXIMG) – Source GXIMG

New in version 5.1.8.

License: Geosoft Open License

is_colour()[source]

Is this a Geosoft color grid?

Return type

bool

New in version 6.0.1.

License: Geosoft Open License

is_null()[source]

Check if this is a null (undefined) instance

Returns

True if this is a null (undefined) instance, False otherwise.

Return type

bool

classmethod is_valid_img_file(file)[source]

Is this a valid GXIMG file?

Parameters

file (str) – File to check

Return type

bool

New in version 8.0.

License: Geosoft Open License

classmethod is_valid_img_file_ex(file, err_msg)[source]

Is this a valid GXIMG file? Returns error message if it cannot be opened for any reason.

Parameters
  • file (str) – File to check

  • err_msg (str_ref) – Error message registered if unable to open

Return type

bool

New in version 8.0.1.

License: Geosoft Open License

load_img(im_gi)[source]

Loads an GXIMG into a master GXIMG.

Parameters

im_gi (GXIMG) – GXIMG to load

New in version 5.0.6.

License: Geosoft Open License

Note: The cell sizes and projections must be the same.

load_into_pager()[source]

Load GXIMG data from file into a pager to increase access time.

New in version 5.0.

License: Geosoft Open License

ne()[source]

Gets the # of elements in the optimal KX direction.

Returns

# of elements in the optimal KX direction

Return type

int

New in version 5.0.

License: Geosoft Open License

classmethod null()[source]

A null (undefined) instance of GXIMG

Returns

A null GXIMG

Return type

GXIMG

number_of_faults()[source]

Returns the number of individual fault traces stored in the IMG

Return type

int

New in version 9.10.

License: Geosoft Open License

Note: Faults are paths of (X, Y) locations, and are either polylines or polygons.

nv()[source]

Gets the # of vectors in the optimal KX direction.

Returns

# of vectors in the optimal KX direction

Return type

int

New in version 5.0.

License: Geosoft Open License

nx()[source]

Gets the # of X elements.

Returns

# of X elements.

Return type

int

New in version 5.0.

License: Geosoft Open License

ny()[source]

Gets the # of Y elements.

Returns

# of Y elements.

Return type

int

New in version 5.0.

License: Geosoft Open License

opt_kx(kx)[source]

Force optimal KX as desired.

Parameters

kx (int) – KX -1 by column 1 by row

New in version 5.0.

License: Geosoft Open License

Note: This will force loading an image into a GXPG if it is not already accessible in the direction requested.

Subsequent calls to methods that use the optimal KX will use the KX set here.

query_double(query)[source]

Query information about the GXIMG

Parameters

query (int) – IMG_QUERY constants

Returns

Information requested, dummy if unknown or invalid.

Return type

float

New in version 5.0.5.

License: Geosoft Open License

Note: You can call either funtion to retrieve any data, int or real.

query_int(query)[source]

Query information about the GXIMG

Parameters

query (int) – IMG_QUERY constants

Returns

Information requested, dummy if unknown or invalid.

Return type

int

New in version 5.0.5.

License: Geosoft Open License

Note: You can call either funtion to retrieve any data, int or real.

query_kx()[source]

Asks the GXIMG for the most efficient way to access the data.

Returns

-1 by columns, 1 by rows, 0 rows and columns are equally efficient.

Return type

int

New in version 5.0.

License: Geosoft Open License

read_v(v, be, ne, vv)[source]

Read a vector in the optimal KX direction.

Parameters
  • v (int) – Vector to Read

  • be (int) – Begining element # to read (0 is the first)

  • ne (int) – # elements to read (0 for whole vector)

  • vv (GXVV) – GXVV handle

New in version 5.0.

License: Geosoft Open License

read_x(bx, by, ny, vv)[source]

Read a column (constant X)

Parameters
  • bx (int) – X column

  • by (int) – Start Y to read

  • ny (int) – # Y to read (0 for whole vector)

New in version 5.0.

License: Geosoft Open License

read_y(by, bx, nx, vv)[source]

Read a row (constant Y)

Parameters
  • by (int) – Y row

  • bx (int) – Start X to read

  • nx (int) – # X to read (0 for whole vector)

New in version 5.0.

License: Geosoft Open License

classmethod refresh_gi(grid)[source]

Refresh the GI of a grid after it has moved or changed.

Parameters

grid (str) – Grid name

New in version 7.0.

License: Geosoft Open License

relocate(min_x, min_y, max_x, max_y, asp)[source]

Re-locate a grid image.

Parameters
  • min_x (float) – Area X minimum

  • min_y (float) – Area Y minimum

  • max_x (float) – Area X maximum

  • max_y (float) – Area Y maximum

  • asp (int) – IMG_RELOCATE constants

New in version 5.0.

License: Geosoft Open License

classmethod report(grid, wa, force, decimals, title)[source]

Writes grid info report to a file

Parameters
  • grid (str) – Grid name

  • wa (GXWA) – Text file to write to

  • force (int) – Recalc statistics (0 - no; 1 - yes)

  • decimals (int) – Number of decimals to put in results

  • title (str) – Title for report

New in version 5.0.

License: Geosoft Open License

classmethod report_csv(grid, wa, force, decimals, header)[source]

Writes grid info as a line to a CSV file

Parameters
  • grid (str) – Grid name

  • wa (GXWA) – Text file to write to

  • force (int) – Recalc statistics (0 - no; 1 - yes)

  • decimals (int) – Number of decimals to put in results

  • header (int) – Write header line (0 - no; 1 - yes)?

New in version 6.4.2.

License: Geosoft Open License

Note: Appends the stats as a CSV line to the input text file. The header line should only be written to a new text file.

set_def_itr(itr)[source]

Set default transform

Parameters

itr (GXITR) – Transform

Returns

0 - Okay 1 - No default possible/available

Return type

int

New in version 5.0.2.

License: Geosoft Open License

set_display_property(query, value)[source]

Sets display information about this image.

Parameters

New in version 2021.2.

License: Geosoft Open License

Note: These values do NOT take immediate effect; they are retrieved and used whenever the grid is displayed in a viewer or map, and are used (for instance) to set the default values in the Display Grid GX. Some values take on only values of 0 or 1.

set_double_parameter(name, value)[source]

Store a real parameter in an GXIMG object

Parameters
  • name (str) – Parameter name (case insensitive)

  • value (float) – Parameter value to store

New in version 8.2.

License: Geosoft Open License

set_grid_unchanged()[source]

Mark the grid as unchanged so it will not output lineage

New in version 7.0.

License: Geosoft Open License

set_info(dx, dy, xo, yo, rot)[source]

Sets location information about this image.

Parameters
  • dx (float) – X element separation

  • dy (float) – Y element separation

  • xo (float) – X location of first point

  • yo (float) – Y location of first point

  • rot (float) – Grid X axis rotation deg. CCW from reference X

New in version 5.0.

License: Geosoft Open License

Note: Calls to this function should be made BEFORE calls to set_ipj, as the latter function sets up the bounding rectangle in the metadata.

set_ipj(ipj)[source]

Set the projection of a grid.

Parameters

ipj (GXIPJ) – Projection

New in version 5.0.

License: Geosoft Open License

Note: Calls to this function should be made AFTER calls to set_info, as set_ipj sets up the bounding rectangle in the metadata.

set_meta(meta)[source]

Set the metadata of a grid.

Parameters

meta (GXMETA) – Metadata to add to the grid

New in version 5.0.8.

License: Geosoft Open License

set_pg(pg)[source]

Copy a pager into the pager of a grid.

Parameters

pg (GXPG) – Pager object to copy into the pager of the grid

New in version 5.0.

License: Geosoft Open License

set_shadow_grid_path(path)[source]

Sets display information about this image.

Parameters

path (str) – Grid path for the shadow grid

New in version 2021.2.

License: Geosoft Open License

Note: This values does NOT take immediate effect; it is retrieved and used whenever the grid is displayed in a viewer or map, and is used (for instance) to set the default value in the Display Grid GX.

set_tr(tr)[source]

Set the trend information to a grid.

Parameters

tr (GXTR) – Trend information to set for the grid

New in version 5.0.

License: Geosoft Open License

classmethod sync(grid)[source]

Syncronize the Metadata for this Grid

Parameters

grid (str) – Grid name

New in version 7.0.

License: Geosoft Open License

classmethod user_preference_to_plot_as_colour_shaded_grid()[source]

Returns the global setting.

Returns

0 - User wishes to plot grids as regular (flat) grid 1 - User wishes to plot grids as color-shaded grids

Return type

int

New in version 7.3.

License: Geosoft Open License

write_v(v, be, ne, vv)[source]

Write a vector in the optimal KX direction.

Parameters
  • v (int) – Vector to write

  • be (int) – Begining element to write (0 is the first)

  • ne (int) – # elements to write (0 for whole vector)

  • vv (GXVV) – GXVV handle

New in version 5.0.

License: Geosoft Open License

write_x(bx, by, ny, vv)[source]

Write a column (constant X)

Parameters
  • bx (int) – X column

  • by (int) – Start Y to write

  • ny (int) – # Y to write (0 for whole vector)

New in version 5.0.

License: Geosoft Open License

write_y(by, bx, nx, vv)[source]

Write a row (constant Y)

Parameters
  • by (int) – Y row

  • bx (int) – Start X to write

  • nx (int) – # X write (0 for whole vector)

New in version 5.0.

License: Geosoft Open License

IMG_DISPLAY_PROPERTY constants

Image display property

IMG_SHADING_INCLINATION

Shading inclination

gxapi.IMG_SHADING_INCLINATION = 0
IMG_SHADING_DECLINATION

Shading declination

gxapi.IMG_SHADING_DECLINATION = 1
IMG_SHADING_SCALE

Shading scale

gxapi.IMG_SHADING_SCALE = 2
IMG_SHADING_CONTRAST

Shading contrast (0-1)

gxapi.IMG_SHADING_CONTRAST = 3
IMG_SHADING_BRIGHTNESS

Shading brightness (0-1)

gxapi.IMG_SHADING_BRIGHTNESS = 4
IMG_SHADING_WETLOOK

Shading wet look (0 or 1)?

gxapi.IMG_SHADING_WETLOOK = 5
IMG_COLOURS_REVERSED

Zone colours reversed from originals (0 or 1)?

gxapi.IMG_COLOURS_REVERSED = 6
IMG_SMOOTHING_ENABLED

Is smoothing enabled (0 or 1)?

gxapi.IMG_SMOOTHING_ENABLED = 7
IMG_SHADING_ENABLED

Is shading enabled (0 or 1)?

gxapi.IMG_SHADING_ENABLED = 8

IMG_FAULT constants

Fault type

IMG_FAULT_POLYLINE

Polyline

gxapi.IMG_FAULT_POLYLINE = 0
IMG_FAULT_POLYGON

Polygon

gxapi.IMG_FAULT_POLYGON = 1

IMG_FILE constants

Image open modes

IMG_FILE_READONLY

Reading only

gxapi.IMG_FILE_READONLY = 0
IMG_FILE_READWRITE

Reading and writting

gxapi.IMG_FILE_READWRITE = 2
IMG_FILE_READORWRITE

Allows you to open read-only grids to change the projection or location information. If you can write to the original grid (dat), the changed projection or location information will be passed on to the grid, otherwise changes will only occur in the .gi file.

gxapi.IMG_FILE_READORWRITE = 3

IMG_QUERY constants

Information to Query

IMG_QUERY_iWRITE

Iwrite

gxapi.IMG_QUERY_iWRITE = 0
IMG_QUERY_iPG

Ipg

gxapi.IMG_QUERY_iPG = 1
IMG_QUERY_iWRITEPG

Iwritepg

gxapi.IMG_QUERY_iWRITEPG = 2
IMG_QUERY_iIMGTYPE

The element type used to open the GXIMG.

gxapi.IMG_QUERY_iIMGTYPE = 3
IMG_QUERY_iDATTYPE

DATTYPE is the native element type of the GXDAT. Types are: 0 - byte 1 - unsigned 16-bit short 2 - 16-bit short 3 - 32-bit long 4 - 32-bit float 5 - 64-bit double

gxapi.IMG_QUERY_iDATTYPE = 4
IMG_QUERY_iRENDER

Render modes are: 0 - interpolate 1 - pixelate 2 - color

gxapi.IMG_QUERY_iRENDER = 5
IMG_QUERY_iKX

Ikx

gxapi.IMG_QUERY_iKX = 6
IMG_QUERY_iNX

Inx

gxapi.IMG_QUERY_iNX = 7
IMG_QUERY_iNY

Iny

gxapi.IMG_QUERY_iNY = 8
IMG_QUERY_iNV

Inv

gxapi.IMG_QUERY_iNV = 9
IMG_QUERY_iNE

Ine

gxapi.IMG_QUERY_iNE = 10
IMG_QUERY_rXO

Rxo

gxapi.IMG_QUERY_rXO = 11
IMG_QUERY_rYO

Ryo

gxapi.IMG_QUERY_rYO = 12
IMG_QUERY_rDX

Rdx

gxapi.IMG_QUERY_rDX = 13
IMG_QUERY_rDY

Rdy

gxapi.IMG_QUERY_rDY = 14
IMG_QUERY_rROT

Rrot

gxapi.IMG_QUERY_rROT = 15
IMG_QUERY_rBASE

Rbase

gxapi.IMG_QUERY_rBASE = 16
IMG_QUERY_rMULT

Rmult

gxapi.IMG_QUERY_rMULT = 17
IMG_QUERY_rCOMPRESSION_RATIO

Rcompression ratio

gxapi.IMG_QUERY_rCOMPRESSION_RATIO = 18

IMG_RELOCATE constants

Relocation Style

IMG_RELOCATE_FIT

Will fit the image to fill the specified area

gxapi.IMG_RELOCATE_FIT = 0
IMG_RELOCATE_ASPECT

Will maintain aspect ratio

gxapi.IMG_RELOCATE_ASPECT = 1