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 theGXPG
class is recommended (seeGXPG
andGXPGU
); theGXIMG
is first created, then theGXPG
is obtained from theGXIMG
usingget_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.- add_fault(xVV, yVV, type)[source]¶
Add a fault trace
- Parameters:
type (int) – Fault type IMG_FAULT constants
- 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.
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:
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:
type (int) – Data type, GS_TYPES constants or
GS_TYPE_DEFAULT
to use nativeGXDAT
type.grid (str) – Name of the Grid to link to
mode (int) – Grid file open mode IMG_FILE constants
- Returns:
GXIMG
object- Return type:
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 ofGS_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:
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:
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:
type (int) – Data type, GS_TYPES constants or
GS_TYPE_DEFAULT
grid (str) – Name of the Grid to link to
img (GXIMG) – Input Image for new image creation
- Returns:
GXIMG
object- Return type:
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 ofGS_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 isrDUMMY
(GS_R8DM
), one is automatically calculated, as withcreate_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 isrDUMMY
(GS_R8DM
), one is automatically calculated, as withcreate_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 thecreate_projected
andcreate_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 torDUMMY
, 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:
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.
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.
New in version 5.0.
License: Geosoft Open License
Note: Returns the cell size calculated by CreateProjected_PJIMG, or by
create_projected2
whenGS_R8DM
is entered as the optional cell size. No inheritance is actually performed to the inputGXIMG
.
- 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.
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 inputGXIPJ
is identical to the originalGXIPJ
, 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
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 masterGXIMG
.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
- 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:
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:
query (int) – IMG_DISPLAY_PROPERTY constants
value (float) – Value
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
, asset_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:
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_FAULT constants¶
Fault type
IMG_FILE constants¶
Image open modes
- 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_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_RELOCATE constants¶
Relocation Style