GXIMG class¶

class geosoft.gx.GXIMG¶

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

Note:

The IMG 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:

geosoft.gx.GXIMG.create_new_file()(GS_DOUBLE,1,100,100,"mag.grd");
   -> creates a new grid file "mag.grd" with all defaults.

geosoft.gx.GXIMG.create_new_file()(GS_DOUBLE,1,100,100,"mag.grd(GRD;comp=none)");
   -> creates a new grid file "mag.grd" with no compression.

geosoft.gx.GXIMG.create_new_file()(GS_DOUBLE,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.DOC for information about file name decorations available
for all DAT 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.

static average2((GXContext)ctx, (str)arg1, (str)arg2) → None:¶

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

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (str) – Name of source Grid arg2 (str) – Name of output Grid
Returns:	Nothing
Return type:	None

New in version 5.0.0.

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((GXIMG)arg1) → None:¶

Copy IMGs.

Parameters:	arg1 (`geosoft.gx.GXIMG`) – target IMG
Returns:	Nothing
Return type:	None

New in version 5.0.0.

static create((GXContext)ctx, (int)arg1, (int)arg2, (int)arg3, (int)arg4) → GXIMG:¶

Creates an IMG not tied to a file at all

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (int) – Data type GS_TYPES constants arg2 (int) – Grid orientation (KX): 1 (rows in X) -1 (rows in Y) arg3 (int) – Grid width arg4 (int) – Grid height
Returns:	IMG Object
Return type:	`geosoft.gx.GXIMG`

New in version 5.0.3.

Note:

Once destroyed all the data in this IMG is lost.

static create_file((GXContext)ctx, (int)arg1, (str)arg2, (int)arg3) → GXIMG:¶

Creates an Image object tied to a grid file.

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (int) – Data type, GS_TYPES constants or GS_TYPE_DEFAULT to use native DAT type. arg2 (str) – Name of the Grid to link to arg3 (int) – Grid File Open Mode IMG_FILE constants
Returns:	IMG Object
Return type:	`geosoft.gx.GXIMG`

New in version 5.0.0.

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 colour data as opposed
to real numbers.

static create_mem((GXContext)ctx, (int)arg1, (int)arg2, (int)arg3, (int)arg4) → GXIMG:¶

Creates an IMG object that is backed only by memory.

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (int) – Data type, GS_TYPES constants arg2 (int) – Grid orientation (KX): 1 (rows in X) -1 (rows in Y) arg3 (int) – Grid width arg4 (int) – Grid height
Returns:	IMG Object
Return type:	`geosoft.gx.GXIMG`

New in version 5.0.6.

Note:

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

static create_new_file((GXContext)ctx, (int)arg1, (int)arg2, (int)arg3, (int)arg4, (str)arg5) → GXIMG:¶

Creates an output image file using User defined info.

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (int) – Data type, GS_TYPES constants Cannot be GS_TYPE_DEFAULT arg2 (int) – Grid orientation (KX): 1 (rows in X) -1 (rows in Y) arg3 (int) – Grid width arg4 (int) – Grid height arg5 (str) – Name of the Grid to link to
Returns:	IMG Object
Return type:	`geosoft.gx.GXIMG`

New in version 5.0.0.

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.

static create_out_file((GXContext)ctx, (int)arg1, (str)arg2, (GXIMG)arg3) → GXIMG:¶

Creates an output image file using input image info.

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (int) – Data type, GS_TYPES constants or GS_TYPE_DEFAULT arg2 (str) – Name of the Grid to link to arg3 (`geosoft.gx.GXIMG`) – Input Image for new image creation
Returns:	IMG Object
Return type:	`geosoft.gx.GXIMG`

New in version 5.0.0.

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 colour data as opposed
to real numbers.

create_projected((GXIPJ)arg1) → None:¶

Applies a projection to an image.

Parameters:	arg1 (`geosoft.gx.GXIPJ`) – Projection to apply
Returns:	Nothing
Return type:	None

New in version 5.0.0.

Note:

The IMG now appears to be in the projected coordinate
system space.

create_projected2((GXIPJ)arg1, (float)arg2) → None:¶

Applies a projection to an image, specify cell size.

Parameters:	arg1 (`geosoft.gx.GXIPJ`) – Projection to apply arg2 (float) – Cell size
Returns:	Nothing
Return type:	None

New in version 5.0.0.

Note:

The IMG 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 geosoft.gx.GXIMG.create_projected().

create_projected3((GXIPJ)arg1, (float)arg2, (float)arg3) → None:¶

Same as geosoft.gx.GXIMG.create_projected2(), but set expansion of bounds.

Parameters:	arg1 (`geosoft.gx.GXIPJ`) – Projection to apply arg2 (float) – Cell size arg3 (float) – Expansion percent (>=0).
Returns:	Nothing
Return type:	None

New in version 6.3.1.

Note:

The IMG 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 geosoft.gx.GXIMG.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 geosoft.gx.GXIMG.create_projected()
and geosoft.gx.GXIMG.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() → int:¶

Returns the element type.

Returns:	Element type
Return type:	int

New in version 5.0.0.

Note:

Same as sElementType_IMG(img,1)

element_type((int)arg1) → int:¶

Returns the element type.

Parameters:	arg1 (int) – 0 for XGD, 1 for IMG
Returns:	Element type
Return type:	int

New in version 5.0.5.

get_def_itr((GXITR)arg1) → int:¶

Get default transform, if it exists

Parameters:	arg1 (`geosoft.gx.GXITR`) – transform
Returns:	0 - Okay 1 - No default possible/available
Return type:	int

New in version 5.0.2.

get_double_parameter((str)arg1) → float:¶

Store a real parameter in an IMG object

Parameters:	arg1 (str) – Parameter name (case insensitive)
Returns:	Parameter value, rDUMMY if not found.
Return type:	float

New in version 8.2.0.

get_info((float_ref)arg1, (float_ref)arg2, (float_ref)arg3, (float_ref)arg4, (float_ref)arg5) → None:¶

Retrieves location information about this image.

Parameters:	arg1 (`geosoft.gx.float_ref`) – X element separation arg2 (`geosoft.gx.float_ref`) – Y element separation arg3 (`geosoft.gx.float_ref`) – X location of first point arg4 (`geosoft.gx.float_ref`) – Y location of first point arg5 (`geosoft.gx.float_ref`) – grid X axis rotation deg. CCW from reference X
Returns:	Nothing
Return type:	None

New in version 5.0.0.

get_ipj((GXIPJ)arg1) → None:¶

Get the projection of a grid.

Parameters:	arg1 (`geosoft.gx.GXIPJ`) – Projection of the grid
Returns:	Nothing
Return type:	None

New in version 5.0.0.

get_meta((GXMETA)arg1) → None:¶

Get the metadata of a grid.

Parameters:	arg1 (`geosoft.gx.GXMETA`) – Metadata of the grid
Returns:	Nothing
Return type:	None

New in version 5.0.8.

get_pg((GXPG)arg1) → None:¶

Get a copy of the pager of a grid.

Parameters:	arg1 (`geosoft.gx.GXPG`) – PG object to hold pager of the grid
Returns:	Nothing
Return type:	None

New in version 5.0.0.

See also

geosoft.gx.GXIMG.get_pg() to get just a copy of the grid’s pager.

inherit((GXIPJ)arg1, (float)arg2) → None:¶

Inherit a projection/new cell size on the IMG.

Parameters:	arg1 (`geosoft.gx.GXIPJ`) – Projection arg2 (float) – Optional cell size
Returns:	Nothing
Return type:	None

New in version 5.0.0.

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 IPJ is identical to the original
IPJ, and the cell boundaries will be forced to be aligned
with the new cell size.

inherit_img((GXIMG)arg1) → None:¶

Make a grids match in size and coordinate system

Parameters:	arg1 (`geosoft.gx.GXIMG`) – source IMG
Returns:	Nothing
Return type:	None

New in version 5.1.8.

is_colour() → bool:¶

Is this a Geosoft colour grid?

Returns:	bool
Return type:	bool

New in version 6.0.1.

is_null() → bool¶

Check if the instance of geosoft.gx.GXIMG is null (undefined)

Returns:	True if this is a null instance of `geosoft.gx.GXIMG`, False otherwise.
Return type:	bool`

static is_valid_img_file((GXContext)ctx, (str)arg1) → bool:¶

Is this a valid IMG file?

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (str) – File to check
Returns:	bool
Return type:	bool

New in version 8.0.0.

static is_valid_img_file_ex((GXContext)ctx, (str)arg1, (str_ref)arg2) → bool:¶

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

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (str) – File to check arg2 (`geosoft.gx.str_ref`) – Error message registered if unable to open
Returns:	bool
Return type:	bool

New in version 8.0.1.

load_img((GXIMG)arg1) → None:¶

Loads an IMG into a master IMG.

Parameters:	arg1 (`geosoft.gx.GXIMG`) – IMG to load
Returns:	Nothing
Return type:	None

New in version 5.0.6.

Note:

The Cell sizes and projections must be the same.

load_into_pager() → None:¶

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

Returns:	Nothing
Return type:	None

New in version 5.0.0.

ne() → int:¶

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

static null() → GXIMG¶

A null (undefined) instance of geosoft.gx.GXIMG

Returns:	A null `geosoft.gx.GXIMG`
Return type:	`geosoft.gx.GXIMG`

nv() → int:¶

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

nx() → int:¶

Gets the # of X elements.

Returns:	# of X elements.
Return type:	int

New in version 5.0.0.

ny() → int:¶

Gets the # of Y elements.

Returns:	# of Y elements.
Return type:	int

New in version 5.0.0.

opt_kx((int)arg1) → None:¶

Force optimal KX as desired.

Parameters:	arg1 (int) – KX -1 by column 1 by row
Returns:	Nothing
Return type:	None

New in version 5.0.0.

Note:

This will force loading an image into a PG 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((int)arg1) → float:¶

Query information about the IMG

Parameters:	arg1 (int) – IMG_QUERY constants
Returns:	Information requested, dummy if unknown or invalid.
Return type:	float

New in version 5.0.5.

Note:

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

query_int((int)arg1) → int:¶

Query information about the IMG

Parameters:	arg1 (int) – IMG_QUERY constants
Returns:	Information requested, dummy if unknown or invalid.
Return type:	int

New in version 5.0.5.

Note:

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

query_kx() → int:¶

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

Returns:

`-1`	by Columns

0 - Rows or Columns are equally efficient. 1 - by Rows

Return type: int

New in version 5.0.0.

read_v((int)arg1, (int)arg2, (int)arg3, (GXVV)arg4) → None:¶

Read a vector in the optimal KX direction.

Parameters:	arg1 (int) – Vector to Read arg2 (int) – begining element # to read (0 is the first) arg3 (int) – # elements to read (0 for whole vector) arg4 (`geosoft.gx.GXVV`) – VV handle
Returns:	Nothing
Return type:	None

New in version 5.0.0.

read_x((int)arg1, (int)arg2, (int)arg3, (GXVV)arg4) → None:¶

Read a column (constant X)

Parameters:	arg1 (int) – X column arg2 (int) – start Y to read arg3 (int) – # Y to read (0 for whole vector) arg4 (`geosoft.gx.GXVV`) – VV
Returns:	Nothing
Return type:	None

New in version 5.0.0.

read_y((int)arg1, (int)arg2, (int)arg3, (GXVV)arg4) → None:¶

Read a row (constant Y)

Parameters:	arg1 (int) – Y row arg2 (int) – start X to read arg3 (int) – # X to read (0 for whole vector) arg4 (`geosoft.gx.GXVV`) – VV
Returns:	Nothing
Return type:	None

New in version 5.0.0.

static refresh_gi((GXContext)ctx, (str)arg1) → None:¶

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

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (str) – grid name
Returns:	Nothing
Return type:	None

New in version 7.0.0.

relocate((float)arg1, (float)arg2, (float)arg3, (float)arg4, (int)arg5) → None:¶

Re-locate a grid image.

Parameters:	arg1 (float) – area X minimum arg2 (float) – area Y minimum arg3 (float) – area X maximum arg4 (float) – area Y maximum arg5 (int) – IMG_RELOCATE constants
Returns:	Nothing
Return type:	None

New in version 5.0.0.

static report((GXContext)ctx, (str)arg1, (GXWA)arg2, (int)arg3, (int)arg4, (str)arg5) → None:¶

Writes grid info report to a file

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (str) – Grid name arg2 (`geosoft.gx.GXWA`) – Text file to write to arg3 (int) – recalc statistics (0 - no; 1 - yes) arg4 (int) – number of decimals to put in results arg5 (str) – Title for report
Returns:	Nothing
Return type:	None

New in version 5.0.0.

static report_csv((GXContext)ctx, (str)arg1, (GXWA)arg2, (int)arg3, (int)arg4, (int)arg5) → None:¶

Writes grid info as a line to a CSV file

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (str) – Grid name arg2 (`geosoft.gx.GXWA`) – Text file to write to arg3 (int) – recalc statistics (0 - no; 1 - yes) arg4 (int) – number of decimals to put in results arg5 (int) – Write header line (0 - no; 1 - yes)?
Returns:	Nothing
Return type:	None

New in version 6.4.2.

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((GXITR)arg1) → int:¶

Set default transform

Parameters:	arg1 (`geosoft.gx.GXITR`) – transform
Returns:	0 - Okay 1 - No default possible/available
Return type:	int

New in version 5.0.2.

set_double_parameter((str)arg1, (float)arg2) → None:¶

Store a real parameter in an IMG object

Parameters:	arg1 (str) – Parameter name (case insensitive) arg2 (float) – Parameter value to store
Returns:	Nothing
Return type:	None

New in version 8.2.0.

set_grid_unchanged() → None:¶

Mark the grid as unchanged so it will not output lineage

Returns:	Nothing
Return type:	None

New in version 7.0.0.

set_info((float)arg1, (float)arg2, (float)arg3, (float)arg4, (float)arg5) → None:¶

Sets location information about this image.

Parameters:	arg1 (float) – X element separation arg2 (float) – Y element separation arg3 (float) – X location of first point arg4 (float) – Y location of first point arg5 (float) – grid X axis rotation deg. CCW from reference X
Returns:	Nothing
Return type:	None

New in version 5.0.0.

Note:

Calls to this function should be made BEFORE calls to geosoft.gx.GXIMG.set_ipj(),
as the latter function sets up the bounding rectangle in the metadata.

set_ipj((GXIPJ)arg1) → None:¶

Set the projection of a grid.

Parameters:	arg1 (`geosoft.gx.GXIPJ`) – Projection
Returns:	Nothing
Return type:	None

New in version 5.0.0.

Note:

Calls to this function should be made AFTER calls to geosoft.gx.GXIMG.set_info(),
as geosoft.gx.GXIMG.set_ipj() sets up the bounding rectangle in the metadata.

set_meta((GXMETA)arg1) → None:¶

Set the metadata of a grid.

Parameters:	arg1 (`geosoft.gx.GXMETA`) – Metadata to add to the grid
Returns:	Nothing
Return type:	None

New in version 5.0.8.

set_pg((GXPG)arg1) → None:¶

Copy a pager into the pager of a grid.

Parameters:	arg1 (`geosoft.gx.GXPG`) – Pager object to copy into the pager of the grid
Returns:	Nothing
Return type:	None

New in version 5.0.0.

set_tr((GXTR)arg1) → None:¶

Set the trend information to a grid.

Parameters:	arg1 (`geosoft.gx.GXTR`) – Trend information to set for the grid
Returns:	Nothing
Return type:	None

New in version 5.0.0.

static sync((GXContext)ctx, (str)arg1) → None:¶

Syncronize the Metadata for this Grid

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context arg1 (str) – grid name
Returns:	Nothing
Return type:	None

New in version 7.0.0.

static user_preference_to_plot_as_colour_shaded_grid((GXContext)ctx) → int:¶

Returns the global setting.

Parameters:	ctx (`geosoft.gx.GXContext`) – The GX execution context
Returns:	0 - User wishes to plot grids as regular (flat) grid 1 - User wishes to plot grids as colour-shaded grids
Return type:	int

New in version 7.3.0.

write_v((int)arg1, (int)arg2, (int)arg3, (GXVV)arg4) → None:¶

Write a vector in the optimal KX direction.

Parameters:	arg1 (int) – vector to write arg2 (int) – begining element to write (0 is the first) arg3 (int) – # elements to write (0 for whole vector) arg4 (`geosoft.gx.GXVV`) – VV handle
Returns:	Nothing
Return type:	None

New in version 5.0.0.

write_x((int)arg1, (int)arg2, (int)arg3, (GXVV)arg4) → None:¶

Write a column (constant X)

Parameters:	arg1 (int) – X column arg2 (int) – start Y to write arg3 (int) – # Y to write (0 for whole vector) arg4 (`geosoft.gx.GXVV`) – VV
Returns:	Nothing
Return type:	None

New in version 5.0.0.

write_y((int)arg1, (int)arg2, (int)arg3, (GXVV)arg4) → None:¶

Write a row (constant Y)

Parameters:	arg1 (int) – Y row arg2 (int) – start X to write arg3 (int) – # X write (0 for whole vector) arg4 (`geosoft.gx.GXVV`) – VV
Returns:	Nothing
Return type:	None

New in version 5.0.0.

IMG_FILE constants¶

Image open modes

gx.IMG_FILE_READONLY = 0¶

Reading only

gx.IMG_FILE_READWRITE = 2¶

Reading and writting

gx.IMG_FILE_READORWRITE = 3¶

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.

IMG_QUERY constants¶

Information to Query

gx.IMG_QUERY_iWRITE = 0¶

gx.IMG_QUERY_iPG = 1¶

gx.IMG_QUERY_iWRITEPG = 2¶

gx.IMG_QUERY_iIMGTYPE = 3¶

The element type used to open the IMG.

gx.IMG_QUERY_iDATTYPE = 4¶

DATTYPE is the native element type of the DAT.
Types are:   0 - byte
- unsigned 16-bit short
- 16-bit short
- 32-bit long
- 32-bit float
- 64-bit double

gx.IMG_QUERY_iRENDER = 5¶

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

gx.IMG_QUERY_iKX = 6¶

gx.IMG_QUERY_iNX = 7¶

gx.IMG_QUERY_iNY = 8¶

gx.IMG_QUERY_iNV = 9¶

gx.IMG_QUERY_iNE = 10¶

gx.IMG_QUERY_rXO = 11¶

gx.IMG_QUERY_rYO = 12¶

gx.IMG_QUERY_rDX = 13¶

gx.IMG_QUERY_rDY = 14¶

gx.IMG_QUERY_rROT = 15¶

gx.IMG_QUERY_rBASE = 16¶

gx.IMG_QUERY_rMULT = 17¶

gx.IMG_QUERY_rCOMPRESSION_RATIO = 18¶

IMG_RELOCATE constants¶

Relocation Style

gx.IMG_RELOCATE_FIT = 0¶

will fit the image to fill the specified area

gx.IMG_RELOCATE_ASPECT = 1¶

will maintain aspect ratio

GXIMG class¶

IMG_FILE constants¶

IMG_QUERY constants¶

IMG_RELOCATE constants¶

Table Of Contents

This Page

Parameters:	arg1 (float) – X location in the grid projection arg2 (float) – Y location in the grid projection
Returns:	Grid value
Return type:	float