Quickstart¶

Client setup and authentication¶

All data in CDF are stored in a CDF tenant, identified by a project name. To specify the project or tenant to work on, set the COGNITE_PROJECT environment variable or use the project keyword argument to the CogniteSeismicClient constructor.

The preferred way to authenticate against the Cognite API is by setting the COGNITE_API_KEY environment variable. All examples in this documentation require that the variable has been set.

$ export COGNITE_PROJECT = example-project
$ export COGNITE_API_KEY = <your-api-key>

You can also pass your API key directly to the CogniteClient.

>>> from cognite.seismic import CogniteSeismicClient
>>> client = CogniteSeismicClient(project = "example-project", api_key="<your-api-key>")

Key concepts¶

The basic flow of ingesting and querying data into the cognite seismic service is the following:

The data manager ingests data into the service in the following typical series of steps:

Create a Survey object to group source files together
Register a SourceSegyFile against the survey
Ask the ingestion worker to ingest the file
Verify that ingestion succeeded
Find the SeismicStore object containing the trace data from the source file, and verify the containing data
Create a Partition object for managing granular user access to the data
Create a Seismic object from a contained in the partition, with a SeismicCutout object describing which parts of the corresponding SeismicStore to include.

A user with scoped access to the given partition can then fetch data from the Seismic object, or download it as a Seg-Y file.

See the example notebook for a more detailed worked example.

API¶

These APIs are stabilized as of the 0.3 release. They support both 2D and 3D seismic data, granular access control using cutouts and partitions, as well as tiered storage. Compared to 0.1 and 0.2 APIs, the number of different functions have been streamlined into a smaller number of more flexible functions.

Client¶

Creating a client¶

class cognite.seismic._api_client.CogniteSeismicClient(api_key=None, base_url=None, custom_root_cert=None, *, project=None, no_retries=False, max_message_size_MB=10, oidc_token=None)¶

Main class for the seismic client.

Parameters:

api_key (str, optional) – An API key. Equivalent to setting the COGNITE_API_KEY environment variable.
base_url (str, optional) – The url to connect to. Defaults to api.cognitedata.com.
port (int, optional) – The port to connect to. Defaults to 443.
custom_root_cert (str, optional) – A custom root certificate for SSL connections. Should not need to be used by general users.
project (str) – The name of the project to call API endpoints against.
no_retries (bool) – If true, will not automatically retry failed requests.
max_message_size_MB (int) – The max message size of gRPC replies. Defaults to 10.
oidc_token (str | function() -> str, optional) – If specified, will attempt to connect to the seismic service using an OIDC token. This should be either a string or a callable resolving to a string.

The API calls are grouped into sub-APIs for dealing with the different resource types:

Client object members¶
client.job	Ingestion job status
client.survey	Seismic Surveys
client.seismic	Seismic Query Objects
client.traces	Seismic trace data access
client.seismicstore	Seismic Store Objects
client.partition	Data Partitions
client.file	File management

Generating OIDC tokens¶

The oidc_token argument takes either a string (representing an OIDC token) or a callable that is expected to return an OIDC token when invoked. The method cognite.seismic.generate_oidc_token can be used to generate such a callable from token credentials.

seismic.generate_oidc_token(*, token_client_id: Optional[str] = None, token_client_secret: Optional[str] = None, token_scopes: Optional[str] = None, token_custom_args: Optional[Dict[str, str]] = None) → Callable[[], str]¶

Returns a callable that can be invoked to generate an OIDC token from info provided.

Parameters:

token_url (str, optional) – If none, will attempt to use the environmental variable COGNITE_TOKEN_URL.
token_client_id (str, optional) – The id for the token. If none, will attempt to use the environmental variable COGNITE_CLIENT_ID.
token_client_secret (str, optional) – The secret for the token. If none, will attempt to use the environmental variable COGNITE_CLIENT_SECRET.
token_scopes (str, optional) – A comma-separated list of token scopes. If none, will attempt to use the environmental variable COGNITE_TOKEN_SCOPES
token_custom_args (Optional[Dict[str, str]]) – Custom args for tokens.

Seismic Surveys¶

Surveys are groupings of seismic data sets, usually for a single area. The first step to ingesting seismic data into the CDF seismic service is to register the survey that the given files should be registered against.

Create a new survey¶

SurveyAPI.create(name: str, external_id: str, crs: str, metadata: Dict[str, str] = {}, grid_transformation: Optional[cognite.seismic.data_classes.api_types.SurveyGridTransformation] = None, custom_coverage_wkt: Optional[str] = None, custom_coverage_geojson: Optional[dict] = None) → cognite.seismic.data_classes.api_types.Survey¶

Creates a survey with the provided characteristics.

Parameters:

name (str) – survey name.
metadata (Dict[str, str], optional) – metadata of the survey.
external_id (str) – external id of the survey.
crs (str) – Coordinate reference system to be used by all members of this survey. Specified as an EPSG reference code in the format “EPSG:####”.
grid_transformation (SurveyGridTransformation, optional) –
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); by specifying three or more corners of the grid (CoordList); or by asking the seismic service to deduce the transformation from the traces in each file (DeduceFromTraces).

This transformation must be valid for all the files in this survey.
custom_coverage_wkt (str, optional) – Specify a custom coverage polygon for this survey in the wkt format
custom_coverage_geojson (dict, optional) – Specify a custom coverage polygon for this survey in the geojson format

Returns:

Survey

List all surveys¶

SurveyAPI.list(list_seismics: bool = False, list_seismic_stores: bool = False, include_metadata: bool = False, coverage_crs: Optional[str] = None, coverage_format: Optional[str] = None, include_grid_transformation: Optional[bool] = False, include_custom_coverage: Optional[bool] = False, coverage_source: cognite.seismic.data_classes.api_types.SurveyCoverageSource = SurveyCoverageSource.UNSPECIFIED) → Iterator[cognite.seismic.data_classes.api_types.Survey]¶

List all the surveys. Provide either crs or coverage_format to get surveys’ coverage.

Parameters:	list_seismics (bool, optional) – If true, list the seismics ids from each survey. list_seismic_stores (bool, optional) – If true, list the seismic store ids from each surveys. Only permitted if the user is a data manager (write access to all partitions). include_metadata (bool, optional) – true if metadata should be included in the response. coverage_crs (str, optional) – The crs in which the surveys’ coverage is returned, default is original survey crs coverage_format (str, optional) – One of “wkt”, “geojson”. If specified, includes the coverage as the given format. Defaults to geojson. include_grid_transformation (bool, optional) – If true, return the user-specified transformation between bin grid and projected coordinates include_custom_coverage (bool, optional) – If true, return the customer-specified survey coverage
Returns:	the requested surveys and their files (if requested).
Return type:	Iterator[`Survey`]

Search for surveys¶

SurveyAPI.search(id: Optional[int] = None, uuid: Optional[str] = None, name: Optional[str] = None, name_substring: Optional[str] = None, external_id: Optional[str] = None, external_id_substring: Optional[str] = None, geometry: Optional[cognite.seismic.data_classes.geometry.Geometry] = None, survey_contains_exact_metadata: Optional[Mapping[str, str]] = None, last_modified: Optional[cognite.seismic.data_classes.searchspec.SearchSpecLastModified] = None, list_seismics: bool = False, list_seismic_stores: bool = False, include_metadata: bool = False, coverage_crs: Optional[str] = None, coverage_format: Optional[str] = None, include_grid_transformation: Optional[bool] = False, include_custom_coverage: Optional[bool] = False, coverage_source: cognite.seismic.data_classes.api_types.SurveyCoverageSource = SurveyCoverageSource.UNSPECIFIED) → Iterator[cognite.seismic.data_classes.api_types.Survey]¶

Search for subset of surveys. Provide either crs or coverage_format to get surveys’ coverage.

Parameters:	id (int, optional) – Find surveys with this id uuid (str, optional) – Find surveys with this id in the old uuid format name (str, optional) – Find surveys with this name name_substring (str) – Find surveys whose name contains this substring external_id (str, optional) – Find surveys with this external id external_id_substring (str, optional) – Find surveys whose external id contains this substring geometry (`Geometry`, optional) – Find surveys whose coverage overlaps the given geometry survey_contains_exact_metadata (Mapping[str, str], optional) – Find surveys whose metadata contains an exact match of the keys and values of the provided metadata. It is also case-sensitive. last_modified (`SearchSpecLastModified`, optional) – If specified, further filters the returned surveys by their last modified date. list_seismics (bool, optional) – If true, list the seismics ids from each survey. list_seismic_stores (bool, optional) – If true, list the seismic store ids from each survey. Only permitted if the user is a data manager (write access to all partitions). include_metadata (bool, optional) – If true, include metadata in the response. coverage_crs (str, optional) – The crs in which the surveys’ coverage is returned, default is original survey crs coverage_format (str, optional) – One of “wkt”, “geojson”. If specified, includes the coverage as the given format. Defaults to wkt. include_grid_transformation (bool, optional) – If True, return the user-specified transformation between bin grid and projected coordinates include_custom_coverage (bool, optional) – If True, return the customer-specified survey coverage coverage_source (SurveyCoverageSource, optional) – If specified, attempts to return the survey coverage from the given source. Defaults to unspecified, where the custom coverage will be prioritized.
Returns:	The requested surveys and their files (if requested).
Return type:	Iterator[`Survey`]

Get one survey¶

SurveyAPI.get(id: Optional[int] = None, external_id: Optional[str] = None, uuid: Optional[str] = None, name: Optional[str] = None, list_seismics: bool = False, list_seismic_stores: bool = False, include_metadata: bool = False, coverage_crs: Optional[str] = None, coverage_format: Optional[str] = None, include_grid_transformation: Optional[bool] = False, include_custom_coverage: Optional[bool] = False, coverage_source: cognite.seismic.data_classes.api_types.SurveyCoverageSource = SurveyCoverageSource.UNSPECIFIED) → cognite.seismic.data_classes.api_types.Survey¶

Get a survey by either id, external_id, name, or the old uuid identifier. Provide either coverage_crs or coverage_format to get survey coverage.

Parameters:	id (int, optional) – survey id. external_id (str, optional) – survey external id. uuid (str, optional) – survey id in the old uuid format. name (str, optional) – survey name. list_seismics (bool, optional) – If true, list the seismic ids in the survey. list_seismic_stores (bool, optional) – If true, list the seismic store ids in the survey. Only permitted if the user is a data manager (write access to all partitions). include_metadata (bool, optional) – If true, include the metadata in the response. coverage_crs (str, optional) – The crs in which the survey coverage is returned, default is original survey crs coverage_format (str, optional) – One of “wkt”, “geojson”. If specified, includes the coverage as the given format. Defaults to wkt. include_grid_transformation (bool, optional) – If true, return the user-specified transformation between bin grid and projected coordinates include_custom_coverage (bool, optional) – If true, return the customer-specified survey coverage coverage_source (SurveyCoverageSource, optional) – if specified, attempts to return the survey coverage from the given source. Defaults to unspecified, where the custom coverage will be prioritized.
Returns:	The requested survey, its seismics, seismic stores and metadata (if requested).
Return type:	`Survey`

Edit a survey¶

SurveyAPI.edit(id: Optional[int] = None, external_id: Optional[str] = None, metadata: Dict[str, str] = {}, new_external_id: Optional[str] = None, crs: Optional[str] = None, grid_transformation: Optional[cognite.seismic.data_classes.api_types.SurveyGridTransformation] = None, custom_coverage_wkt: Optional[str] = None, custom_coverage_geojson: Optional[dict] = None, clear_custom_coverage: Optional[bool] = False, name: Optional[str] = None)¶

Edit a survey This method replaces fields in an existing survey identified by either its id or external_id. Method parameters that are non-null will be used to replace the corresponding field in the survey object. Null (unspecified) method parameters will not affect a change to the survey object.

Parameters:	id (int, optional) – integer id of the survey to edit. external_id (str, optional) – external id of the survey to edit. Either id or external_id must be specified. metadata (dict) – metadata to be used by the survey. new_external_id (str, optional) – External id to be used by the survey. crs (str, optional) – Coordinate reference system to be used by all members of this survey grid_transformation (`SurveyGridTransformation`, optional) – 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`); by specifying three or more corners of the grid (`CoordList`); or by asking the seismic service to deduce the transformation from the traces in each file (`DeduceFromTraces`). This transformation must be valid for all members of this survey. custom_coverage_wkt (str, optional) – Specify a custom coverage polygon for this survey in the wkt format custom_coverage_geojson (dict, optional) – Specify a custom coverage polygon for this survey in the geojson format clear_custom_coverage (bool, optional) – Set this to True to clear the custom coverage from this survey, so that coverage is computed as a union of the coverage of the data sets included in the survey. name (str, optional) – new name for the survey.
Returns:	id, name and metadata of the survey.
Return type:	`Survey`

Delete a survey¶

SurveyAPI.delete(id: Optional[int] = None, external_id: Optional[str] = None)¶

Delete a survey

Parameters:	id (int, optional) – Integer id of the survey to delete external_id (str, optional) – External id of the survey to delete

File management¶

CDF seismic works with SEG-Y files stored in cloud storage buckets. To work with data stored in these SEG-Y files the file must be registered with the seismic service. This registration must include the location of the file, any metadata you want associated with the file to enable its discovery and use, and the information needed to interpret the SEG-Y file, such as the coordinate reference system used for spatial locations in the file, the byte locations of trace header fields (if non-standard) and scalars to be applied to location fields.

Register file¶

FileAPI.register(*, survey_id: Optional[int] = None, survey_external_id: Optional[str] = None, path: str, external_id: str, metadata: Dict[str, str] = {}, crs: Optional[str] = None, energy_source_point_offset: Optional[int] = None, cdp_number_offset: Optional[int] = None, inline_offset: Optional[int] = None, crossline_offset: Optional[int] = None, cdp_x_offset: Optional[int] = None, cdp_y_offset: Optional[int] = None, shotpoint_offset: Optional[int] = None, cdp_trace_offset: Optional[int] = None, offset_header_offset: Optional[int] = None, source_group_scalar_override: Optional[float] = None, dimensions: int = 3, seismic_data_type: cognite.seismic.data_classes.api_types.SeismicDataType = SeismicDataType.POSTSTACK, key_fields: List[cognite.seismic.data_classes.extents.TraceHeaderField] = []) → cognite.seismic.data_classes.api_types.SourceSegyFile¶

Register a source SEG-Y file for ingestion.

Parameters:	survey_id (int, optional) – The id of the survey this source file belongs to. The survey is identified by either the id or the external id. If both are provided, the id is used. survey_external_id (str, optional) – The external id of the survey this source file belongs to. The survey is identified by either the id or the external id. If both are provided, the id is used. path (str) – Cloud storage path including protocol, bucket, directory structure, and file name. Example: “gs://cognite-seismic-eu/samples/SOME_FILE.sgy”. external_id (str) – External id to assign to the file metadata (dict, optional) – A string -> string dictionary with any metadata to add about the file crs (str, optional) – The CRS of the file as an EPSG code (e.g. “EPSG:4326”). If not given, the CRS will be taken from the survey. energy_source_point_offset (int, optional) – Position of the energy source point in trace headers. Defaults to 17 as per the SEG-Y rev1 specification. cdp_number_offset (int, optional) – Position of the ensemble (CDP) number in trace headers. Defaults to 21 as per the SEG-Y rev1 specification. inline_offset (int, optional) – Position of the inline number field in the trace headers. Defaults to 189 as per the SEG-Y rev1 specification. crossline_offset (int, optional) – Position of the crossline number field in the trace headers. Defaults to 193 as per the SEG-Y rev1 specification. cdp_x_offset (int, optional) – Position of the X coordinate of ensemble (CDP) in trace headers. Defaults to 181 as per the SEG-Y rev1 specification. cdp_y_offset (int, optional) – Position of the Y coordinate of ensemble (CDP) in trace headers. Defaults to 185 as per the SEG-Y rev1 specification. shotpoint_offset (int, optional) – Position of the shotpoint field in trace headers. Defaults to 197 as per the SEG-Y rev1 specification. cdp_trace_offset (int, optional) – Position of the cdp_trace field in trace headers. Defaults to 25 as per the SEG-Y rev1 specification. offset_header_offset (int, optional) – Position of the offset field in trace headers. Defaults to 37 as per the SEG-Y rev1 specification. source_group_scalar_override – Multiplier for CDP-X and CDP-Y values, overrides scalar factor obtained from trace header. Note that this is a straight multiplier to be applied, not a value to be interpreted like the SEG-Y trace header field. Valid values for this parameter are in the range 0.0 < n <= 1.0 dimensions (int, optional) – File data dimensionality, either 2 or 3. Defaults to 3. seismic_data_type (`SeismicDataType`, optional) – File data type, either poststack, or prestack migrated. key_fields (List[`TraceHeaderField`], optional) – The trace header fields that will be used as keys for indexing. Defaults to [INLINE, CROSSLINE] for 3D files, and [CDP] for 2D.
Returns:	The registered source file
Return type:	`SourceSegyFile`

Ingest file¶

FileAPI.ingest(*, file_id: Optional[int] = None, file_external_id: Optional[str] = None, storage_tier: Optional[str] = None) → cognite.seismic.data_classes.api_types.IngestionJob¶

Ingest a registered file.

Parameters:	file_id (int, optional) – File id of the registered source file to ingest. file_external_id (str, optional) – External id of the registered source file to ingest. storage_tier (str, optional) – Target storage tier. A storage tier is a defined facility for storing the trace data associated with a seismic volume.
Returns:	A job id that can be used to query for status of the ingestion job.
Return type:	`IngestionJob`

Get file¶

FileAPI.get(*, id: Optional[int] = None, uuid: Optional[str] = None, external_id: Optional[str] = None) → cognite.seismic.data_classes.api_types.SourceSegyFile¶

Fetch a file by id.

Parameters:	id (int, optional) – The id of the file to fetch uuid (str, optional) – The id of the file to fetch in the old uuid format external_id (str, optional) – The external id of the file to fetch
Returns:	The retrieved file
Return type:	`SourceSegyFile`

List all files¶

FileAPI.list() → Iterator[cognite.seismic.data_classes.api_types.SourceSegyFile]¶

List all files.

Returns:	A stream of Files.
Return type:	Iterator[`SourceSegyFile`]

Search for files¶

FileAPI.search(*, search_spec: cognite.seismic.data_classes.searchspec.SearchSpecBase) → Iterator[cognite.seismic.data_classes.api_types.SourceSegyFile]¶

Search for files.

Parameters:	search_spec – One of `SearchSpecSurvey`, `SearchSpecFile`, `SearchSpecSeismicStore`, or `SearchSpecGetAll`. Specifies the search parameters.
Returns:	A stream of found Files.
Return type:	Iterator[`SourceSegyFile`]

Edit file¶

FileAPI.edit(*, id: Optional[int] = None, external_id: Optional[str] = None, path: Optional[str] = None, new_external_id: Optional[str] = None, metadata: Dict[str, str] = {}, crs: Optional[str] = None, energy_source_point_offset: Optional[int] = None, cdp_number_offset: Optional[int] = None, inline_offset: Optional[int] = None, crossline_offset: Optional[int] = None, cdp_x_offset: Optional[int] = None, cdp_y_offset: Optional[int] = None, shotpoint_offset: Optional[int] = None, cdp_trace_offset: Optional[int] = None, offset_header_offset: Optional[int] = None, source_group_scalar_override: Optional[float] = None, dimensions: Optional[int] = None, seismic_data_type: Optional[cognite.seismic.data_classes.api_types.SeismicDataType] = None, key_fields: List[cognite.seismic.data_classes.extents.TraceHeaderField] = []) → cognite.seismic.data_classes.api_types.SourceSegyFile¶

Edit a previously registered source SEG-Y file.

Pass a value of 0 to any override argument to remove that override.

Parameters:	id (int, optional) – The id of the source file to edit. external_id (str, optional) – The external id of the source file to edit. path (str, optional) – Cloud storage path including protocol, bucket, directory structure, and file name. Example: “gs://cognite-seismic-eu/samples/SOME_FILE.sgy”. new_external_id (str, optional) – An external identifier - matches service contract field. metadata (Dict[str, str], optional) – Any custom-defined metadata. crs (str, optional) – Official name of the CRS used. Example: “EPSG:23031”. energy_source_point_offset (int, optional) – Position of the energy source point in trace headers. cdp_number_offset (int, optional) – Position of the ensemble (CDP) number in trace headers. inline_offset (int, optional) – Position of the inline number field in the trace headers. crossline_offset (int, optional) – Position of the crossline number field in the trace headers. cdp_x_offset (int, optional) – Position of the X coordinate of ensemble (CDP) in trace headers. cdp_y_offset (int, optional) – Position of the Y coordinate of ensemble (CDP) in trace headers. shotpoint_offset (int, optional) – Position of the shotpoint field in trace headers. cdp_trace_offset (int, optional) – Position of the cdp_trace field in trace headers. Defaults to 25 as per the SEG-Y rev1 specification. offset_header_offset (int, optional) – Position of the offset field in trace headers. Defaults to 37 as per the SEG-Y rev1 specification. source_group_scalar_override (float, optional) – Position of the energy source point in trace headers. dimensions (int, optional) – File data dimensionality, either 2 or 3. seismic_data_type (`SeismicDataType`, optional) – File data type, either poststack, or prestack migrated. key_fields (List[`TraceHeaderField`], optional) – The trace header fields that will be used as keys for indexing.
Returns:	The registered source file
Return type:	`SourceSegyFile`

Unregister file¶

FileAPI.unregister(*, id: Optional[int] = None, external_id: Optional[str] = None)¶

Unregister a previously registered source SEG-Y file. If the file has been ingested or queued for ingestion, the seismicstore must first be deleted.

Parameters:	id (int, optional) – The id of the source file to unregister. external_id (str, optional) – The external id of the source file to unregister.

Ingestion job status¶

After a file has been registered and an ingestion request has been sent, the status of the ingestion job can be monitored using this API.

Get the status of an ingestion job¶

JobAPI.status(job_id: Optional[str] = None, file_id: Optional[int] = None, file_uuid: Optional[str] = None, status: cognite.seismic.data_classes.api_types.StatusCode = <StatusCode.NONE: 0>, target_storage_tier_name: Optional[str] = None, started_before: Optional[datetime.datetime] = None, started_after: Optional[datetime.datetime] = None, updated_before: Optional[datetime.datetime] = None, updated_after: Optional[datetime.datetime] = None) → Iterator[cognite.seismic.data_classes.api_types.JobStatus]¶

Retrieve all job statuses that are within the specified criteria. One of each criteria can be specified. No specified criteria will list all jobs.

Parameters:

job_id (str, optional) – The id of the job
file_id (int, optional) – The id of the file being ingested
file_uuid (str, optional) – The uuid of the file being ingested
status (int, optional) – The status code of the jobs returned
target_storage_tier_name (str, optional) – The target storage tier of the jobs returned
started_before (datetime, optional) – The date jobs returned were started before
started_after (datetime, optional) – The date jobs returned were started after
updated_before (datetime, optional) – The date jobs returned were updated before
updated_after (datetime, optional) – The date jobs returned were updated after

Returns:

A stream of job statuses in order of most recently updated

Seismic Store Objects¶

Once an ingestion job is complete, the file will be visible as a Seismic Store object. Seismic store objects represent a 2D or 3D post-stack dataset from the point of view of a data manager, and are only accessible for the default data partition.

A seismic store object represents the actual storage facility for trace data, and can be exposed for data consumer use through seismic query objects.

List all seismic stores¶

SeismicStoreAPI.list(*, include_file_info: bool = False, include_extent: bool = False, extent_key: Optional[cognite.seismic.data_classes.extents.TraceHeaderField] = None) → Iterator[cognite.seismic.data_classes.api_types.SeismicStore]¶

List all visible seismic stores.

This is equivalent to calling search() with search_spec=SearchSpecGetAll().

Parameters:	include_file_info (bool, optional) – If true, the response will include information on the source file. include_extent (bool, optional) – If true, the response will include a description of the traces contained in the seismic store. extent_key (`TraceHeaderField`, optional) – Choose which trace header field to describe the traces by (in 2D), or which to use as the major direction (in 3D). Implies include_extent.
Returns:	A Stream of visible seismic stores
Return type:	Iterator[`SeismicStore`]

Search for seismic stores¶

SeismicStoreAPI.search(*, search_spec: cognite.seismic.data_classes.searchspec.SearchSpecBase, include_file_info: bool = False, include_headers: bool = False, include_extent: bool = False, extent_key: Optional[cognite.seismic.data_classes.extents.TraceHeaderField] = None, coverage_crs: Optional[str] = None, coverage_format: Optional[str] = None) → Iterator[cognite.seismic.data_classes.api_types.SeismicStore]¶

Search for seismic stores.

Can search all seismic stores included in surveys or directly search seismic stores, specified by id, external_id, name, or substrings of external_id or name.

For example, to find the seismic store corresponding to a recently ingested file with id file_id, run:

client.seismicstore.search(search_spec=SearchSpecFile(id=file_id))

Parameters:	search_spec – One of `SearchSpecSurvey`, `SearchSpecFile`, `SearchSpecSeismicStore`, or `SearchSpecGetAll`. Specifies the search parameters. include_file_info (bool) – If true, the response will include information on the source file. include_headers (bool) – If true, the response will include headers. include_extent (bool) – If true, the response will include a description of the traces contained in the seismic store extent_key (`TraceHeaderField`, optional) – Choose which trace header field to describe the traces by (in 2D), or which to use as the major direction (in 3D). Implies include_extent. coverage_crs (str, optional) – If specified, includes the coverage in the given CRS. Either coverage_crs or coverage_format must be specified to retrieve coverage. coverage_format (str, optional) – One of “wkt”, “geojson”. If specified, includes the coverage as the given format.
Returns:	A stream of matching seismic stores
Return type:	Iterator[`SeismicStore`]

Get seismic store¶

SeismicStoreAPI.get(id: int, *, extent_key: Optional[cognite.seismic.data_classes.extents.TraceHeaderField] = None, coverage_crs: Optional[str] = None, coverage_format: Optional[str] = 'wkt') → cognite.seismic.data_classes.api_types.SeismicStore¶

Get a seismic store by its id.

Includes all available info.

Parameters:

id (int) – The seismic store id to find
extent_key (TraceHeaderField, optional) – Choose which trace header field to describe the traces by (in 2D), or which to use as the major direction (in 3D).
coverage_crs (str, optional) – If specified, includes the coverage in the given CRS. Either coverage_crs or coverage_format must be specified to retrieve coverage.
coverage_format (str, optional) – Either “wkt” or “geojson”. The desired file format for the coverage. Defaults to “wkt”.

Returns:

SeismicStore

Edit seismic stores¶

SeismicStoreAPI.edit(*, id: Optional[int] = None, external_id: Optional[str] = None, new_name: Optional[str] = None, metadata: Optional[Dict[str, str]] = None) → cognite.seismic.data_classes.api_types.SeismicStore¶

Edit a seismic store.

Edit a seismic store, providing the seismic store id. The name and the metadata can be edited.

Parameters:	id (int, optional) – The id of the seismic store new_name (str, optional) – If specified, the new name. Provide an empty string to delete the existing name. metadata (Dict[str, str], optional) – If specified, replaces the old metadata with the new one.
Returns:
Return type:	`SeismicStore`

Delete seismic stores¶

SeismicStoreAPI.delete(*, id: Optional[int] = None, external_id: Optional[str] = None)¶

Delete a seismic store.

If any seismics still reference the specified seismic store, the request will fail.

Parameters:	id (int, optional) – The id or the external id of the seismic store to delete external_id (str, optional) – The id or the external id of the seismic store to delete

Data Partitions¶

Data Partitions are containers for seismic objects. The partitions function as a security boundary, and access to a data partition grants access to its contained seismic objects.

List all data partitions¶

PartitionAPI.list() → Iterator[cognite.seismic.data_classes.api_types.Partition]¶

List all partitions.

List all visible partitions. This is equivalent to calling search() with get_all=true.

Returns:	A stream of all visible partitions
Return type:	Iterator[`Partition`]

Search for data partitions¶

PartitionAPI.search(*, id: Optional[int] = None, external_id: Optional[str] = None, external_id_substring: Optional[str] = None, name: Optional[str] = None, name_substring: Optional[str] = None, last_modified: Optional[cognite.seismic.data_classes.searchspec.SearchSpecLastModified] = None, get_all: bool = False) → Iterator[cognite.seismic.data_classes.api_types.Partition]¶

Search for partitions.

Can search by id, external_id, name, or substrings of external_id or name. Only one search method should be specified. The behaviour when multiple are specified is undefined.

Parameters:	id (int, optional) – Partition id external_id (str, optional) – Partition external id external_id_substring (str, optional) – Substring of external id to search by name (str, optional) – Partition name name_substring (str, optional) – Substring of name to search by last_modified (`SearchSpecLastModified`) – Return partitions where the last modified time is within this range get_all (bool) – Whether to instead retrieve all visible partitions. Equivalent to list().
Returns:	A stream of matching partitions
Return type:	Iterator[`Partition`]

Get data partition¶

PartitionAPI.get(id: Optional[int] = None, external_id: Optional[str] = None) → cognite.seismic.data_classes.api_types.Partition¶

Retrieve a single partition by id or external id.

Equivalent to search() using id or external id.

Parameters:	id (int, optional) – Partition id external_id (str, optional) – Partition external id
Returns:	`Partition`

Create a new data partition¶

PartitionAPI.create(*, external_id: str, name: str = '') → cognite.seismic.data_classes.api_types.Partition¶

Create a new partition.

Create a new partition, providing an external id and an optional name.

Parameters:	external_id (str) – The external id of the new partition. Must be unique. name (str) – The name of the new partition. If not specified, will display the external id wherever a name is required.
Returns:	The newly created partition
Return type:	`Partition`

Edit a data partition¶

PartitionAPI.edit(*, new_name: str, id: Optional[int] = None, external_id: Optional[str] = None) → cognite.seismic.data_classes.api_types.Partition¶

Edit an existing partition.

Edit an existing partition by providing either an id or an external id. The only parameter that can be edited is the name.

Parameters:	id (int, optional) – The id of the partition external_id (str, optional) – The external id of the partition new_name (str) – The new name. Set as an empty string to delete the existing name.
Returns:	The edited partition
Return type:	`Partition`

Delete a data partition¶

PartitionAPI.delete(*, id: Optional[int] = None, external_id: Optional[str] = None)¶

Delete a partition.

Delete a partition by providing either an id or an external id.

Parameters:	id (int, optional) – The id of the partition external_id (str, optional) – The external id of the partition

Seismic Query Objects¶

Seismic objects represent a 2D or 3D post-stack dataset from the point of view of a data consumer. It is backed by a seismic store, which is itself not necessarily available to the caller.

Create seismic objects¶

SeismicAPI.create(*, external_id: str, partition_identifier: Union[int, str], seismic_store_id: int, name: Optional[str] = None, cutout: cognite.seismic.data_classes.extents.SeismicCutout, trace_group_cutout: Optional[cognite.seismic.data_classes.extents.SeismicTraceGroupExtent] = None, metadata: Optional[Dict[str, str]] = None, copy_metadata: bool = False, text_header: Optional[cognite.seismic.data_classes.api_types.TextHeader] = None, binary_header: Optional[cognite.seismic.data_classes.api_types.BinaryHeader] = None) → cognite.seismic.data_classes.api_types.Seismic¶

Create a new Seismic.

Parameters:	external_id (str) – The external id of the new Seismic name (str, optional) – If specified, the name of the new Seismic partition_identifier (int \| str) – Either the partition id or external_id that the Seismic is part of seismic_store_id (int) – The seismic store that the new Seismic is derived from cutout (`SeismicCutout`) – Specifies which part of the data is included from the containing seismicstore trace_group_cutout (`SeismicTraceGroupExtent`) – Specifies which traces are included from each prestack migrated bin from the containing seismicstore. Only available for prestack migrated files. metadata (Dict[str, str], optional) – If specified, sets the metadata to the provided value. copy_metadata (bool) – If True, ignores the metadata arg and copies the metadata from the seismic store. text_header (`TextHeader`, optional) – If specified, sets the provided text header on the new seismic binary_header (`BinaryHeader`, optional) – If specified, sets the provided binary header on the new seismic
Returns:	The newly created Seismic with minimal data. Use search() or get() to retrieve all data.
Return type:	`Seismic`

List all seismic objects¶

SeismicAPI.list(*, include_text_header: bool = False, include_binary_header: bool = False, include_extent: bool = False, extent_key: Optional[cognite.seismic.data_classes.extents.TraceHeaderField] = None, include_cutout: bool = False, include_seismic_store: bool = False, include_partition: bool = False, coverage_crs: Optional[str] = None, coverage_format: Optional[str] = None) → Iterator[cognite.seismic.data_classes.api_types.Seismic]¶

List all visible seismics. This is equivalent to calling search() with search_spec=SearchSpecGetAll().

Parameters:	include_text_header (bool) – If true, includes the text header in the responses include_binary_header (bool) – If true, includes the binary header in the responses include_extent (bool) – If true, includes a description of the traces included in the Seismic object include_seismic_store (bool) – If true, include the seismic store info in the responses include_partition (bool) – If true, include the partition info in the responses coverage_crs (str, optional) – If specified, includes the coverage in the given CRS. Either coverage_crs or coverage_format must be specified to retrieve coverage. coverage_format (str, optional) – One of “wkt”, “geojson”. If specified, includes the coverage as the given format.
Returns:	A stream of visible seismic objects.
Return type:	Iterator[`Seismic`]

Search for seismic objects¶

SeismicAPI.search(*, search_spec: cognite.seismic.data_classes.searchspec.SearchSpecBase, include_text_header: bool = False, include_binary_header: bool = False, include_extent: bool = False, extent_key: Optional[cognite.seismic.data_classes.extents.TraceHeaderField] = None, include_cutout: bool = False, include_seismic_store: bool = False, include_partition: bool = False, coverage_crs: Optional[str] = None, coverage_format: Optional[str] = None) → Iterator[cognite.seismic.data_classes.api_types.Seismic]¶

Search for seismics.

Can search all seismics included in surveys, partitions, or directly search for seismic objects, specified by id, external_id, name, or substrings of external_id or name. Only one search method should be specified.

Parameters:	search_spec – One of `SearchSpecSurvey`, `SearchSpecPartition`, `SearchSpecSeismic`, or `SearchSpecGetAll`. include_text_header (bool) – If true, includes the text header in the responses include_binary_header (bool) – If true, includes the binary header in the responses include_extent (bool) – If true, includes a description of the traces included in the Seismic object extent_key (`TraceHeaderField`, optional) – Choose which trace header field to describe the traces by (in 2D), or which to use as the major direction (in 3D). Implies include_extent. include_seismic_store (bool) – If true, include the seismic store info in the responses include_partition (bool) – If true, include the partition info in the responses coverage_crs (str, optional) – If specified, includes the coverage in the given CRS. Either coverage_crs or coverage_format must be specified to retrieve coverage. coverage_format (str, optional) – One of “wkt”, “geojson”. If specified, includes the coverage as the given format.
Returns:	The list of matching Seismics
Return type:	Iterator[`Seismic`]

Get seismic object¶

SeismicAPI.get(*, id: Optional[int] = None, external_id: Optional[str] = None, extent_key: Optional[cognite.seismic.data_classes.extents.TraceHeaderField] = None, coverage_crs: Optional[str] = None, coverage_format: Optional[str] = 'wkt') → cognite.seismic.data_classes.api_types.Seismic¶

Get a seismic by id or external id.

Includes all available info.

Parameters:	id (int, optional) – id of seismic to get external_id (str, optional) – external id of seismic to get extent_key (`TraceHeaderField`, optional) – Choose which trace header field to describe the traces by (in 2D), or which to use as the major direction (in 3D). coverage_crs (str, optional) – The CRS of the received coverage. Defaults to the file’s CRS. coverage_format (str, optional) – Either “wkt” or “geojson”. The desired file format for the coverage. Defaults to “wkt”.
Returns:	The matching seismic
Return type:	`Seismic`

Edit seismic objects¶

SeismicAPI.edit(*, id: Optional[int] = None, external_id: Optional[str] = None, name: Optional[str] = None, metadata: Optional[Dict[str, str]] = None) → cognite.seismic.data_classes.api_types.Seismic¶

Edit an existing seismic.

Either the id or the external_id should be provided in order to identify the seismic. The editable fields are name and metadata. Providing a name or metadata field will replace the existing data with the new data. Providing an empty string as the name will delete the seismic name.

Parameters:	id (int, optional) – The id of the seismic external_id (str, optional) – The external id of the seismic name (str, optional) – The new name of the seismic metadata (Dict[str, str], optional) – The new metadata for the seismic
Returns:	The edited Seismic with minimal data. Use search() to retrieve all data.
Return type:	`Seismic`

Delete seismic objects¶

SeismicAPI.delete(*, id: Optional[int] = None, external_id: Optional[str] = None)¶

Delete a seismic

Either the id or the external id should be provided in order to identify the seismic.

Parameters:	id (int, optional) – The id of the seismic external_id (str, optional) – The external id of the seismic

Seismic trace data access¶

Retrieving trace data from a seismic object may be done with the volume retrieval API.

This API produces a stream of trace data, based on line-based filters (see the Trace Extents documentation), or geometry-based filters.

Stream traces from a seismic object¶

TracesAPI.stream_traces(**kwargs) → Iterator[cognite.seismic.data_classes.trace_data.Trace]¶

Retrieve traces from a seismic or seismic store

Provide one of: the seismic id, the seismic external id, the seismic store id.

Traces can be filtered by a geometry, by line ranges, or by a SeismicExtent object for more advanced line-based filtering. The line ranges are specified as tuples of either (start, end) or (start, end, step). If a filter is not specified, the maximum ranges will be assumed.

Note that while both inline_range and xline_range may be specified at the same time, only one of cdp_range, shotpoint_range or energy_source_point_range may be specified.

Parameters:

seismic_id (int, optional) – The id of the seismic to query
seismic_external_id (str, optional) – The external id of the seismic to query
seismic_store_id (int, optional) – The id of the seismic store to query
extent (SeismicExtent, optional) – A SeismicExtent object indicating which traces to include
trace_group_extent (SeismicTraceGroupExtent, optional) – A SeismicTraceGroupExtent object indicating which sub-traces to include. Only valid for prestack migrated seismic files.
geometry (Geometry, optional) – Return traces inside this geometry (if area-like) or interpolate traces onto a line (if line-like; only valid for 3d objects).
interpolation_method (InterpolationMethod, optional) – Interpolation method to use when interpolating traces. Only valid if geometry is a line-like geometry.
z_range (line range, optional) – The range of depth indices to include. Specified as a tuple of (int, int) or (int, int, int), representing start index, end index, and step size respectively.
include_trace_header (bool, optional) – Whether to include trace header info in the response.

Returns:

Iterator[Trace], the traces for the specified volume

Download seismic objects as a segy file¶

TracesAPI.get_segy(**kwargs) → Iterator[bytes]¶

Retrieve traces in binary format from a seismic or seismic store

Provide one of: the seismic id, the seismic external id, the seismic store id.

The first and second elements in the response stream will always be the text header and binary header of the file.

Traces can be filtered by a geometry, by line ranges, or by a SeismicExtent object for more advanced line-based filtering. The line ranges are specified as tuples of either (start, end) or (start, end, step). If a filter is not specified, the maximum ranges will be assumed.

Note that while both inline_range and xline_range may be specified at the same time, only one of cdp_range, shotpoint_range or energy_source_point_range may be specified.

Parameters:

seismic_id (int, optional) – The id of the seismic to query
seismic_external_id (str, optional) – The external id of the seismic to query
seismic_store_id (int, optional) – The id of the seismic store to query
extent (SeismicExtent, optional) – A SeismicExtent object indicating which traces to include
trace_group_extent (SeismicTraceGroupExtent, optional) – A SeismicTraceGroupExtent object indicating which sub-traces to include. Only valid for prestack migrated seismic files.
geometry (Geometry, optional) – Return traces inside this geometry (if area-like) or interpolate traces onto a line (if line-like; only valid for 3d objects).

Returns:

An Iterator of bytes buffers that, when concatenated, constitute a SEG-Y stream.

Estimate how much data would be downloaded¶

TracesAPI.get_trace_bounds(**kwargs) → cognite.seismic.data_classes.trace_data.TraceBounds¶

Compute the amount of data that will be returned for a given stream_traces request. This may be used to allocate sufficient data in an array, and also describes the range of the key header fields used to identify traces, ie. the range of the inline and xline numbers for 3D data, or the CDP or shotpoint field values for 2D data.

Parameters: See stream_traces()

Returns:	A `TraceBounds` object describing the size and bounds of the returned traces

class cognite.seismic._api.traces.TraceBounds(num_traces: int, sample_count: int, size_kilobytes: int, crs: str, cdp_trace_bounds: Optional[cognite.seismic.data_classes.extents.RangeInclusive], z_range: cognite.seismic.data_classes.extents.RangeInclusive)¶

Information about the traces that would be returned from a corresponding stream_traces() call

num_traces¶

The number of traces that will be streamed

Type:	int

sample_count¶

The number of samples in each trace

Type:	int

size_kilobytes¶

An estimate of the total streaming size in kilobytes (= 1024 bytes)

Type:	int

crs¶

The coordinate reference system the returned trace coordinates will be given in

Type:	str

z_range¶

The range of depth indices that will be returned in each trace

Type:	`RangeInclusive`

cdp_trace_range¶

The range of CDP_TRACE headers that will be returned. Only populated for pre-stack data.

Type:	`RangeInclusive`

If the queried object is a 3D object and was not queried by a line-like geometry, the returned bounds will be TraceBounds3d. If the queried object is 2D, the returned bounds will be TraceBounds2d. These subclasses contain additional information about the trace bounds.

class cognite.seismic._api.traces.TraceBounds3d(num_traces: int, sample_count: int, size_kilobytes: int, crs: str, cdp_trace_bounds: Optional[cognite.seismic.data_classes.extents.RangeInclusive], z_range: cognite.seismic.data_classes.extents.RangeInclusive, inline_bounds: Optional[cognite.seismic.data_classes.extents.RangeInclusive], xline_bounds: Optional[cognite.seismic.data_classes.extents.RangeInclusive])¶

Information about the traces that would be returned from a corresponding stream_traces() call, with 3d-specific information. In addition to the fields in TraceBounds, there are the following fields:

inline_bounds¶

The smallest range including all the returned inline numbers, or None if there are none.

Type:	`RangeInclusive`

xline_bounds¶

The smallest range including all the returned xline numbers, or None if there are none.

Type:	`RangeInclusive`

class cognite.seismic._api.traces.TraceBounds2d(num_traces: int, sample_count: int, size_kilobytes: int, crs: str, cdp_trace_bounds: Optional[cognite.seismic.data_classes.extents.RangeInclusive], z_range: cognite.seismic.data_classes.extents.RangeInclusive, trace_key_header: cognite.seismic.data_classes.extents.TraceHeaderField, trace_key_bounds: Optional[cognite.seismic.data_classes.extents.RangeInclusive])¶

Information about the traces that would be returned from a corresponding stream_traces() call, with 2d-specific information. In addition to the fields in TraceBounds, there are the following fields:

trace_key_header¶

The trace header the array is indexed by

Type:	`TraceHeaderField`

trace_key_bounds¶

The smallest range including all the returned trace key values, or None if there are none.

Type:	`RangeInclusive`

Store traces into a numpy array¶

TracesAPI.get_array(*, progress: Optional[bool] = None, **kwargs) → cognite.seismic.data_classes.trace_data.ArrayData¶

Store traces from a seismic or seismic store into a numpy array

Parameters: See stream_traces().

In addition, there’s an optional boolean argument progress, which turns a progress bar on or off and defaults to True.

Returns:	An `ArrayData` object encapsulating the retrieved array (see below)

class cognite.seismic._api.traces.ArrayData(trace_data: numpy.ma.core.MaskedArray, crs: str, coord_x: numpy.ma.core.MaskedArray, coord_y: numpy.ma.core.MaskedArray, cdp_trace_range: Optional[cognite.seismic.data_classes.extents.RangeInclusive], z_range: cognite.seismic.data_classes.extents.RangeInclusive)¶

Encapsulates the array returned from get_array(), along with metadata about coordinates. Below, the number d refers to the dimensionality of the requested seismic object, and is either 2 or 3. The number p is 1 for pre-stack data and 0 for post-stack data.

trace_data¶

(d+p)-dimensional numpy MaskedArray containing the requested trace data. The first d-1 dimensions are indexed by (inline, crossline) for 3d data, and the 2d header (cdp, shotpoint or energy_source_point) for 2d data. Prestack data will have a dimension following these for the cdp_trace indexing. The last dimension indexes the depth.

Type:	`MaskedArray`

crs¶: The coordinate system used

coord_x¶

(d-1)-dimensional array containing the x coordinate of the corresponding trace in trace_data

Type:	`MaskedArray`

coord_y¶

(d-1)-dimensional array containing the y coordinate of the corresponding trace in trace_data

Type:	`MaskedArray`

z_range¶

The range of depth indices described by the last dimension of trace_data

Type:	`RangeInclusive`

cdp_trace_range¶

The range of CDP_TRACE headers that will be returned. Only populated for pre-stack data.

Type:	`RangeInclusive`

If the queried object is 3D, the returned data will be ArrayData3d. If the queried object is 2d, the returned data will be ArrayData2d. These subclasses contain additional information about the array.

class cognite.seismic._api.traces.ArrayData3d(trace_data: numpy.ma.core.MaskedArray, crs: str, coord_x: numpy.ma.core.MaskedArray, coord_y: numpy.ma.core.MaskedArray, cdp_trace_range: Optional[cognite.seismic.data_classes.extents.RangeInclusive], z_range: cognite.seismic.data_classes.extents.RangeInclusive, inline_range: Optional[cognite.seismic.data_classes.extents.RangeInclusive], xline_range: Optional[cognite.seismic.data_classes.extents.RangeInclusive])¶

Encapsulates the array returned from get_array(), with 3d-specific information. In addition to the fields in ArrayData, there are the fields:

inline_range¶

The range of inline numbers described by the first dimension of the trace_data, or None if the array is empty

Type:	`RangeInclusive`

xline_range¶

The range of xline numbers described by the second dimension of the trace_data, or None if the array is empty

Type:	`RangeInclusive`

class cognite.seismic._api.traces.ArrayData2d(trace_data: numpy.ma.core.MaskedArray, crs: str, coord_x: numpy.ma.core.MaskedArray, coord_y: numpy.ma.core.MaskedArray, cdp_trace_range: Optional[cognite.seismic.data_classes.extents.RangeInclusive], z_range: cognite.seismic.data_classes.extents.RangeInclusive, trace_key_header: cognite.seismic.data_classes.extents.TraceHeaderField, trace_key_values: numpy.ma.core.MaskedArray)¶

Encapsulates the array returned from get_array(), with 2d-specific information. In addition to the fields in ArrayData, there are the fields:

trace_key_header¶

Which trace header the array is indexed by

Type:	`TraceHeaderField`

trace_key_values¶

1-dimensional array containing the values of the given trace key header for each corresponding trace in trace_data

Type:	`MaskedArray`

API Data Types¶

The API data types returned by the API endpoints are documented here.

Coordinate¶

class cognite.seismic.Coordinate(crs: str, x: float, y: float)¶

Represents physical coordinates in a given CRS.

crs¶

The coordinate reference system of the coordinate. Generally should be an EPSG code.

Type:	str

x¶

The x value of the coordinate.

Type:	float

y¶

The y value of the coordinate.

Type:	float

Trace¶

class cognite.seismic.Trace(trace_header: bytes, inline: Optional[int], xline: Optional[int], cdp: Optional[int], shotpoint: Optional[int], energy_source_point: Optional[int], cdp_trace: Optional[int], offset: Optional[int], trace: List[float], coordinate: cognite.seismic.data_classes.trace_data.Coordinate)¶

Represents a seismic trace identified by a single (inline, xline) pair (if the underlying object is 3D) or a single 2D header value (if 2D).

trace_header¶

The raw trace header.

Type:	bytes

inline¶

The inline number, if available

Type:	int

xline¶

The xline number, if available

Type:	int

cdp¶

The cdp number, if available

Type:	int

shotpoint¶

The shotpoint number, if available

Type:	int

energy_source_point¶

The energy source point number, if available

Type:	int

cdp_trace¶

The cdp trace number, if available

Type:	int

offset¶

The offset number, if available

Type:	int

trace¶

The trace values

Type:	List[float]

coordinate¶

The coordinate of the trace

Type:	`Coordinate`

IngestionSource¶

class cognite.seismic.IngestionSource¶

Enum of ingestion sources.

INVALID_SOURCE = 0¶: Indicates that a source was not specified or was invalid.

FILE_SOURCE = 1¶: Indicates ingestion from a file

TRACE_WRITER = 2¶: Indicates creation by trace writer

Seismic data type¶

class cognite.seismic.SeismicDataType¶: Used to describe what data type a file or seismic/store uses.

Trace Extents¶

Seismic extents provide a flexible way to describe exactly which traces to include in a given query, such as trace streaming or seismic cutout specifications. Extent objects are also returned as part of Seismic and SeismicStore objects to describe exactly which traces are contained in the object.

The base class, SeismicExtent, is an abstract base class which can not be instantiated. This reflects the fact that the trace layout depends on whether the underlying object is 2D or 3D.

class cognite.seismic.SeismicExtent¶: Describes a selection of traces in a seismic object. This is an abstract class: Concrete instances will be either Seismic2dExtent or a subclass of Seismic3dExtent

All extents are based on inclusive, stepped ranges of header values. A range can usually be specified as a tuple (start, stop) or (start, stop, step). However, for return types, we provide a custom class RangeInclusive which has more functionality than a simple tuple:

class cognite.seismic.RangeInclusive(start: int, stop: int, step: Optional[int] = None)¶

Represents an inclusive range of inlines/xlines or depth coordinates.

start¶: The first linenumber encompassed by the range

stop¶: The last linenumber encompassed by the range

step¶: The distance between linenumbers

static from_linerange(linerange: Union[Tuple[int, int], Tuple[int, int, int]]) → cognite.seismic.data_classes.extents.RangeInclusive¶: Construct a RangeInclusive from a (start, stop) or (start, stop, step) tuple

index(line: int) → int¶: Compute the index of a given linenumber in this range

to_linerange() → Union[Tuple[int, int], Tuple[int, int, int]]¶: Return a (start, stop) or a (start, stop, step) tuple

to_positive() → cognite.seismic.data_classes.extents.RangeInclusive¶: Return an equivalent RangeInclusive where the step size is always positive

2D extents¶

A 2D extent is a union of stepped ranges of 2D header values, e.g., CDP or Shotpoint numbers. An object of the class describes which header to use for indexing traces, using a custom enumeration:

class cognite.seismic.TraceHeaderField¶

Used to reference a key trace header field.

INLINE = 3¶: Inline number in a 3D grid

CROSSLINE = 4¶: Crossline number in a 3d grid

CDP = 2¶: Common depth point number

ENERGY_SOURCE_POINT = 1¶: Energy source point number. Usually means the same as shotpoint, but has a different standard location according to the SEGY spec.

SHOTPOINT = 5¶: Shotpoint number. Usually means the same as energy source point, but has a different standard location according to the SEGY spec.

CDP_TRACE = 6¶: Trace number within ensemble. Used by prestack migrated files.

OFFSET = 7¶: Distance from center of source point to the center of the receiver group. Used by prestack migrated files.

With the index header selected, it remains to specify a list of ranges contained in the union. In addition, several helper methods make it easier to construct a range for a particular header. For example, to filter CDP numbers between 200 and 300, use the helper method cdp_range:

extent = Seismic2dExtent.cdp_range((200, 300))

class cognite.seismic.Seismic2dExtent(trace_key: cognite.seismic.data_classes.extents.TraceHeaderField, ranges: List[cognite.seismic.data_classes.extents.RangeInclusive])¶

Describes a selection of traces in a 2d seismic object.

trace_key¶

Which trace header field to select traces by

Type:	`TraceHeaderField`

ranges¶

A list of ranges of trace header values to include

Type:	List[`RangeInclusive`]

static cdp_range(range: Union[Tuple[int, int], Tuple[int, int, int]]) → cognite.seismic.data_classes.extents.Seismic2dExtent¶: Create an extent filtering by a single cdp range

static cdp_ranges(ranges: Iterable[Union[Tuple[int, int], Tuple[int, int, int]]]) → cognite.seismic.data_classes.extents.Seismic2dExtent¶: Create an extent filtering by a union of cdp ranges

static energy_source_point_range(range: Union[Tuple[int, int], Tuple[int, int, int]]) → cognite.seismic.data_classes.extents.Seismic2dExtent¶: Create an extent filtering by a single energy source point range

static energy_source_point_ranges(ranges: Iterable[Union[Tuple[int, int], Tuple[int, int, int]]]) → cognite.seismic.data_classes.extents.Seismic2dExtent¶: Create an extent filtering by a union of energy source point ranges

static shotpoint_range(range: Union[Tuple[int, int], Tuple[int, int, int]]) → cognite.seismic.data_classes.extents.Seismic2dExtent¶: Create an extent filtering by a single shotpoint range

static shotpoint_ranges(ranges: Iterable[Union[Tuple[int, int], Tuple[int, int, int]]]) → cognite.seismic.data_classes.extents.Seismic2dExtent¶: Create an extent filtering by a union of shotpoint ranges

3D extents¶

3D extents are specified as a combination of inline and crossline header values. There are a few different ways to combine ranges of inline and crossline numbers into an extent, hence the Seismic3dExtent class is again abstract, with different options as subclasses.

class cognite.seismic.Seismic3dExtent¶: Describes a selection of traces in a 3d seismic object. This is an abstract class: Concrete instances will be either Seismic3dRect, Seismic3dRects, or Seismic3dDef

The simplest way to filter a 3D object is to specify a stepped rectangle of inline and crossline values:

class cognite.seismic.Seismic3dRect(inline: Union[cognite.seismic.data_classes.extents.RangeInclusive, Tuple[int, int], Tuple[int, int, int]], xline: Union[cognite.seismic.data_classes.extents.RangeInclusive, Tuple[int, int], Tuple[int, int, int]])¶

Describes a selection of traces in a 3d seismic object as a stepped rectangle.

To construct a Seismic3dRect, pass either a RangeInclusive for the inline and xline arguments, or a tuple describing the start, and, and optionally step.

A pair (il, xl) is considered to be part of this extent if il is part of the range inline and xl is part of the range xline.

inline¶

The range of inline values to include

Type:	`RangeInclusive`

xline¶

The range of xline values to include

Type:	`RangeInclusive`

If the traces don’t map exactly into a single rectangle, one can instead specify a union of rectangles:

class cognite.seismic.Seismic3dRects(rects: List[cognite.seismic.data_classes.extents.Seismic3dRect])¶

Describes a selection of traces in a 3d seismic object as a union of stepped rectangles.

A pair (il, xl) is considered to be part of this extent if it is part of at least one of the rectangles in rects.

rects¶

The list of rectangles in the union

Type:	List[`Seismic3dRect`]

Finally, the most flexible extent is a mapping from inline numbers to ranges of crossline numbers, or vice versa:

class cognite.seismic.Seismic3dDef(major_header: cognite.seismic.data_classes.extents.TraceHeaderField, minor_header: cognite.seismic.data_classes.extents.TraceHeaderField, lines: Dict[int, List[cognite.seismic.data_classes.extents.RangeInclusive]])¶

Describes a selection of traces in a 3d seismic object as a mapping. For each major line (inline or xline) to include, provide a list of minor line ranges (xline or inline, respectively) to include for that major line.

If major_header == Inline and minor_header == Crossline, a pair (il, xl) is considered to be part of this extent if lines[il] is populated and xl is part of at least one of the ranges in lines[il]. The situation with the opposite major / minor header is similar.

major_header¶

Either Inline or Crossline

Type:	`TraceHeaderField`

minor_header¶

Either Crossline or Inline, and different from major_header

Type:	`TraceHeaderField`

lines¶

The mapping from major lines to minor ranges

Type:	Dict[int, List[`RangeInclusive`]]

get_bounding_box() → Optional[cognite.seismic.data_classes.extents.Seismic3dRect]¶: Get the bounding box of the extent, described as a Seismic3dRect where the step size is meaningless.

get_inline(xline: int) → List[int]¶

Get every inline for a given crossline

Returns:	A list of inlines

get_inline_counts() → Mapping[int, int]¶

Get the number of inlines for each crossline

Returns:	A mapping crossline->number of inlines

get_inline_ranges() → Mapping[int, Tuple[int, int]]¶

Get the minimum and maximum inlines for each crossline

Returns:	A mapping inline->[crossline min, crossline max]

get_major(minor: int) → List[int]¶: Get all major line numbers for a minor line

get_majors() → Mapping[int, List[int]]¶: Get all major line numbers for each minor line

get_minor(major: int) → List[int]¶: Get all minor line numbers for a major line

get_minor_range() → Mapping[int, Tuple[int, int]]¶: Get the minor line number range for each major line

get_minors() → Mapping[int, List[int]]¶: Get all minor line numbers for each major line

get_xline(inline: int) → List[int]¶

Get every crossline for a given inline

Returns:	A list of crosslines

get_xline_counts() → Mapping[int, int]¶

Get the number of crosslines for each inline.

Returns:	A mapping inline->number of crosslines

get_xline_ranges() → Mapping[int, Tuple[int, int]]¶

Get the minimum and maximum crosslines for each inline.

Returns:	A mapping inline->[crossline min, crossline max]

static inline_major(lines: Mapping[int, List[Union[Tuple[int, int], Tuple[int, int, int]]]]) → cognite.seismic.data_classes.extents.Seismic3dDef¶

Create a Seismic3dDef mapping inlines to xline ranges

Parameters:	lines (Mapping[int, List[LineRange]]) – A mapping from inline numbers to xline ranges in the (start, stop) or (start, stop, step) format.
Returns:	A `Seismic3dDef` extent.

static xline_major(lines: Mapping[int, List[Union[Tuple[int, int], Tuple[int, int, int]]]]) → cognite.seismic.data_classes.extents.Seismic3dDef¶

Create a Seismic3dDef mapping xlines to inline ranges

Parameters:	lines (Mapping[int, List[LineRange]]) – A mapping from xline numbers to inline ranges in the (start, stop) or (start, stop, step) format.
Returns:	A `Seismic3dDef` extent.

Pre-stack extents¶

For pre-stack data, we can also specify exactly which part of each bin is included in the cutout. These trace group extents are specified similarly to 2D extents, giving a collection of trace group headers which are included in each trace group.

class cognite.seismic.SeismicTraceGroupExtent(group_header: cognite.seismic.data_classes.extents.TraceHeaderField, ranges: List[cognite.seismic.data_classes.extents.RangeInclusive])¶

Describes a selection of traces in a prestack migrated seismic object. To be used with either a Seismic2dExtent or Seismic3dExtent to fully describe the object.

group_header¶

Which trace group header field to select traces by

Type:	`TraceHeaderField`

ranges¶

A list of ranges of trace group header values to include

Type:	List[`RangeInclusive`]

static cdp_trace_range(range: Union[Tuple[int, int], Tuple[int, int, int]]) → cognite.seismic.data_classes.extents.SeismicTraceGroupExtent¶: Create an extent filtering by a single cdp_trace range

static cdp_trace_ranges(ranges: Iterable[Union[Tuple[int, int], Tuple[int, int, int]]]) → cognite.seismic.data_classes.extents.SeismicTraceGroupExtent¶: Create an extent filtering by a union of cdp_trace ranges

static offset_range(range: Union[Tuple[int, int], Tuple[int, int, int]]) → cognite.seismic.data_classes.extents.SeismicTraceGroupExtent¶: Create an extent filtering by a single offset range

static offset_ranges(ranges: Iterable[Union[Tuple[int, int], Tuple[int, int, int]]]) → cognite.seismic.data_classes.extents.SeismicTraceGroupExtent¶: Create an extent filtering by a union of offset ranges

Cutout specifications¶

When creating a Seismic object as a cutout of it’s containing SeismicStore, there are a few choices as to how to describe the cutout. Each choice is a subclass of an abstract base class.

class cognite.seismic.SeismicCutout¶

Describes how a Seismic object is cut out of the containing SeismicStore. This is an abstract class: Concrete instances will be one of the following:

A subclass of SeismicExtent for describing exactly which traces to include
A geometry wrapped in a GeometryCutout object
EmptyCutout to explicitly describe an empty seismic object
FullCutout to describe a seismic containing all the data in the seismic store

In the simplest case, the trivial cutout lets the seismic object simply inherit all the traces from the seismic store, by specifying an instance of the FullCutout class:

class cognite.seismic.FullCutout¶: Describes a cutout filling its entire containing seismic store

In order to cut by geometry, wrap the geometry in a GeometryCutout:

class cognite.seismic.GeometryCutout(geometry: cognite.seismic.data_classes.geometry.Geometry)¶

Describes a cutout by a geometry.

geometry¶

The geometry to cut by

Type:	`Geometry`

One can also specify exactly which traces to include by passing an extent object for the cutout. Finally, in the rare edge case that you want to explicitly create an empty cutout containing no traces, pass an instance of EmptyCutout:

class cognite.seismic.EmptyCutout¶: Describes an empty cutout

Types for bin grid to projected coordinates transformation¶

These classes can be used to specify a custom transformation from the (inline, xline) bin grid to projected coordinates on a per-survey basis, using the argument grid_transformation to survey.create or survey.edit.

class cognite.seismic.SurveyGridTransformation¶

Description of an affine transformation between bin grid coordinates and projected coordinates. Pass a subclass of this in the grid_transformation parameter to survey.create or survey.edit to describe the transformation on a per-survey basis.

This is an abstract class - concrete instances will be one of P6Transformation for an explicit mathematical description of the transformation, CoordList to specify it as a list of correlated coordinates, or DeduceFromTraces to request that the seismic service attempts to deduce the transformation from individual traces.

class cognite.seismic.DeduceFromTraces¶: Pass an instance of this class as the grid_transformation argument to indicate that the seismics service should try to deduce the affine transformation between bin grid coordinates and projected coordinates from the trace coordinates themselves.

class cognite.seismic.CoordList(coordinates: List[cognite.seismic.data_classes.api_types.DoubleTraceCoordinates])¶

Description of an affine transformation between bin grid coordinates and projected coordinates as a list of three or more points spanning the area of the bin grid.

coordinates¶

The list of points spanning the grid.

Type:	List[`DoubleTraceCoordinates`]

class cognite.seismic.DoubleTraceCoordinates(x: float, y: float, inline: int, xline: int)¶

The coordinates of a point, given in both projected coordinates (x, y) and in bin grid coordinates (inline, xline).

Pass a list of three or more instances to specify the affine transformation between bin grid coordinates and projected coordinates by the corners of the grid.

x¶

Longitude or easting

Type:	float

y¶

Latitude or northing

Type:	float

inline¶

The inline coordinate of the bin grid

Type:	int

xline¶

The xline coordinate of the bin grid

Type:	int

class cognite.seismic.P6Transformation(origin: cognite.seismic.data_classes.api_types.DoubleTraceCoordinates, inline_bin_width: float, xline_bin_width: float, xline_azimuth: float, handedness: cognite.seismic.data_classes.api_types.Handedness = <Handedness.RIGHTHANDED: 0>, inline_bin_inc: int = 1, xline_bin_inc: int = 1)¶

Description of an affine transformation between bin grid coordinates and projected coordinates in the P6 format, loosely following IOGP guidance note 373-7-2 section 2.3.2.4.

origin¶

The origin point of the transformation

Type:	`DoubleTraceCoordinates`

inline_bin_width¶

The width of bins in the inline direction

Type:	float

xline_bin_width¶

The width of bins in the xline direction

Type:	float

xline_azimuth¶

The direction of the xline axis, in degrees clockwise from north

Type:	float

handedness¶

The orientation of the inline vs. the xline axes. Default: RIGHTHANDED.

Type:	`Handedness`

inline_bin_inc¶

The increment of the inline coordinate corresponding to a bin. Default: 1.

Type:	Optional[int]

xline_bin_inc¶

The increment of the xline coordinate corresponding to a bin. Default: 1.

Type:	Optional[int]

class cognite.seismic.Handedness¶

The handedness of a P6Transformation.

RIGHTHANDED = 0¶: Specifies that the inline axis is 90 degrees clockwise from the xline axis.

LEFTHANDED = 1¶: Specifies that the inline axis is 90 degrees counter-clockwise from the xline axis.

SourceSegyFile¶

class cognite.seismic.SourceSegyFile(id: int, external_id: str, name: str, survey_id: int, cloud_storage_path: str, metadata: Mapping[str, str], segy_overrides: cognite.seismic.data_classes.api_types.SegyOverrides, key_fields: List[cognite.seismic.data_classes.extents.TraceHeaderField], dimensions: int, seismic_data_type: cognite.seismic.data_classes.api_types.SeismicDataType, crs: str, last_modified: datetime.datetime, uuid: str)¶

Represents a raw SEGY file as used in the seismicstore-aware API, particularly for ingestion.

id¶

A 64-bit integer that represents the source file internally within the seismic service.

Type:	int

uuid¶

The unique string-based uuid of a source segy file.

Type:	str

external_id¶

A string-based user id that uniquely identifies the file.

Type:	str

name¶

Non-unique string that describes the file.

Type:	str

survey_id¶

The id of the survey this file is registered against

Type:	int

cloud_storage_path¶

The cloud storage path where the file is located.

Type:	str

metadata¶

User-provided metadata in the form of a string to string mapping

Type:	Mapping[str, str]

segy_overrides¶

A set of SegY overrides

Type:	`SegyOverrides`

key_fields¶

The trace header fields that are used as keys for indexing

Type:	List[`TraceHeaderField`]

seismic_data_type¶

Whether this file is pre-stack or post-stack.

Type:	`SeismicDataType`

dimensions¶

File dimensionality, either 2 or 3 dimensions.

Type:	int

crs¶

The coordinate reference system used for this file.

Type:	str

SegyOverrides¶

class cognite.seismic.SegyOverrides(energy_source_point_offset: Optional[int], cdp_number_offset: Optional[int], inline_offset: Optional[int], crossline_offset: Optional[int], cdp_x_offset: Optional[int], cdp_y_offset: Optional[int], shotpoint_offset: Optional[int], cdp_trace_offset: Optional[int], offset_header_offset: Optional[int], source_group_scalar_override: Optional[float])¶

A set of SegY header overrides for a given ingested file.

energy_source_point_offset¶

Type:	Optional[int]

cdp_number_offset¶

Type:	Optional[int]

inline_offset¶

Type:	Optional[int]

crossline_offset¶

Type:	Optional[int]

cdp_x_offset¶

Type:	Optional[int]

cdp_y_offset¶

Type:	Optional[int]

shotpoint_offset¶

Type:	Optional[int]

cdp_trace_offset¶

Type:	Optional[int]

offset_header_offset¶

Type:	Optional[int]

source_group_scalar_override¶

Type:	Optional[float]

Survey¶

class cognite.seismic.Survey(id: int, external_id: Optional[str], name: str, seismic_ids: Optional[List[int]], metadata: Optional[Mapping[str, str]], last_modified: datetime.datetime, uuid: str, seismic_store_ids: Optional[List[int]], coverage: Optional[cognite.seismic.data_classes.geometry.Geometry], crs: Optional[str], grid_transformation: Optional[cognite.seismic.data_classes.api_types.SurveyGridTransformation], custom_coverage: Optional[cognite.seismic.data_classes.geometry.Geometry], survey_coverage_source: Optional[cognite.seismic.data_classes.api_types.SurveyCoverageSource])¶

Represents a seismic survey, a grouping of related files

id¶

The unique internal id of the survey.

Type:	int

external_id¶

A string-based user id that uniquely identifies the survey.

Type:	str

uuid¶

The unique internal id of the survey, in the old uuid format

Type:	str

name¶

A descriptive name of the survey.

Type:	str

seismic_ids¶

A list of seismic ids contained in the survey (if requested)

Type:	List[int]

seismic_store_ids¶

A list of the seismic store ids contained in the survey (if requested; only available for data managers)

Type:	List[int]

metadata¶

Any custom-defined metadata

Type:	Mapping[str, str]

coverage¶

If present, the coverage geometry for this survey

Type:	`Geometry`

survey_coverage_source¶

Whether the coverage is a custom-defined survey coverage, or computed from the containing seismic stores.

Type:	`SurveyCoverageSource`

crs¶

The coordinate reference system used by all members of this survey

Type:	str

grid_transformation¶

Any custom-defined transformation from bin grid to projected coordinates, if requested

Type:	`SurveyGridTransformation`

custom_coverage¶

Any custom-defined coverage geometry, if requested

Type:	`Geometry`

Geometry¶

class cognite.seismic.Geometry(crs: str, *, geojson=None, wkt=None)¶

Represents a CRS + shape, in either a WKT format or a GeoJSON.

crs¶

The CRS of the shape.

Type:	str

geojson¶

If exists, the GeoJSON representation of this shape

Type:	Optional[dict]

wkt¶

If exists, the Well Known Text representation of this shape

Type:	Optional[str]

class cognite.seismic.InterpolationMethod¶

Method for interpolating between traces when filtering by linear geometries.

NearestTrace = 0¶: Set values to those of the nearest trace

InverseDistanceWeighting = 1¶: Linear interpolation between traces weighted by inverse distance

BinaryHeader¶

class cognite.seismic.BinaryHeader(traces: int, trace_data_type: int, fixed_length_traces: int, segy_revision: int, auxtraces: int, interval: int, interval_original: int, samples: int, samples_original: int, ensemble_fold: int, vertical_sum: int, trace_type_sorting_code: int, sweep_type_code: int, sweep_frequency_start: int, sweep_frequency_end: int, sweep_length: int, sweep_channel: int, sweep_taper_start: int, sweep_taper_end: int, sweep_taper_type: int, correlated_traces: int, amplitude_recovery: int, original_measurement_system: int, impulse_signal_polarity: int, vibratory_polarity_code: int, raw_header: Optional[bytes] = None)¶

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.

traces¶

trace_data_type¶

fixed_length_traces¶

segy_revision¶

auxtraces¶

interval¶

interval_original¶

samples¶

samples_original¶

ensemble_fold¶

vertical_sum¶

trace_type_sorting_code¶

sweep_type_code¶

sweep_frequency_start¶

sweep_frequency_end¶

sweep_length¶

sweep_channel¶

sweep_taper_start¶

sweep_taper_end¶

sweep_taper_type¶

correlated_traces¶

amplitude_recovery¶

original_measurement_system¶

impulse_signal_polarity¶

vibratory_polarity_code¶

TextHeader¶

class cognite.seismic.TextHeader(header: Optional[str] = None, raw_header: Optional[str] = None)¶

A representation of text headers used to create or edit existing headers.

header¶

The text content of the header

Type:	Optional[str]

raw_header¶

The raw bytes of a header as a string

Type:	Optional[str]

SeismicStore¶

class cognite.seismic.SeismicStore(id: int, name: str, survey_id: int, ingestion_source: cognite.seismic.data_classes.api_types.IngestionSource, metadata: Mapping[str, str], storage_tier_name: List[str], trace_header_fields: List[cognite.seismic.data_classes.extents.TraceHeaderField], dimensions: int, seismic_data_type: cognite.seismic.data_classes.api_types.SeismicDataType, last_modified: datetime.datetime, survey_uuid: str, ingested_file: Optional[cognite.seismic.data_classes.api_types.SourceSegyFile], coverage: Optional[cognite.seismic.data_classes.geometry.Geometry], text_header: Optional[cognite.seismic.data_classes.api_types.TextHeader], binary_header: Optional[cognite.seismic.data_classes.api_types.BinaryHeader], extent: Optional[cognite.seismic.data_classes.extents.SeismicExtent], crs: str, _traces: cognite.seismic._api.traces.TracesAPI)¶

Represents a seismic store.

id¶

The unique internal id of the seismic store.

Type:	int

name¶

The unique name of the seismic store.

Type:	str

survey_id¶

The survey this seismic store belongs to.

Type:	int

survey_uuid¶

The survey this seismic store belongs to, in the old uuid format.

Type:	str

ingestion_source¶

The source of the seismicstore.

Type:	`IngestionSource`

metadata¶

Any custom-defined metadata

Type:	Mapping[str, str]

ingested_file¶

If present, the file this SeismicStore was ingested from

Type:	Optional[`SourceSegyFile`]

coverage¶

If present, the coverage geometry for this seismic store

Type:	Optional[`Geometry`]

text_header¶

If present, the text header for this seismic store

Type:	Optional[`TextHeader`]

binary_header¶

If present, the binary header for this seismic store

Type:	Optional[`BinaryHeader`]

storage_tier_name¶

The names of the storage tiers this seismic store exists in

Type:	List[str]

extent¶

If present, a description of the traces contained in this seismic store.

Type:	Optional[`SeismicExtent`]

trace_header_fields¶

The trace header fields that are available for accessing indexed trace data.

Type:	List[`TraceHeaderField`]

seismic_data_type¶

Whether this seismic store describes pre-stack or post-stack data.

Type:	`SeismicDataType`

dimensions¶

The underlying segy file’s dimensionality, either 2 or 3 dimensions.

Type:	int

crs¶

The Coordinate Reference System of the seismic store

Type:	str

get_array(*, progress: Optional[bool] = None, **kwargs) → cognite.seismic.data_classes.trace_data.ArrayData¶

Store traces from this seismic store into a numpy array

Parameters: See stream_traces().

In addition, there’s an optional boolean argument progress, which turns a progress bar on or off and defaults to True.

Returns:	An `ArrayData` object encapsulating the retrieved array (see below)

get_segy(**kwargs) → Iterator[bytes]¶

Retrieve traces in binary format from the seismic store

The first and second elements in the response stream will always be the text header and binary header of the file.

Traces can be filtered by a geometry, by line ranges, or by a SeismicExtent object for more advanced line-based filtering. The line ranges are specified as tuples of either (start, end) or (start, end, step). If a filter is not specified, the maximum ranges will be assumed.

Note that while both inline_range and xline_range may be specified at the same time, only one of cdp_range, shotpoint_range or energy_source_point_range may be specified.

Parameters:	inline_range (line range, optional) – Range of inline values to include. Only valid for 3d objects. xline_range (line range, optional) – Range of xline values to include. Only valid for 3d objects. cdp_range (line range, optional) – Range of cdp numbers to include. Only valid for a 2d object. shotpoint_range (line range, optional) – Range of shotpoint numbers to include. Only valid for a 2d object. energy_source_point_range (line range, optional) – Range of energy_source_point numbers to include. Only valid for a 2d object. extent (`SeismicExtent`, optional) – A SeismicExtent object indicating which traces to include geometry (`Geometry`, optional) – Return traces inside this geometry (if area-like) or interpolate traces onto a line (if line-like; only valid for 3d objects).
Returns:	A stream of buffers that, when concatenated, constitute a SEG-Y stream.
Return type:	Iterator[bytes]

get_trace_bounds(**kwargs) → cognite.seismic.data_classes.trace_data.TraceBounds¶

Compute the amount of data that will be returned for a given stream_traces request for this seismic store. This may be used to allocate sufficient data in an array, and also describes the range of the key header fields used to identify traces, ie. the range of the inline and xline numbers for 3D data, or the CDP or shotpoint field values for 2D data.

Parameters: See stream_traces()

Returns:	A `TraceBounds` object describing the size and bounds of the returned traces

stream_traces(**kwargs) → Iterator[cognite.seismic.data_classes.trace_data.Trace]¶

Retrieve traces from this seismic store

Traces can be filtered by a geometry, by line ranges, or by a SeismicExtent object for more advanced line-based filtering. The line ranges are specified as tuples of either (start, end) or (start, end, step). If a filter is not specified, the maximum ranges will be assumed.

Note that while both inline_range and xline_range may be specified at the same time, only one of cdp_range, shotpoint_range or energy_source_point_range may be specified.

Parameters:

extent (SeismicExtent, optional) – A SeismicExtent object indicating which traces to include
geometry (Geometry, optional) – Return traces inside this geometry (if area-like) or interpolate traces onto a line (if line-like; only valid for 3d objects).
interpolation_method (InterpolationMethod, optional) – Interpolation method to use when interpolating traces. Only valid if geometry is a line-like geometry.
z_range (line range, optional) – The range of depth indices to include. Specified as a tuple of (int, int) or (int, int, int), representing start index, end index, and step size respectively.
include_trace_header (bool, optional) – Whether to include trace header info in the response.

Returns:

Iterator[Trace], the traces for the specified volume

Seismic¶

class cognite.seismic.Seismic(id: int, external_id: str, crs: str, metadata: Mapping[str, str], trace_header_fields: List[cognite.seismic.data_classes.extents.TraceHeaderField], dimensions: int, seismic_data_type: cognite.seismic.data_classes.api_types.SeismicDataType, last_modified: datetime.datetime, name: str, text_header: Optional[cognite.seismic.data_classes.api_types.TextHeader], binary_header: Optional[cognite.seismic.data_classes.api_types.BinaryHeader], partition_id: int, seismicstore_id: Optional[int], coverage: Optional[cognite.seismic.data_classes.geometry.Geometry], trace_count: int, extent: Optional[cognite.seismic.data_classes.extents.SeismicExtent], cutout: Optional[cognite.seismic.data_classes.extents.SeismicCutout], _traces: cognite.seismic._api.traces.TracesAPI)¶

Represents a seismic, a cutout of a seismic store.

id¶

The unique internal id of the seismic

Type:	int

external_id¶

The external id of the seismic

Type:	str

crs¶

The Coordinate Reference System of the seismic

Type:	str

metadata¶

Any custom-defined metadata

Type:	Mapping[str, str]

text_header¶

The text header that corresponds to the seismic

Type:	Optional[`TextHeader`]

binary_header¶

The binary header that corresponds to the seismic

Type:	Optional[`BinaryHeader`]

partition_id¶

The id of the partition the seismic belongs to

Type:	int

seismicstore_id¶

The id of the seismicstore the seismic is derived from

Type:	int

coverage¶

The coverage geometry for the seismic.

Type:	Optional[`Geometry`]

extent¶

A detailed description of the traces included in the seismic object

Type:	Optional[`SeismicExtent`]

trace_header_fields¶

The trace header fields that are available for accessing indexed trace data.

Type:	List[`TraceHeaderField`]

seismic_data_type¶

Whether this seismic describes pre-stack or post-stack data.

Type:	`SeismicDataType`

dimensions¶

The underlying segy file’s dimensionality, either 2 or 3 dimensions.

Type:	int

get_array(*, progress: Optional[bool] = None, **kwargs) → cognite.seismic.data_classes.trace_data.ArrayData¶

Store traces from this seismic into a numpy array

Parameters: See stream_traces().

In addition, there’s an optional boolean argument progress, which turns a progress bar on or off and defaults to True.

Returns:	An `ArrayData` object encapsulating the retrieved array (see below)

get_segy(**kwargs) → Iterator[bytes]¶

Retrieve traces in binary format from this seismic

The first and second elements in the response stream will always be the text header and binary header of the file.

Traces can be filtered by a geometry, by line ranges, or by a SeismicExtent object for more advanced line-based filtering. The line ranges are specified as tuples of either (start, end) or (start, end, step). If a filter is not specified, the maximum ranges will be assumed.

Note that while both inline_range and xline_range may be specified at the same time, only one of cdp_range, shotpoint_range or energy_source_point_range may be specified.

Parameters:	extent (`SeismicExtent`, optional) – A SeismicExtent object indicating which traces to include geometry (`Geometry`, optional) – Return traces inside this geometry (if area-like) or interpolate traces onto a line (if line-like; only valid for 3d objects).
Returns:	A stream of buffers that, when concatenated, constitute a SEG-Y stream.
Return type:	Iterator[bytes]

get_trace_bounds(**kwargs) → cognite.seismic.data_classes.trace_data.TraceBounds¶

Compute the amount of data that will be returned for a given stream_traces request for this seismic. This may be used to allocate sufficient data in an array, and also describes the range of the key header fields used to identify traces, ie. the range of the inline and xline numbers for 3D data, or the CDP or shotpoint field values for 2D data.

Parameters: See stream_traces()

Returns:	A `TraceBounds` object describing the size and bounds of the returned traces

stream_traces(**kwargs) → Iterator[cognite.seismic.data_classes.trace_data.Trace]¶

Retrieve traces from this seismic

Traces can be filtered by a geometry, by line ranges, or by a SeismicExtent object for more advanced line-based filtering. The line ranges are specified as tuples of either (start, end) or (start, end, step). If a filter is not specified, the maximum ranges will be assumed.

Note that while both inline_range and xline_range may be specified at the same time, only one of cdp_range, shotpoint_range or energy_source_point_range may be specified.

Parameters:

extent (SeismicExtent, optional) – A SeismicExtent object indicating which traces to include
geometry (Geometry, optional) – Return traces inside this geometry (if area-like) or interpolate traces onto a line (if line-like; only valid for 3d objects).
interpolation_method (InterpolationMethod, optional) – Interpolation method to use when interpolating traces. Only valid if geometry is a line-like geometry.
z_range (line range, optional) – The range of depth indices to include. Specified as a tuple of (int, int) or (int, int, int), representing start index, end index, and step size respectively.
include_trace_header (bool, optional) – Whether to include trace header info in the response.

Returns:

Iterator[Trace], the traces for the specified volume

Partition¶

class cognite.seismic.Partition(id: int, external_id: str, name: str, last_modified: datetime.datetime, seismic_ids: List[int])¶

Represents a partition and its included seismics

id¶

The unique internal id for this partition

Type:	int

external_id¶

The unique external id for this partition

Type:	str

name¶

The human-friendly name for this partition

Type:	str

seismic_ids¶

A list of ids of seismics that belong to this partition

Type:	List[int]

IngestionJob¶

class cognite.seismic.IngestionJob(job_id: str)¶

The newly created ingestion job’s unique id.

job_id¶

The unique id of the newly created job.

Type:	str

SearchSpecBase¶

class cognite.seismic.data_classes.searchspec.SearchSpecBase¶: Base class for search specs. The concrete implementations are SearchSpecGetAll, SearchSpecLastModified, SearchSpecSurvey, SearchSpecSeismicStore, SearchSpecFile.

SearchSpecSurvey¶

class cognite.seismic.SearchSpecSurvey(id: Optional[int] = None, external_id: Optional[str] = None, external_id_substring: Optional[str] = None, name: Optional[str] = None, name_substring: Optional[str] = None, uuid: Optional[str] = None)¶: Defines a spec to search for objects by survey identifiers. Only one such identifier be specified.

SearchSpecSeismicStore¶

class cognite.seismic.SearchSpecSeismicStore(id: Optional[int] = None, external_id: Optional[str] = None, external_id_substring: Optional[str] = None, name: Optional[str] = None, name_substring: Optional[str] = None, uuid: Optional[str] = None)¶: Defines a spec to search for seismics, files, and seismic stores by seismic store identifiers. Only one such identifier should be specified.

SearchSpecFile¶

class cognite.seismic.SearchSpecFile(id: Optional[int] = None, external_id: Optional[str] = None, external_id_substring: Optional[str] = None, name: Optional[str] = None, name_substring: Optional[str] = None, uuid: Optional[str] = None)¶: Defines a spec to search for seismic stores by file identifiers. Only one such identifier should be specified.

SearchSeismic¶

class cognite.seismic.SearchSpecSeismic(id: Optional[int] = None, external_id: Optional[str] = None, external_id_substring: Optional[str] = None, name: Optional[str] = None, name_substring: Optional[str] = None, uuid: Optional[str] = None)¶: Defines a spec to search for seismics by seismic identifiers. Only one such identifier should be specified.

SearchSpecPartition¶

class cognite.seismic.SearchSpecPartition(id: Optional[int] = None, external_id: Optional[str] = None, external_id_substring: Optional[str] = None, name: Optional[str] = None, name_substring: Optional[str] = None, uuid: Optional[str] = None)¶: Defines a spec to search for seismics by partition. Only one such identifier should be specified.

SearchSpecGetAll¶

class cognite.seismic.SearchSpecGetAll¶: Defines a spec to search for all objects.

SearchSpecLastModified¶

class cognite.seismic.SearchSpecLastModified(before: Union[datetime.datetime, NoneType] = None, after: Union[datetime.datetime, NoneType] = None)¶

Error types¶

SeismicServiceError¶

class cognite.seismic.errors.SeismicServiceError(status=None, message=None, hint=None, source=None, request_id=None)¶: The base class for all seismic service-related errors.

NotFoundError¶

class cognite.seismic.errors.NotFoundError(status=None, message=None, hint='The object was not found.', source=None, request_id=None)¶: The object was not found.

TransientError¶

class cognite.seismic.errors.TransientError(status=None, message=None, source=None, request_id=None)¶: A temporary error that can usually be solved by retrying the request.

InternalError¶

class cognite.seismic.errors.InternalError(status=None, message=None, source=None, request_id=None)¶: An internal error. Please contact support.

AuthenticationError¶

class cognite.seismic.errors.AuthenticationError(status=None, message=None, source=None, request_id=None)¶: An unauthenticated request was made.

InvalidArgumentError¶

class cognite.seismic.errors.InvalidArgumentError(status=None, message=None, source=None, request_id=None)¶: An invalid argument was provided.

PermissionError¶

class cognite.seismic.errors.PermissionError(status=None, message=None, source=None, request_id=None)¶: Insufficient permissions.