Protocol Documentation
Service for querying data and metadata from seismic tracestore in Cognite Data Fusion (CDF) seismic datastore.
Queries are done primarily on cubes, with some management endpoints for tracestores & partitions.
Queries are divided in:
- Metadata: General information and headers for surveys and files
- Trace: Retrieve traces, be it by geometry, line or volume
- Artificial sampling: Get the (calculated/interpolated) values of properties in the file/tracestore given arbitrary positions
| Method Name | Request Type | Response Type | Description |
|---|
| CreateSurvey | CreateSurveyRequest | Survey | Creates a Survey object in the data model. A Survey object represents a grouping of seismic data in the same area and normally sharing acquisition and most processing parameters. Capabilities: Requires Seismic:WRITE capability to the CDF tenant. |
| SearchSurveys | SearchSurveysRequest | SearchSurveyResponse stream | Lists all surveys accessible to the client. Optionally includes Cubes associated with the surveys. Can optionally search surveys based on both/either of two criteria: Coverage polygon of files in the survey are within an area delimited by a specified polygon Filters on metadata of both the survey and the file |
| EditSurvey | EditSurveyRequest | Survey | Modify the metadata for a survey. |
| DeleteSurvey | DeleteSurveyRequest | DeleteSurveyResponse | Deletes a specified survey. Must have ALL scope and Write capabilities. In the case of Surveys, the "name" should be input into the external_ids field of the Identifier. |
| CreateSeismic | CreateSeismicRequest | Seismic | Create new Seismics and assign them to partitions. Seismics are mostly immutable save for their name and metadata. The user needs to delete an existing cutout and create a new one if e.g. the definition or the seismic store must be changed |
| SearchSeismics | SearchSeismicsRequest | Seismic stream | Returns Seismic metadata given its id. Can optionally retrieve seismic store & partition info if user has the right scope. Use GetVolume to retrieve traces. |
| EditSeismic | EditSeismicRequest | Seismic | Edit the specified seismic. Seismic object names and metadata can be changed. The cutout definition, however, cannot be changed. To modify the definition or the owning partition, delete the seismic object and create a new one. |
| DeleteSeismic | DeleteSeismicRequest | DeleteSeismicResponse | Delete seismic objects. |
| SearchSeismicStores | SearchSeismicStoresRequest | SeismicStore stream | Search and retrieve seismic stores. Can only retrieve seismic stores you own. |
| EditSeismicStore | EditSeismicStoreRequest | SeismicStore | Set the name of a seismic store object. |
| DeleteSeismicStore | DeleteSeismicStoreRequest | DeleteSeismicStoreResponse | Delete a seismic store. If any seismics still reference the specified seismic store, the request will fail. |
| CreatePartition | CreatePartitionRequest | Partition | Create a data partition, optionally setting a name. |
| SearchPartitions | SearchPartitionsRequest | Partition stream | Returns the partition(s) specified, with the same search options as the other search endpoints. |
| EditPartition | EditPartitionRequest | Partition | Edit partitions. The only modifiable field is the name |
| DeletePartition | DeletePartitionRequest | DeletePartitionResponse | Delete the specified partition, and return whether it was successfully deleted. |
| GetVolume | VolumeRequest | .com.cognite.seismic.Trace stream | Request a volume of traces by range of inlines, crosslines and time |
| GetSegYFile | SegYSeismicRequest | SegYSeismicResponse stream | Fetch seismic data in SEG-Y format. The stream of responses each contain a byte array that must be written sequentially to a file to produce a SEG-Y file. The ordering of traces in the output is unspecified.The request object can be used to specify whether the file should contain the whole set of traces in the source dataset or a subset of the traces (ie. a cropped file). See SegYSeismicRequest for more information. Returns a stream of SegYSeismicResponse objects, each containing a fragment of a SEG-Y data stream. |
| SearchFiles | SearchFilesRequest | .com.cognite.seismic.File stream | Retrieves File objects describing the seismic files registered with the tenant. Search criteria can be specified in the SearchFilesRequest, restricting the data retrieved to a subset of the files in the tenant. See SearchFilesRequest for more information. Returns a stream of file objects, terminating all files matching the search criteria have been returned. |
Top
Messages that describe requests/responses from the Seismic Datastore in Cognite Data Fusion
| Field | Type | Label | Description |
|---|
| name | string | | optional name |
| external_id | string | | not optional externalid |
| Field | Type | Label | Description |
|---|
| success | bool | | |
| Field | Type | Label | Description |
|---|
| succeeded | bool | | |
| Field | Type | Label | Description |
|---|
| succeeded | bool | | |
| Field | Type | Label | Description |
|---|
| success | bool | | |
| Field | Type | Label | Description |
|---|
| partition | Identifier | | Must uniquely identify a partition |
| new_name | string | | |
| Field | Type | Label | Description |
|---|
| seismic_store_id | int64 | | Deprecated. Use identifier instead. |
| name | google.protobuf.StringValue | | If not null will change the seismic store name |
| metadata | OptionalMap | | If not null, will replace the seismic store metadata |
| seismic_store | Identifier | | Uniquely identifies one seismic store |
| external_id | google.protobuf.StringValue | | If not null, will attempt to change the seismic store external id. Can fail if the new external id is not unique. |
Used to search files by id, extid, extid substring, name, name substring
| Field | Type | Label | Description |
|---|
| seismic_store | SearchSpec | | |
| survey | SearchSpec | | |
| include_file_info | bool | | If true, include File information in the response |
| include_volume_definitions | bool | | If true, includes inline/crossline volume definitions for store |
| include_headers | bool | | if true, include text and binary headers in the response |
| include_coverage | bool | | Deprecated. Use coverage instead. |
| coverage | CoverageSpec | | If specified, include coverage |
| Field | Type | Label | Description |
|---|
| survey | SearchSpec | | |
| seismic | SearchSpec | | |
| partition | SearchSpec | | Can only search on partitions you can see. |
| include_text_header | bool | | |
| include_binary_header | bool | | |
| include_line_range | bool | | |
| include_volume_definition | bool | | If true, include the volume definition blob |
| include_seismic_store | bool | | If true, include info on the backing seismicstore. Must be data manager. |
| include_partition | bool | | If true, include info on the partition. Must be data manager.\ |
| include_coverage | bool | | Deprecated. Use coverage instead. |
| coverage | CoverageSpec | | If specified, requests coverage as well. |
| Field | Type | Label | Description |
|---|
| surveys | SearchSpec | repeated | Optional identifier of the survey. If empty, retrieve all accessible surveys |
| list_seismic_ids | bool | | set to true to list the survey's seismics in the response (default: false) |
| list_seismic_store_ids | bool | | Set to true to list the survey's seismic stores in the response. Only tenant users can see this. |
| include_metadata | bool | | set to true to include survey metadata in the response (default: false) |
| include_coverage | com.cognite.seismic.CoverageParameters | | set this field to include coverage in the response (default: false) |
| include_grid_transformation | bool | | set this field to include the manually specified grid transformation in the response (default: false) |
| include_custom_coverage | bool | | set this field to include the customer-provided survey coverage in the response |
| coverage_source | SurveyCoverageSource | | Requests that a coverage geometry from a particular source is returned in the SearchSurveysResponse. If this field is specified, the coverage parameters in the include_coverage field must also be set. Note that this is independent from the custom coverage returned as part of the survey. If no coverage source is provided, but the coverage parameters are provided, the coverage geometry will be fetched from the custom coverage if one has been provided, and the calculated coverage in other cases. |
| Field | Type | Label | Description |
|---|
| content | bytes | | |
Top
Messages that describe data types used by Seismic Datastore in Cognite Data Fusion
A representation of binary headers used to create or edit existing headers. BinaryHeader FIELDS contains the list of valid fields. to set after the object is constructed.
| Field | Type | Label | Description |
|---|
| x | float | | The x value of the coordinate |
| y | float | | The y value of the coordinate |
| Field | Type | Label | Description |
|---|
| crs | string | | If crs is not specified (aka is blank), uses default crs from file |
| format | CoverageSpec.Format | | |
Specify an individual filter.
Used to identify zero or one objects that may have an external id
Matches when the key AND value are exact matches.
Specifying how to filter metadata. An object will be considered a match if it satisfies ALL filters.
All strings are case sensitive.
| Field | Type | Label | Description |
|---|
| filters | Filter | repeated | |
Used in edit messages to distinguish between an empty map, and a missing map
OptionalMap.DataEntry
Represents partitions, used for granular access control
| Field | Type | Label | Description |
|---|
| id | int64 | | The unique internal id for this partition |
| external_id | string | | The external id of the partition |
| name | string | | The human-friendly name for this partition |
| seismics | Seismic | repeated | DEPRECATED: This field will always be empty. Use seismic search by partition instead. |
| seismic_ids | int64 | repeated | The list of ids of seismics that belong to this partition |
Used to identify any number of objects, intended for any plural Read endpoints. Set endpoints should use Identifier.
Can search by id, name, or prefix.
| Field | Type | Label | Description |
|---|
| id | int64 | | |
| id_string | string | | Surveys and files must have string format ids. Other objects can't use this. |
| external_id | string | | External ids only exist for partitions and seismics. Exact match required |
| external_id_substring | string | | |
| name | string | | Names exist for everything. An exact string match is required |
| name_substring | string | | Searches for names having this substring. |
| metadata | MetadataFilter | | Filters by metadata. Currently only supported by Surveys. |
A cutout of a seismic store
| Field | Type | Label | Description |
|---|
| id | int64 | | The unique internal id of the seismic. It is always present |
| external_id | string | | The external id of the seismic |
| name | string | | A non-unique name for the seismic. It is easily editable and is intended to be used as a human-friendly reference. |
| crs | string | | The Coordinate Reference System of the seismic |
| metadata | Seismic.MetadataEntry | repeated | Any custom-defined metadata |
| text_header | TextHeader | | The text header that corresponds to the seismic |
| binary_header | BinaryHeader | | The binary header that corresponds to the seismic |
| line_range | LineRange | | The minimum and maximum extents of the seismic's grid, described in inlines and crosslines. |
| volume_def | VolumeDef | | The VolumeDef describing the seismic |
| partition_id | int64 | | The id of the partition the seismic belongs to |
| seismicstore_id | int64 | | The id of the seismicstore the seismic is derived from. It is present only if agent has READ access and ALL scope |
| coverage | com.cognite.seismic.Geometry | | The coverage geometry for the seismic. |
| created_empty | bool | | If true, this seismic was created with the 'empty' volume option and thus will have no trace data available |
| trace_count | int64 | | Provides an estimate of the number of traces contained within the seismic. |
Represents a seismic store.
| Field | Type | Label | Description |
|---|
| id | int64 | | The unique internal id of the seismic store |
| name | string | | The unique name of the seismic store. Will become non-unique in the future, and external_id will become the unique identifier. |
| survey_id | string | | The survey this seismic store belongs to. |
| ingestion_source | com.cognite.seismic.IngestionSource | | The source of the seismicstore. It indicates how the file was ingested |
| metadata | SeismicStore.MetadataEntry | repeated | Any custom-defined metadata |
| ingested_file | com.cognite.seismic.File | | If present, the file this SeismicStore was ingested from |
| inline_volume_def | VolumeDef | | Volume definition for the store, indexed on inlines. Maps from an inline to all of its valid crosslines. |
| crossline_volume_def | VolumeDef | | Volume definition for the store, indexed on crosslines. Maps from a crossline to all of its valid inlines |
| text_header | TextHeader | | If present, the text header for this seismic store |
| binary_header | BinaryHeader | | If present, the binary header for this seismic store |
| storage_tier_name | string | repeated | Tenant specific name for the storage facility the trace data are stored in. If empty, it is stored in an unspecified trace store. While support for multiple storage backends per store is planned, this is not currently offered. |
| coverage | com.cognite.seismic.Geometry | | If present, the coverage geometry for this seismic store |
Representation of the data for a survey
| Field | Type | Label | Description |
|---|
| id | string | | Unique identifier for the survey in CDF. The identifier is generated by CDF on creation and not editable. |
| name | string | | Survey name: Should be a short but recognizable name for the survey. Must be unique within a single CDF tenant, and may be used to refer to the survey in API calls. Survey name |
| metadata | Survey.MetadataEntry | repeated | Metadata describing the survey with named fields and values. |
| external_id | com.cognite.seismic.ExternalId | | External identifier of the survey. The value of this field must be unique among all the surveys in the CDF tenant. It may be used for correlating with systems outside CDF, and for search and retrieval operations later. |
| crs | string | | Coordinate reference system to be used by all members of this survey |
| grid_transformation | com.cognite.seismic.SurveyGridTransformation | | Manually specify an affine transformation between bin grid coordinates and projected crs coordinates, either using an origin point and the azimuth of the xline axis (P6Transformation) or by specifying three or more corners of the grid as a list of DoubleTraceCoordinates. This transformation must be valid for all members of this survey. |
| custom_coverage | com.cognite.seismic.CustomSurveyCoverage | | User-provided coverage override |
A representation of text headers used to create or edit existing headers.
| Field | Type | Label | Description |
|---|
| file_id | string | | |
| header | string | | The text content of the header |
| raw_header | string | | The raw bytes of a header as a string |
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.
For more information refer to <a href="https://cognite-seismic-sdk.readthedocs-hosted.com/en/latest/volumedef.html#volumedef-overview">the SDK docs</a>.
| Field | Type | Label | Description |
|---|
| json | string | | Uses the Volume Definition schema |
| Name | Number | Description |
|---|
| WKT | 0 | |
| GEOJSON | 1 | |
| Name | Number | Description |
|---|
| UNSPECIFIED | 0 | Used as the default when a specific source isn't requested by the user. |
| CUSTOM | 1 | Requesting or returning custom coverage |
| CALCULATED | 2 | Requesting or returning calculated coverage |
Top
Messages for types used in ingestion and query services in Seismic Datastore in Cognite Data Fusion
| Field | Type | Label | Description |
|---|
| crs | string | | |
Basic type representing (x,y) coordinate in the given CRS
| Field | Type | Label | Description |
|---|
| crs | string | | The Coordinate Reference System of the coordinate. Generally should be an EPSG code including the EPSG: prefix, for example EPSG:23031 |
| x | float | | The x value of the coordinate |
| y | float | | The y value of the coordinate |
Parameters for requesting coverage of survey
| Field | Type | Label | Description |
|---|
| crs | CRS | | [optional] If CRS provided converts coverage to given CRS. Otherwise, will return in the survey's original CRS |
| in_wkt | bool | | set this to true to return in WKT format. Otherwise, response will be in geojson format by default |
Customer-provided custom coverage for surveys
| Field | Type | Label | Description |
|---|
| custom_coverage | Geometry | | Overrides survey coverage with the provided custom coverage geometry |
| no_custom_coverage | CustomSurveyCoverage.NoCustomCoverage | | Specifies that no custom coverage is provided, so survey coverage is computed from the seismicstores in the survey |
Have the seismic service try to deduce the affine transformation for each file by
reading trace coordinates
Correlated grid indices and coordinates
| Field | Type | Label | Description |
|---|
| iline | int32 | | The inline number. Within a 3D survey, a inline represents a seismic line parallel to the direction in which the data was adquired. |
| xline | int32 | | The xline number. Within a 3D survey, a xline represents a seismic line perpendicular to the direction in which the data was adquired. |
| x | float | | The x value of the coordinate |
| y | float | | The y value of the coordinate |
| Field | Type | Label | Description |
|---|
| external_id | string | | |
File or dataset or cube derived from a single SEG-Y file
The GeoJSON format (<a href="https://tools.ietf.org/html/rfc7946">RFC 7946</a>)
Supported geometry: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, and GeometryCollection.
Example:
<pre>{
"type": "Point",
"coordinates": [100.0, 0.0]
}</pre>
Geometry can be specified using either wkt or geoJSON. CRS is always required.
Specify either id or name to find a file or survey.
Range of inline and crossline indices defining a 2D region
Object to store the line range. From and to are optional
Specify either inline OR crossline
| Field | Type | Label | Description |
|---|
| iline | int32 | | The inline number. Within a 3D survey, a inline represents a seismic line parallel to the direction in which the data was adquired. |
| xline | int32 | | The xline number. Within a 3D survey, a xline represents a seismic line perpendicular to the direction in which the data was adquired. |
Specify the transformation by an origin point and the crossline azimuth
Format inspired by IOGP guidance note 373-7-2 section 2.3.2.4.
https://ge0mlib.com/papers/Guide/IOGP/373-07-2-1_2017.pdf
| Field | Type | Label | Description |
|---|
| handedness | Handedness | | |
| origin | DoubleTraceCoordinates | | A point in the grid |
| iline_bin_width | float | | The bin width along the inline axis |
| xline_bin_width | float | | The bin width along the crossline axis |
| xline_azimuth | float | | Map bearing of the crossline axis in clockwise degrees from north |
| iline_bin_inc | int32 | | Inline increment corresponding to a bin |
| xline_bin_inc | int32 | | Crossline increment corresponding to a bin |
Point defined by its inline and crossline indices
| Field | Type | Label | Description |
|---|
| iline | int32 | | The inline number. Within a 3D survey, a inline represents a seismic line parallel to the direction in which the data was adquired. |
| xline | int32 | | The xline number. Within a 3D survey, a xline represents a seismic line perpendicular to the direction in which the data was adquired. |
Wrapper over Trace type that additionally provide information about the range of z values
included in the trace.
Basic type to represent a point in a surface defined by a horizontal grid
Used in horizontal slice queries
| Field | Type | Label | Description |
|---|
| iline | int32 | | The inline number. Within a 3D survey, a inline represents a seismic line parallel to the direction in which the data was adquired. |
| xline | int32 | | The xline number. Within a 3D survey, a xline represents a seismic line perpendicular to the direction in which the data was adquired. |
| value | float | | |
A survey represents a collection of files in the same area
Specify the affine transformation between line indices and coordinates
Basic type to represent a seismic trace
Used in trace, vertical slices and volume queries
Contains the samples and information on positioning
If a trace is an original trace in the file, it can optionally contain the trace header.
This is not valid for traces that are synthetically generated from interpolation.
| Field | Type | Label | Description |
|---|
| trace_header | bytes | | |
| iline | google.protobuf.Int32Value | | The inline number. Within a 3D survey, a inline represents a seismic line parallel to the direction in which the data was adquired. |
| xline | google.protobuf.Int32Value | | The xline number. Within a 3D survey, a xline represents a seismic line perpendicular to the direction in which the data was adquired. |
| trace | float | repeated | The underlying array of floats representing samples |
| coordinate | Coordinate | | |
Specify the transformation by giving the coordinates of three or more corners
Well-known text representation of geometry (<a href="http://www.opengeospatial.org/standards/sfa">WKT</a>)
| Field | Type | Label | Description |
|---|
| geometry | string | | |
| Name | Number | Description |
|---|
| REGISTER | 0 | |
| INSERT_FILE_HEADERS | 1 | |
| INSERT_TRACE_HEADERS | 2 | |
| INSERT_DATA | 3 | |
| COMPUTE_COVERAGE | 4 | |
| COMPUTE_GRID | 5 | |
| COMPUTE_TRACE_INDICES | 6 | |
| DELETING | 254 | |
| DELETE | 255 | |
| Name | Number | Description |
|---|
| RIGHTHANDED | 0 | inline axis is 90 deg clockwise from crossline AKA EPSG code 9666 |
| LEFTHANDED | 1 | inline axis is 90 deg counterclockwise from crossline AKA EPSG code 1049 |
| Name | Number | Description |
|---|
| INVALID_SOURCE | 0 | |
| FILE_SOURCE | 1 | |
| TRACE_WRITER | 2 | TraceWriter |
| Name | Number | Description |
|---|
| NEAREST_TRACE | 0 | |
| INVERSE_DISTANCE_WEIGHTING | 1 | |
| Name | Number | Description |
|---|
| NONE | 0 | |
| QUEUED | 1 | |
| IN_PROGRESS | 2 | |
| SUCCESS | 3 | |
| FAILED | 4 | |
| TIMEOUT | 5 | |
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
|---|
| double | | double | double | float | float64 | double | float | Float |
| float | | float | float | float | float32 | float | float | Float |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |