ZGY tool

Owned by Anders Moe
Last updated: Sept 24, 2019 by Andreas Paulsen (Unlicensed)
6 min read

The Geocap ZGY tool is used to create ArcGIS features and rasters from Petrel ZGY files. 


The ZGY tool can read a ZGY file and create a ArcGIS feature class containing the navigation geometry and metadata. The ZGY tool has the following features:

  1. Create exact navigation outlines based on live traces. Rather than a simple rectangle the tool will create a set of polygons  showing the exact coverage.
  2. Conversion of ZGY to ArcGIS rasters. This makes it possible to view the seismics in the Geocap Seismic Explorer as well as storing the data in cost-effective storage such as Amazon S3.
  3. The tool can be run as a command-line utility without the need to have Petrel or ArcGIS installed on your system.
  4. If you have ArcGIS desktop installed you may benefit from an easy-to-use graphical tool interface.

Obtaining the tool

Please contact Geocap for information on how to obtain the ZGY tool.

Command line vs interactive tool

There are three ways to use the ZGY tool.


  1. As a command line tool using the ZGYTool executable. This has the advantage of not requiring ArcPy. However the command has to be invoked several times in order to create a geodatabase, add features etc.
  2. As a command line python script. The importZGY.py file can be invoked as a one-liner with several arguments that perform a complete run from creating a geodatabase to creating rasters.
  3. As an interactive Python tool. The ImportZGY.pyt toolbox can be conveniently executed interactively from ArcMap/ArcGIS Pro or in batch using ArcPy.

Each option is documented in the following sections.

Raster output vs ZGY

When using the tool you have a choice of converting the ZGY file to ArcGIS rasters. Whether you choose to do so or not depends on the subsequent steps in your seismic workflow. Some things to keep in mind:

  1. If you wish to view the seismics in the Geocap Seismic Explorer you must perform a raster conversion. The Seismic Explorer does not currently support viewing directly from ZGY.
  2. If you plan on publishing the data to Geocap Seismic Server you may again choose to keep the ZGY file as is, since the Seismic Server is capable of reading directly from a ZGY file. If you wish to attain maximum visualization performance or plan on using Amazon S3 storage, however, you should convert the ZGY file to rasters. For most purposes having the Seismic Server display directly from ZGY gives sufficient performance.

About live traces

The ZGY tool detects missing or zero-traces in the ZGY volume and is therefore able to create an outline based on the exact coverage. The ZGY format itself does not support missing traces, therefore the following algorithm is applied:

  • A trace with all values equal to 0 inside a given z interval will be considered a missing trace (or zero trace) and will be omitted from the pool of traces used to assemble the final polygon.
  • This interval can be explicitly provided using the topZT and bottomZT command line arguments
  • If the topZT/bottomZT arguments are omitted an interval containing 50 timeslices in the middle of the cube will be used.

About compressed ZGY files

The ZGY tool is capable of reading compressed ZGY files.

Installing the ZGY tool

The ZGY tool required no separate installation step. When unzipping the package the command line utility ZGYTool.exe and python toolboxes are immediately available in the unpacked folder. 

Invoking the ImportZGY tool from ArcGIS Desktop

To run the ZGY from ArcMap or ArcGIS Pro:

  1. Ensure that the ArcGIS desktop application (ie ArcCatalog) has access to the unpacked ZGY tool
  2. Open the ImportZGY toolbox
  3. Double-click to open the Import 3D seismic from ZGY file tool.
  4. Enter the correct values in the tool dialog. Each field is documented in the right-side panel. 
  5. If you wish to only create navigation features you may uncheck the Raster output button. 


Invoking the ImportZGY tool from the command line

Locate the ImportZGY.py script. In the window command line shell enter

python.exe importZGY.py --help

to see a list of arguments.Tip : Use ZGYTool.exe --info --nostats to see the valid range of topZT/bottomZT values.

Invoking the ZGY tool from the command line

To run the ZGY tool from the command line : 

  1. Open a Windows command window or PowerShell window.
  2. Invoke the ZGYTool.exe without arguments to have the various options listed.
  3. The steps involved are:
    1. Create a file geodatabase
    2. Create a feature class in the geodatabase
    3. Add a feature in the feature class from the ZGY file. The feature will contain a live trace outline as well as various metadata.
    4. Optionally, create ArcGIS rasters from the ZGY file.


The following script show a complete run creating a feature class and rasters.



set GDB="TEST.gdb"
set FC="SeismicCubes"
set WKID=23031
set RASTER_DIR="RASTERS"
set ZGY_FILE="C:\Data\MS97M_1.zgy"

mkdir %RASTER_DIR%
call ZGYTool.exe -create-db %GDB%
call ZGYTool.exe -create-feature-class %GDB% %FC% %WKID%
call ZGYTool.exe -add-feature-raster %GDB% %FC% %RASTER_DIR% %ZGY_FILE%



Command line arguments

info  [-nostats] <zgyfilepath>

Display key statistics and metadata from the file. If the nostats argument is provided the calculation of min, max, mean and std. dev  will be omitted. This will save some time on large volumes.

The SeismicZUnit setting will apply to the following: DelayRecTime, TMin, TMax and TStep.


create-db <workspacepath>

Create an ArcGIS file geodatabase. The workspace path will be a path to the new filegeodatabase including the .gdb ending. SDE databases are not supported.


create-feature-class <workspacepath> <featureclassname> [wkid]

Create a feature class with the given name in the provided file geodatabase.The wkid is a well-known EPSG spatial reference id.


add-feature <workspacepath> <featureclassname> <zgyfilepath> [topZT bottomZT]

Add the navigation outline of the seismics as a feature to the named featureclass. Live traces will be calculated using the following algorithm:

  • A trace with all values equal to 0 inside a given z interval will be considered a missing trace (or zero trace) and will be omitted from the pool of traces used to assemble the final polygon.
  • This interval can be explicitly provided using the topZT/bottomZT arguments
  • If the topZT/bottomZT arguments are omitted an interval containing 50 timeslices in the middle of the cube will be used.

The topZY/bottomZT values are taken to be positive downwards. Valid examples would be topZT = 400 and bottomZT = 800.

Hint :  Use the info argument to see the valid Z range for your cube. 

add-feature-nostats <workspacepath> <featureclassname> <zgyfilepath> [topZT bottomZT]

This is similar to add-feature with the exception that the calculation of min, max, mean and std. dev  will be omitted. This will save some time on large volumes. However the resulting feature class can only be displayed as a polygon, not as a seismic cube. 

add-feature-raster <workspacepath> <featureclassname> <rasterdirectory> <zgyfilepath> [topZT bottomZT]

This is similar to add-feature with the addition of rasters being generated from the seismic data. You may want to create rasters if:

  1. You want to view the volume in 3D in the Geocap Seismic Explorer
  2. You want to use rasters as backend storage for the Seismic Server. Rasters can be stored in Amazon S3 or in any ArcGIS raster storage and generally provide optimal viewing performance at the cost of disk space. Generating the rasters can also be time-consuming.


create-livetrace-raster <zgyfilepath> <rasterpath> [topZT bottomZT]

Creates a TIF raster with value 0 where a trace is zero and 1 elsewhere. The raster has inline along x-axis and crossline along y-axis as coordinates. 


setURL <workspacepath> <featureclassname> <dstDir>

Loops trough all features and replaces the directory in the URL field of the feature with dstDir.

This is useful if you want to move the rasters to another location eg. when moving the data to a server. 


Viewing the seismics in web 3D

Using the Geocap Seismic Server and client you can view the seismic 3D volume in a web browser. 

  1. The Geocap Seismic Server is capable of reading the ZGY file directly. You may however use the tool to generate rasters if you wish to store the rasters in a geodatabase or Amazon S3 or if you generally want maximum performance.
  2. Copy the rasters or ZGY file to a location on the server from which the ArcGIS has access. Make a note of the location as seen from the server.
  3. Use the Set Seismic URL tool to create a copy of the seismic feature class with URLs updated to reflect the location on the server. The Seismic Server SOE will use this URL when reading the seismics.
  4. Create a map using the feature class with the server-side URLs and publish as a map service. This will give you a URL to the feature layer containing the seismic outline.
  5. In the seismic web app open the 3D viewer and click Scene → Add Data and enter the URL of the seismic outline. The 3D volume should display. See the section Web Client for details on how to configure your own scene file containing the outline.

Troubleshooting the ZGY tool

If the ZGY tool or any of the scripts do not work as they should;

please start the program "DbgView.exe" from the same folder as ZGYTool.exe. This program listens to diagnostic log messages from ZGY tool.

Then rerun the command that did not work. The log can be saved to a text file from DebugView: File→Save As...

When contacting Geocap for support please attach this log file.