GXIMG class

class GXIMG(handle=0)

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.

classmethod average2(grid_in, grid_out)

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)

Copy IMGs.

Parameters:im_go (GXIMG) – Target GXIMG

New in version 5.0.

License: Geosoft Open License

classmethod create(type, kx, width, height)

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)

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)

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)

Creates an output image file using User defined info.

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

Note: Special Note for developers who use this function and related functions to output ERMapper image (ERS, ECW) files:

This function internally called ERMapper plugin to create ERS header files. To find the location of ERMapper plugin library, a registry setting needs to set. The key in the registry is HKEY_LOCAL_MACHINESOFTWARE”MyProgram(libversion7.0)” and in that key register a string BASE_PATH = D:Oasismontajpluginser_mapper. MyProgram is the name of your application and D:Oasismontajpluginser_mapper is the location of ERMapper library.

It is recommended that this registry key is set during the installation of your application.

classmethod create_out_file(type, grid, img)

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)

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)

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)

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.

e_type()

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)

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

get_def_itr(itr)

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_double_parameter(name)

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_info(dx, dy, xo, yo, rot)

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)

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)

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)

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)

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_tr(tr)

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)

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()

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)

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)

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()

Is this a Geosoft color grid?

Return type:bool

New in version 6.0.1.

License: Geosoft Open License

is_null()

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)

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)

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)

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()

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

New in version 5.0.

License: Geosoft Open License

ne()

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()

A null (undefined) instance of GXIMG

Returns:A null GXIMG
Return type:GXIMG
nv()

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()

Gets the # of X elements.

Returns:# of X elements.
Return type:int

New in version 5.0.

License: Geosoft Open License

ny()

Gets the # of Y elements.

Returns:# of Y elements.
Return type:int

New in version 5.0.

License: Geosoft Open License

opt_kx(kx)

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)

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)

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()

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)

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)

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)

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)

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)

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)

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)

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)

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_double_parameter(name, value)

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()

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)

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)

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)

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)

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_tr(tr)

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)

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()

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)

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)

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)

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_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