Cubes (e.g. seismic)

Cube

Functions

xtgeo.cube_from_file(mfile, fformat='guess', iline=189, xline=193)

This makes an instance of a Cube directly from file import.

Parameters:

• mfile (str) – Name of file

• fformat (str) – See Cube.from_file()

• iline (Literal[189, 193]) – Byte position of the inline number field in each trace header. Default is 189 (SEGY standard). Only 189 and 193 are valid; use iline=193, xline=189 for files with non-standard byte locations.

• xline (Literal[189, 193]) – Byte position of the crossline number field in each trace header. Default is 193 (SEGY standard). Must differ from iline.

Example:

>>> import xtgeo
>>> mycube = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")

xtgeo.cube_from_roxar(project, name, folder=None)

This makes an instance of a Cube directly from roxar input.

The folder is a string on form “a” or “a/b” if subfolders are present

Example:

import xtgeo
mycube = xtgeo.cube_from_roxar(project, "DepthCube")

Classes

class xtgeo.Cube(ncol, nrow, nlay, xinc, yinc, zinc, xori=0.0, yori=0.0, zori=0.0, yflip=1, values=0.0, rotation=0.0, zflip=1, ilines=None, xlines=None, traceidcodes=None, segyfile=None, filesrc=None)

Bases: object

Class for a (seismic) cube in the XTGeo framework.

The values are stored as a 3D numpy array (4 bytes; float32 is default), with internal C ordering (nlay fastest).

See xtgeo.cube_from_file() for importing cubes from e.g. segy files.

See also Cube section in documentation: docs/datamodel.rst

Examples:

>>> import xtgeo
>>> # a user defined cube:
>>> mycube = xtgeo.Cube(
...     xori=100.0,
...     yori=200.0,
...     zori=150.0,
...     ncol=40,
...     nrow=30,
...     nlay=10,
...     rotation=30,
...     values=0
... )

Parameters:

• xori – Origin in Easting coordinate

• yori – Origin in Northing coordinate

• zori – Origin in Depth coordinate, where depth is positive down

• ncol – Number of columns

• nrow – Number of columns

• nlay – Number of layers, starting from top

• rotation – Cube rotation, X axis is applied and “school-wise” rotation, anti-clock in degrees

• values – Numpy array with shape (ncol, nrow, nlay), C order, np.float32

• ilines – 1D numpy array with ncol elements, aka INLINES array, defaults to arange

• xlines – 1D numpy array with nrow elements, aka XLINES array, defaults to arange

• segyfile – Name of source segyfile if any

• filesrc – String: Source file if any

• yflip – Normally 1; if -1 Y axis is flipped –> from left-handed (1) to right handed (-1). Right handed cubes are common.

Initiate a Cube instance.

Public Data Attributes:

metadata	Return metadata object instance of type MetaDataRegularSurface.
ncol	The NCOL (NX or I dir) number (read-only).
nrow	The NROW (NY or J dir) number (read-only).
nlay	The NLAY (or NZ or K dir) number (read-only).
dimensions	The cube dimensions with 3 integers (read only).
xori	The XORI (origin corner) coordinate.
yori	The YORI (origin corner) coordinate.
zori	The ZORI (origin corner) coordinate.
xinc	The XINC (increment X) as property.
yinc	The YINC (increment Y).
zinc	The ZINC (increment Z).
rotation	The rotation, anticlock from X axis in degrees.
ilines	The inlines numbering vector.
xlines	The xlines numbering vector.
zslices	Return the time/depth slices as an int array (read only).
traceidcodes	The trace identifaction codes array (ncol, nrow).
yflip	The YFLIP indicator, 1 is normal, -1 means Y flipped.
zflip	The ZFLIP indicator, 1 is normal, -1 means Z flipped.
segyfile	The input segy file name (str), if any (or None) (read-only).
filesrc	The input file name (str), if any (or None) (read-only).
values	The values, as a 3D numpy (ncol, nrow, nlay), 4 byte float.

Public Methods:

generate_hash([hashmethod])	Return a unique hash ID for current instance.
describe([flush])	Describe an instance by printing to stdout or return.
copy()	Deep copy of a Cube() object to another instance.
swapaxes()	Swap the axes inline vs xline, keep origin.
resample(incube[, sampling, outside_value])	Resample a Cube object into this instance.
do_thinning(icol, jrow, klay)	Thinning the cube by removing every N column, row and/or layer.
do_cropping(icols, jrows, klays[, mode])	Cropping the cube by removing rows, columns, layers.
values_dead_traces(newvalue)	Set values for traces flagged as dead.
get_xy_value_from_ij(iloc, jloc[, ixline, ...])	Returns x, y coordinate from a single i j location.
compute_attributes_in_window(upper, lower[, ...])	Return a cube's attributes as a set of surfaces, given two input surfaces.
get_randomline(fencespec[, zmin, zmax, ...])	Get a randomline from a fence spesification.
to_file(sfile[, fformat, pristine, engine])	Export cube data to file.
to_roxar(project, name[, folder, propname, ...])	Export (transfer) a cube from a XTGeo cube object to Roxar data.

---

__init__(ncol, nrow, nlay, xinc, yinc, zinc, xori=0.0, yori=0.0, zori=0.0, yflip=1, values=0.0, rotation=0.0, zflip=1, ilines=None, xlines=None, traceidcodes=None, segyfile=None, filesrc=None)

Initiate a Cube instance.

compute_attributes_in_window(upper, lower, ndiv=10, interpolation='cubic', minimum_thickness=0.0)

Return a cube’s attributes as a set of surfaces, given two input surfaces.

The attributes are computed vertically (per column) within a window defined by the two input surfaces and/or levels.

The statistical measures can be min, max, mean, variance etc. A complete list of supported attributes is given below.

• ‘max’ for maximum

• ‘min’ for minimum

• ‘rms’ for root mean square

• ‘mean’ for expected value

• ‘var’ for variance (population var; https://en.wikipedia.org/wiki/Variance)

• ‘maxpos’ for maximum of positive values

• ‘maxneg’ for negative maximum of negative values

• ‘maxabs’ for maximum of absolute values

• ‘sumpos’ for sum of positive values using cube sampling resolution

• ‘sumneg’ for sum of negative values using cube sampling resolution

• ‘meanabs’ for mean of absolute values

• ‘meanpos’ for mean of positive values

• ‘meanneg’ for mean of negative values

• ‘upper’ will return a copy of the upper surface applied

• ‘lower’ will return a copy of the lower surface applied

Parameters:

• upper (RegularSurface | float) – The uppermost surface or constant level to compute within.

• lower (RegularSurface | float) – The lower surface or level to compute within.

• ndiv (int) – Number of intervals for sampling within zrange. Default is 10. using 0.1 of cube Z increment as basis. A higher ndiv will increase CPU time and memory usage, but also increase the precision of the result.

• interpolation (Literal['cubic', 'linear']) – ‘cubic’ or ‘linear’ for interpolation of the seismic signal, default here is ‘cubic’.

• minimum_thickness (float) – Minimum thickness (isochore or isochron) between the two surfaces. If the thickness is less or equal than this value, the result will be masked. Default is 0.0.

Return type:

dict[RegularSurface]

Example:

>>> import xtgeo
>>> cube = xtgeo.cube_from_file("mycube.segy")
>>> surf = xtgeo.surface_from_file("topreek.gri")
>>> # sample in a total range of 30 m, 15 units above and 15 units below:
>>> attrs = cube.compute_attributes_in_window((surf-15), (surf + 15))
>>> attrs["max"].to_file("max.gri")  # save the 'max' attribute to file

Note

This method is a significantly improved version of the slice_cube_window() method within RegularSurface(), and it is strongly recommended to replace the former with this as soon as possible.

Added in version 4.1.

copy()

Deep copy of a Cube() object to another instance.

>>> mycube = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> mycube2 = mycube.copy()

describe(flush=True)

Describe an instance by printing to stdout or return.

Parameters:

flush (bool) – If True, description is printed to stdout.

property dimensions

The cube dimensions with 3 integers (read only).

Type:

NamedTuple

do_cropping(icols, jrows, klays, mode='edges')

Cropping the cube by removing rows, columns, layers.

Note that input boundary checking is currently lacking, and this is a currently a user responsibility!

The ‘mode’ is used to determine to different ‘approaches’ on cropping. Examples for icols and mode ‘edges’: Here the tuple (N, M) will cut N first rows and M last rows.

However, if mode is ‘inclusive’ then, it defines the range of rows to be included, and the numbering now shall be the INLINE, XLINE and DEPTH/TIME mode.

Parameters:

• icols (int tuple) – Cropping front, end of rows, or inclusive range

• jrows (int tuple) – Cropping front, end of columns, or inclusive range

• klays (int tuple) – Cropping top, base layers, or inclusive range.

• mode (str) – ‘Default is ‘edges’; alternative is ‘inclusive’

Example

Crop 10 columns from front, 2 from back, then 20 rows in front, 40 in back, then no cropping of layers:

>>> import xtgeo
>>> mycube1 = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> mycube2 = mycube1.copy()
>>> mycube1.do_cropping((10, 2), (20, 40), (0, 0))
>>> mycube1.to_file(outdir + '/mysegy_smaller.segy')

In stead, do cropping as ‘inclusive’ where inlines, xlines, slices arrays are known:

>>> mycube2.do_cropping((11, 32), (112, 114), (150, 200))

do_thinning(icol, jrow, klay)

Thinning the cube by removing every N column, row and/or layer.

Parameters:

• icol (int) – Thinning factor for columns (usually inlines)

• jrow (int) – Thinning factor for rows (usually xlines)

• klay (int) – Thinning factor for layers

Raises:

ValueError – If icol, jrow or klay are out of reasonable range

Example

>>> mycube1 = Cube(cube_dir + "/ib_test_cube2.segy")
>>> mycube1.do_thinning(2, 2, 1)  # keep every second column, row
>>> mycube1.to_file(outdir + '/mysegy_smaller.segy')

property filesrc

The input file name (str), if any (or None) (read-only).

generate_hash(hashmethod='md5')

Return a unique hash ID for current instance.

See generic_hash() for documentation.

Added in version 2.14.

get_randomline(fencespec, zmin=None, zmax=None, zincrement=None, hincrement=None, atleast=5, nextend=2, sampling='nearest')

Get a randomline from a fence spesification.

This randomline will be a 2D numpy with depth/time on the vertical axis, and length along as horizontal axis. Undefined values will have the np.nan value.

The input fencespec is either a 2D numpy where each row is X, Y, Z, HLEN, where X, Y are UTM coordinates, Z is depth/time, and HLEN is a length along the fence, or a Polygons instance.

If input fencspec is a numpy 2D, it is important that the HLEN array has a constant increment and ideally a sampling that is less than the Cube resolution. If a Polygons() instance, this is automated!

Parameters:

• fencespec (ndarray or Polygons) – 2D numpy with X, Y, Z, HLEN as rows or a xtgeo Polygons() object.

• zmin (float) – Minimum Z (default is Cube Z minima/origin)

• zmax (float) – Maximum Z (default is Cube Z maximum)

• zincrement (float) – Sampling vertically, default is Cube ZINC/2

• hincrement (float or bool) – Resampling horizontally. This applies only if the fencespec is a Polygons() instance. If None (default), the distance will be deduced automatically.

• atleast (int) – Minimum number of horizontal samples (only if fencespec is a Polygons instance)

• nextend (int) – Extend with nextend * hincrement in both ends (only if fencespec is a Polygons instance)

• sampling (str) – Algorithm, ‘nearest’ or ‘trilinear’ (first is faster, second is more precise for continuous fields)

Returns:

(hmin, hmax, vmin, vmax, ndarray2d)

Return type:

A tuple

Raises:

ValueError – Input fence is not according to spec.

Changed in version 2.1: support for Polygons() as fencespec, and keywords hincrement, atleast and sampling

See also

Class Polygons

The method get_fence() which can be used to pregenerate fencespec

get_xy_value_from_ij(iloc, jloc, ixline=False, zerobased=False)

Returns x, y coordinate from a single i j location.

Parameters:

• iloc (int) – I (col) location (base is 1)

• jloc (int) – J (row) location (base is 1)

• ixline (bool) – If True, then input locations are inline and xline position

• zerobased (bool) – If True, first index is 0, else it is 1. This does not apply when ixline is set to True.

Returns:

The X, Y coordinate pair.

property ilines

The inlines numbering vector.

property metadata

Return metadata object instance of type MetaDataRegularSurface.

property ncol

The NCOL (NX or I dir) number (read-only).

property nlay

The NLAY (or NZ or K dir) number (read-only).

property nrow

The NROW (NY or J dir) number (read-only).

resample(incube, sampling='nearest', outside_value=None)

Resample a Cube object into this instance.

Parameters:

• incube (Cube) – A XTGeo Cube instance

• sampling (str) – Sampling algorithm: ‘nearest’ for nearest node of ‘trilinear’ for trilinear interpoltion (more correct but slower)

• outside_value (None or float) – use this value

Raises:

ValueError – If cubes do not overlap

Example

>>> import xtgeo
>>> mycube1 = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> mycube2 = xtgeo.Cube(
...     xori=777574,
...     yori=6736507,
...     zori=1000,
...     xinc=10,
...     yinc=10,
...     zinc=4,
...     ncol=100,
...     nrow=100,
...     nlay=100,
...     yflip=mycube1.yflip,
...     rotation=mycube1.rotation
... )
>>> mycube2.resample(mycube1)

property rotation

The rotation, anticlock from X axis in degrees.

property segyfile

The input segy file name (str), if any (or None) (read-only).

swapaxes()

Swap the axes inline vs xline, keep origin.

to_file(sfile, fformat='segy', pristine=False, engine=None)

Export cube data to file.

Parameters:

• sfile (str) – Filename

• fformat (str, optional) – file format ‘segy’ (default) or ‘rms_regular’

• pristine (bool) – If True, make SEGY from scratch.

• engine (str) – Which “engine” to use.

Example::

>>> import xtgeo
>>> zz = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> zz.to_file(outdir + '/some.rmsreg')

to_roxar(project, name, folder=None, propname='seismic_attribute', domain='time', compression=('wavelet', 5.0), target='seismic')

Export (transfer) a cube from a XTGeo cube object to Roxar data.

Note

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Parameters:

• project (Any) – Inside RMS use the magic ‘project’, else use path to RMS project, or a project reference

• name (str) – Name of cube (seismic data) within RMS project.

• folder (str | None) – Cubes may be stored under a folder in the tree, use ‘/’ to seperate subfolders.

• propname (str) – Name of grid property; only relevant when target is “grid” and defaults to “seismic_attribute”

• domain (str) – ‘time’ (default) or ‘depth’

• compression (tuple[str, float]) – Reference to Roxar API ‘compression method’ and ‘compression tolerance’, but implementation is pending. Hence inactive.

• target (str) – Optionally, the seismic cube can be written to the Grid model tree in RMS. Internally, it will be convert to a “box” grid with one gridproperty, before it is written to RMS. The compression``and ``domain are not relevant when writing to grid model.

Raises:

To be described... –

Example:

zz = xtgeo.cube_from_file('myfile.segy')
zz.to_roxar(project, 'reek_cube')
# write cube to "Grid model" tree in RMS instead
zz.to_roxar(project, 'cube_as_grid', propname="impedance", target="grid")

Changed in version 3.4: Add target and propname keys

property traceidcodes

The trace identifaction codes array (ncol, nrow).

property values

The values, as a 3D numpy (ncol, nrow, nlay), 4 byte float.

values_dead_traces(newvalue)

Set values for traces flagged as dead.

Dead traces have traceidcodes 2 and corresponding values in the cube will here receive a constant value to mimic “undefined”.

Parameters:

newvalue (float) – Set cube values to newvalues where traceid is 2.

Returns:

The estimated simple ‘average’ of old value will

be returned as (max + min)/2. If no dead traces, return None.

Return type:

oldvalue (float)

property xinc

The XINC (increment X) as property.

property xlines

The xlines numbering vector.

property xori

The XORI (origin corner) coordinate.

property yflip

The YFLIP indicator, 1 is normal, -1 means Y flipped.

YFLIP = 1 means a LEFT HANDED coordinate system with Z axis positive down, while inline (col) follow East (X) and xline (rows) follows North (Y), when rotation is zero.

property yinc

The YINC (increment Y).

property yori

The YORI (origin corner) coordinate.

property zflip

The ZFLIP indicator, 1 is normal, -1 means Z flipped.

ZFLIP = 1 and YFLIP = 1 means a LEFT HANDED coordinate system with Z axis positive down, while inline (col) follow East (X) and xline (rows) follows North (Y), when rotation is zero.

property zinc

The ZINC (increment Z).

property zori

The ZORI (origin corner) coordinate.

property zslices

Return the time/depth slices as an int array (read only).