GXITR class¶

class GXITR(handle=0)[source]¶

GXITR class.

The GXITR class provides access to GXITR files. An GXITR file maps ranges of values to specific colors. The GXITR object is typically used in conjunction with GXMVIEW objects (see GXMVIEW and GXMVU).

Note:

Histogram ranges and color zone ranges

Histogram bins are defined with inclusive minima and exclusive maxima; for instance if Min = 0 and Inc = 1, then the second bin would include all values z such that 0 <= z < 1 (the first bin has all values < 0).

Color zones used in displaying grids (GXITR, ZON etc…) are the opposite, with exclusive minima and inclusive maxima. For instance, if a zone is defined from 0 to 1, then it would contain all values of z such that 0 < z <= 1.

These definitions mean that it is impossible to perfectly assign GXITR colors to individual bars of a histogram. The best work-around when the data values are integers is to define the color zones using 0.5 values between the integers. A general work-around is to make the number of histogram bins much larger than the number of color zones.

The ITR_NULL is used to hold a NULL handle to an GXITR class.

__init__(handle=0)[source]¶

change_brightness(brt)[source]¶

Change the brightness.

Parameters:: brt (float) – -1.0 - black; 0.0 no change; 1.0 white

New in version 5.0.

License: Geosoft Open License

Note: 0.0 brightness does nothing. -1.0 to 0.0 makes colors darker, -1.0 is black 0.0 to 1.0 makes colors lighter, 1.0 is white

color_value(val)[source]¶

Transform single data value to color

Parameters:: val (float) – Data value
Returns:: MVIEW_COLOR constants
Return type:: int

New in version 5.1.

License: Geosoft Open License

color_vv(vv_d, vv_c)[source]¶

Get color transform of a GXVV.

Parameters:

vv_d (GXVV) – Input GXVV of values (none-string)
vv_c (GXVV) – Output GXVV of colors (type INT)

New in version 5.1.6.

License: Geosoft Open License

Note: If the input value is a dummy, then the output color is 0 (no color).

copy(it_rs)[source]¶

Copies ITRs

Parameters:: it_rs (GXITR) – GXITR Source

New in version 5.0.

License: Geosoft Open License

classmethod create()[source]¶

Create an GXITR object

Returns:: GXITR object
Return type:: GXITR

New in version 5.0.

License: Geosoft Open License

classmethod create_file(file)[source]¶

Create an GXITR object from an itr, tbl, zon, lut file.

Parameters:: file (str) – File name, type determined from extension
Returns:: GXITR object
Return type:: GXITR

New in version 5.0.

License: Geosoft Open License

classmethod create_img(img, tbl, zone, contour)[source]¶

Create an GXITR for an image.

Parameters:

tbl (str) – Color table name, NULL for default
zone (int) – ITR_ZONE constants
contour (float) – Color contour interval or rDUMMY

Returns:

GXITR object

Return type:

New in version 5.1.

License: Geosoft Open License

Note: The ITR_ZONE_DEFAULT model will ask the GXIMG to provide a model if it can.

If a shaded relief model is selected, a shaded image will be created and a shaded image file will be created with the same name as the original grid but with the suffux “_s” added to the name part of the grid.

classmethod create_map(map, name)[source]¶

Create GXITR from Map with GXAGG Group name.

Parameters:

map (GXMAP) – GXMAP on which to place the view
name (str) – GXAGG Group name

Returns:

GXITR object

Return type:

New in version 5.0.

License: Geosoft Open License

classmethod create_s(bf)[source]¶

Create an GXITR object from a GXBF

Parameters:: bf (GXBF) – GXBF to serialize from
Returns:: GXITR object
Return type:: GXITR

New in version 5.0.

License: Geosoft Open License

classmethod default_color_method()[source]¶

Return the user-defined global default color method.

Returns:: One of ITR_ZONE_EQUALAREA, ITR_ZONE_LINEAR, ITR_ZONE_NORMAL or ITR_ZONE_LOGLINEAR
Return type:: int

New in version 9.4.

License: Geosoft Open License

equal_area(st, contour)[source]¶

Calculate an equal area transform.

Parameters:

st (GXST) – Stat object with a histogram
contour (float) – Color contour interval or dummy for none

New in version 5.1.2.

License: Geosoft Open License

Note: If the number of individual populated zones calculated using an equal-area ITR is less than the number of colours in the ITR, then an error message is displayed to that effect. If you want to avoid this error message in your work-flow, call EqualAreaOrLinear_ITR, which will apply a linear transform with the input number of colours, covering the whole range, should the equal-area transform have a problem, and no error message will appear, even if there is no valid data at all.

equal_area_or_linear(st, contour)[source]¶

Calculate an equal area transform.

Parameters:

st (GXST) – Stat object with a histogram
contour (float) – Color contour interval or dummy for none

New in version 2022.2.

License: Geosoft Open License

Note: If the number of individual populated zones calculated using an equal-area ITR is less than the number of colours in the ITR, then EqualArea_ITR displays an error message is displayed to that effect. If you want to avoid this error message in your work-flow, call this function, EqualAreaOrLinear_ITR, which will apply a linear transform with the input number of colours, covering the whole range, should the equal-area transform have a problem, and no error message will appear, even if there is no valid data at all.

get_brightness()[source]¶

Get the brightness setting of the GXITR

Returns:: The brightness setting of the GXITR
Return type:: float

New in version 5.0.

License: Geosoft Open License

Note: Brightness can range from -1.0 (black) to 1.0 (white). This brightness control is relative to the normal color when the GXITR is created.

See also

change_brightness, get_contrast, set_bright_contrast

get_contour()[source]¶

Get the contour value associated with the current transform model of the GXITR

Returns:: The contour setting of the GXITR
Return type:: float

New in version 2021.2.

License: Geosoft Open License

Note: The Linear, Normal and Equal-Area transforms accept a contour value as part of their definitions on creation. All the colour-breaks are rounded to the nearest integral multiple of the contour value (if defined). This function returns the value defined, and rDUMMY if none is defined.

get_contrast()[source]¶

Get the contrast setting of the GXITR

Returns:: The contrast setting of the GXITR
Return type:: float

New in version 2021.2.

License: Geosoft Open License

Note: Brightness can range from 0.0 (flat) to 1.0 (normal full contrast).

See also

change_brightness, GXAGG.get_brightness, set_bright_contrast

get_data_limits(min, max)[source]¶

Get GXITR max/min data limits.

Parameters:

min (float_ref) – Data minimum value (or rDUMMY if not set)
max (float_ref) – Data maximum value (or rDUMMY if not set)

New in version 6.0.

License: Geosoft Open License

Note: In some ITRs, especially those defined and embedded inside grid (GXIMG) objects, the actual data minimum and maximum values are stored. This function retrieves those values. This is NOT true of all GXITR objects, and in those cases dummy values will be returned.

get_name(name)[source]¶

Get the name of the GXITR.

Parameters:: name (str_ref) – Name returned

New in version 2021.2.

License: Geosoft Open License

get_reg()[source]¶

Get the GXITR’s GXREG

Returns:: GXREG object
Return type:: GXREG

New in version 5.0.

License: Geosoft Open License

get_size()[source]¶

Get the number of zones in an GXITR

Returns:: The number of zones.
Return type:: int

New in version 5.0.

License: Geosoft Open License

get_zone_active(zone)[source]¶

Get whether a zone of the GXITR is active (1) or rendered trasparent (0)

Parameters:: zone (int) – Number of the zone to set.
Return type:: int

New in version 2021.2.

License: Geosoft Open License

Note: Valid indices are 0 to N-1, where N is the size of the GXITR.

get_zone_base_color(zone, color)[source]¶

Get the base color in a zone of the GXITR

Parameters:

zone (int) – Number of the zone to set.
color (int_ref) – MVIEW_COLOR constants

New in version 2021.2.

License: Geosoft Open License

Note: Valid indices are 0 to N-1, where N is the size of the GXITR. The base colour is the colour in the ITR before any brightness is applied.

get_zone_color(zone, color)[source]¶

Get the color in a zone of the GXITR

Parameters:

zone (int) – Number of the zone to set.
color (int_ref) – MVIEW_COLOR constants

New in version 5.0.

License: Geosoft Open License

Note: Valid indices are 0 to N-1, where N is the size of the GXITR.

get_zone_model(model, parameters)[source]¶

Get the GXITR zone model (e.g. Linear, LogLin, Equal Area) and the accompanying values (if defined)

Parameters:

model (int_ref) – ITR_ZONE_MODEL constants
parameters (GXVV) – GXVV object (REAL): see notes for values returned

New in version 2021.2.

License: Geosoft Open License

Note: The following parameters are returned for the following values returned for ITR_ZONE_MODEL constants: ITR_ZONE_MODEL_LINEAR: [0]: Contour, [1]: Min, [2]: Max ITR_ZONE_MODEL_LOGLIN: [0]: Contour, [1]: Min, [2]: Max ITR_ZONE_MODEL_NORMAL: [0]: Contour, [1]: Mean, [2]: Standard Deviation, [3]: Exponent ITR_ZONE_MODEL_EQUAL: [0]: Contour All other types do not return any values (the VV will be empty).

get_zone_model_type()[source]¶

Get the GXITR zone model (e.g. Linear, LogLin, Equal Area).

Returns:: ITR_ZONE_MODEL constants
Return type:: int

New in version 6.4.

License: Geosoft Open License

Note: This function may be used to determine if a color transform is included in an GXITR.

get_zone_value(zone)[source]¶

Get the value in a zone of the GXITR

Parameters:: zone (int) – Number of the zone to set.
Returns:: The value of the specified zone.
Return type:: float

New in version 5.0.

License: Geosoft Open License

Note: Valid indices are 0 to N-2, where N is the size of the GXITR.

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

linear(min, max, contour)[source]¶

Calculate a linear transform.

Parameters:

min (float) – Minimum
max (float) – Maximum
contour (float) – Color contour interval or dummy for none

New in version 5.0.

License: Geosoft Open License

load_a(file)[source]¶

Load to an ASCII file, ZON, TBL or ER-Mapper LUT

Parameters:: file (str) – File name

New in version 5.1.6.

License: Geosoft Open License

log_linear(min, max, contour)[source]¶

Calculate a log transform.

Parameters:

min (float) – Minimum ( > 0)
max (float) – Maximum ( > minimum)
contour (float) – Color contour interval or dummy for none

New in version 5.0.

License: Geosoft Open License

Note: The function name is a misnomer. This is a pure log transform.

normal(std_dev, mean, exp, contour)[source]¶

Calculate a normal distribution transform.

Parameters:

std_dev (float) – Standard deviation
mean (float) – Mean
exp (float) – Expansion, normally 1.0
contour (float) – Color contour interval or dummy for none

New in version 5.1.2.

License: Geosoft Open License

classmethod null()[source]¶

A null (undefined) instance of GXITR

Returns:: A null GXITR
Return type:: GXITR

power_zone(pow)[source]¶

Modified GXITR zone values to 10 (or e) raized to the power of the values

Parameters:: pow (int) – ITR_POWER constants

New in version 5.0.

License: Geosoft Open License

save_a(file)[source]¶

Save to an ASCII file, ZON, TBL or ER-Mapper LUT

Parameters:: file (str) – File name

New in version 5.1.2.

License: Geosoft Open License

save_file(file)[source]¶

Save to any type (based on the extension of the input file name).

Parameters:: file (str) – File name

New in version 8.2.

License: Geosoft Open License

serial(bf)[source]¶

Serialize an GXITR to a GXBF

Parameters:: bf (GXBF) – GXBF to serialize to

New in version 5.0.

License: Geosoft Open License

classmethod set_agg_map(map, name, itr)[source]¶

Set GXITR to an GXAGG in map

Parameters:

map (GXMAP) – GXMAP on which to place the view
name (str) – GXAGG group name
itr (GXITR) – GXITR object to set

New in version 5.0.

License: Geosoft Open License

Note: See the create_map function

set_bright_contrast(brt, con)[source]¶

Set the brightness of the GXITR colors

Parameters:

brt (float) – 0.0 - black; 0.5 normal; 1.0 white
con (float) – 0.0 - flat; 1.0 normal

New in version 5.0.

License: Geosoft Open License

Note: Brightness settings: 0.0 - black 0.5 - normal (no change) 1.0 - white

Contrast 0.0 - flat 1.0 - full contrast (normal)

set_color_model(model)[source]¶

Set the color model of an GXITR.

Parameters:: model (int) – ITR_COLOR_MODEL constants

New in version 5.0.2.

License: Geosoft Open License

set_data_limits(min, max)[source]¶

Set GXITR max/min data limits.

Parameters:

min (float) – Data minimum value
max (float) – Data maximum value

New in version 6.3.

License: Geosoft Open License

set_name(name)[source]¶

Set the name of the GXITR.

Parameters:: name (str) – Name to set

New in version 2021.2.

License: Geosoft Open License

set_size(zones)[source]¶

Set the number of zones in an GXITR

Parameters:: zones (int) – Number of zones to set GXITR to.

New in version 5.0.

License: Geosoft Open License

set_zone_active(zone, active)[source]¶

Set whether a zone of the GXITR is active (1) or rendered trasparent (0)

Parameters:

zone (int) – Number of the zone to set.
active (int) – 1: active, 0: inactive (transparent)

New in version 2021.2.

License: Geosoft Open License

Note: Valid indices are 0 to N-1, where N is the size of the GXITR.

set_zone_base_color(zone, color)[source]¶

Set the color in a zone of the GXITR

Parameters:

zone (int) – Number of the zone to set.
color (int) – MVIEW_COLOR constants

New in version 2021.2.

License: Geosoft Open License

Note: “: Valid indices are 0 to N-1, where N is the size of the GXITR. This function modifies the “base” colours directly. The base colours have the current brightness applied to produce the rendered colours. The internal brightness remains unchanged.

set_zone_color(zone, color)[source]¶

Set the color in a zone of the GXITR

Parameters:

zone (int) – Number of the zone to set.
color (int) – MVIEW_COLOR constants

New in version 5.0.

License: Geosoft Open License

Note: “: Valid indices are 0 to N-1, where N is the size of the GXITR. This function modifies the colours as rendered, including applied brightness, and triggers an internal reset of the ITR brightness to zero, with all the “rendered” colours becoming the “base” colours.

set_zone_model(model, parameters)[source]¶

Set the GXITR zone model (e.g. Linear, LogLin, Equal Area) and the accompanying values (if defined)

Parameters:

model (int) – ITR_ZONE_MODEL constants
parameters (GXVV) – GXVV object (REAL): see notes for values returned

New in version 2021.2.

License: Geosoft Open License

Note: The following parameters are required for the following values of ITR_ZONE_MODEL constants: ITR_ZONE_MODEL_LINEAR: [0]: Contour, [1]: Min, [2]: Max ITR_ZONE_MODEL_LOGLIN: [0]: Contour, [1]: Min, [2]: Max ITR_ZONE_MODEL_NORMAL: [0]: Contour, [1]: Mean, [2]: Standard Deviation, [3]: Exponent ITR_ZONE_MODEL_EQUAL: [0]: Contour All other types do not require any values (the VV will be empty). NOTE: This will not change the actual ranges, so care is needed when using this function that the input specification accurately reflects the actual ranges.

set_zone_value(zone, value)[source]¶

Set the value in a zone of the GXITR

Parameters:

zone (int) – Number of the zone to set.
value (float) – The value to set

New in version 5.0.

License: Geosoft Open License

Note: Valid indices are 0 to N-2, where N is the size of the GXITR.

ITR_COLOR_MODEL constants¶

GXITR Color Model defines

ITR_COLOR_MODEL_HSV¶

Hsv

gxapi.ITR_COLOR_MODEL_HSV = 1¶

ITR_COLOR_MODEL_RGB¶

Rgb

gxapi.ITR_COLOR_MODEL_RGB = 2¶

ITR_COLOR_MODEL_CMY¶

Cmy

gxapi.ITR_COLOR_MODEL_CMY = 3¶

ITR_POWER constants¶

Power Zoning defines

ITR_POWER_10¶

Power of 10

gxapi.ITR_POWER_10 = 0¶

ITR_POWER_EXP¶

Exponential

gxapi.ITR_POWER_EXP = 1¶

ITR_ZONE constants¶

Zoning Methods

ITR_ZONE_DEFAULT¶

Default

gxapi.ITR_ZONE_DEFAULT = 0¶

ITR_ZONE_LINEAR¶

Linear

gxapi.ITR_ZONE_LINEAR = 1¶

ITR_ZONE_NORMAL¶

Normal

gxapi.ITR_ZONE_NORMAL = 2¶

ITR_ZONE_EQUALAREA¶

Equalarea

gxapi.ITR_ZONE_EQUALAREA = 3¶

ITR_ZONE_SHADE¶

Shade

gxapi.ITR_ZONE_SHADE = 4¶

ITR_ZONE_LOGLINEAR¶

Loglinear

gxapi.ITR_ZONE_LOGLINEAR = 5¶

ITR_ZONE_MODEL constants¶

GXITR Zone Model defines

ITR_ZONE_MODEL_NOZONE¶

The GXITR has no numeric zones defined (e.g. from a TBL file)

gxapi.ITR_ZONE_MODEL_NOZONE = -1¶

ITR_ZONE_MODEL_NONE¶

There is no specific zone model defined.

gxapi.ITR_ZONE_MODEL_NONE = 0¶

ITR_ZONE_MODEL_LINEAR¶

The GXITR is set up with a linear transform.

gxapi.ITR_ZONE_MODEL_LINEAR = 1¶

ITR_ZONE_MODEL_NORMAL¶

The GXITR is set up with a normal distribution transform.

gxapi.ITR_ZONE_MODEL_NORMAL = 2¶

ITR_ZONE_MODEL_EQUAL¶

The GXITR is set up with an equal area transform.

gxapi.ITR_ZONE_MODEL_EQUAL = 3¶

ITR_MODEL_LOGLIN¶

The GXITR is set up with a log-linear transform.

gxapi.ITR_MODEL_LOGLIN = 4¶

ITR_ZONE_MODEL_LOGLIN¶

The GXITR is set up with a log-linear transform.

gxapi.ITR_ZONE_MODEL_LOGLIN = 4¶