VolumeDef schema

VolumeDef is a simple, versioned, flexible format for describing which grid points of a seismic volume contain data.

The grid is described per line. Each line contains a series of descriptors that specify the points on the axis perpendicular to the line. For example, a volumedef that is indexed as inline-major will use inline numbers as keys in the lines object, and have descriptors with crossline numbers.

Format of a VolumeDef object

VolumeDefs are transmitted as plaintext JSON objects.

As of version 102, three keys are required: version, direction, and lines, and the key sample_count is optional.

• version must contain an integer value. Major version changes are indicated by incrementing by 100, while minor version changes increment by 1. The current version is 102.
• direction must have the value of either inline or crossline, declaring which dimension is used as the outer dimension of the VolumeDef, and the direction in which the line descriptor increments.
• lines contains the meat of the volumedef: An object, keyed by the line numbers (as strings) of the dimension described in the direction key, and each key containing an array with one or more descriptors detailing which inner dimension line numbers the volume contains trace data for.
• sample_count indicates the number of samples in each trace, if available.

JSON format

{
    "version": 102,
    "direction": "inline",  // Either "inline" or "crossline"
    "lines": {
        // A given line number, e.g. 101
        "$lineid_1": [
            /** Descriptors... **/
        ],
        "$lineid-2": [
            /** Descriptors... **/
        ]
   },
   "sample_count": 10, // An unsigned integer
}

Descriptors

A descriptor object (as of version 102) contains only a single field or key/value pair. The key string defines the type of the descriptor object, and the value of the field is a type-specific description of the existing line identifiers included in the inner dimension.

There are two types of descriptor objects, range and list.

The descriptors in a single line may not overlap.

Range

Describe a range of coordinates as an inclusive start, inclusive end, and a step (interval) between points. The step is optional, and will be assumed to be 1 if omitted. These two or three numbers are simply stored in an array.

This is currently the most compact representation, for ranges that include at least 4 coordinates, and VolumeDefs should prefer ranges when possible.

[
   // This range descriptor includes the coordinates 0, 1, ... 119, 120.
   {
       "range": [0, 120]
   },

   // This range descriptor includes the coordinates 151, 153, ... 301, 303.
   {
       "range": [151, 303, 2]
   }
]

List

Describe line numbers by explicitly listing them. This is the fallback type, guaranteed to be able to represent any kind of cutout.

[
    // This list descriptor includes the points listed.
    {
       "list": [9, 15, 39, 80, 120, 153]
    }
]

Complete example

This is an example of a volumedef for a small 5x5 grid with a corner cut off, and a hole in the middle. Inlines are numbered from 1..5, and crosslines are numbered from 10..18 with step 2: 10, 12, 14, 16, 18.

{
    "version": 102,
    "direction": "inline",
    "lines": {
        "1": [
            {
                "range": [12, 18, 2]  // Grid point at (1, 10) not included.
            }
        ],
        "2": [
            {
                "range": [10, 18, 2]
            }
        ],
        "3": [
            {
                "list": [10, 12, 16, 18]  // Hole at grid point (3, 14)
            }
        ],
        "4": [
            {
                "range": [10, 18, 2]
            }
        ],
        "5": [
            {
                "range": [10, 18, 2]
            }
        ]
   },
   "sample_count": 100
}

Using VolumeDefs

VolumeDefs provide useful information about the layout of a seismic grid. For example, you can count the number of traces in a seismic volume:

volumedef.count_total_traces()

This is useful for determining how large a created volume actually is in terms of data rather than area. You can also count the number of traces by line:

volumedef.count_line_traces()

This returns a dict mapping from integers, representing the major element (usually either inlines or xlines) to the number of traces in that line.

It is also possible to get the line ranges by inline or xline:

volumedef.get_inline_range()
volumedef.get_xline_range()

Both of these methods return a mapping of, respectively, inline or xline to the minimum and maximum values for the xline or inline. For example, if get_inline_range() returns a map {1: (2, 4), 2: (3, 5)}, it means that the range of xline values for the volumedef is 2~4 on inline 1, and 3~5 on inline 2.