capstool

CAPS command-line interface (CLI) client.

Description

capstool is a CAPS client application for retrieving data and listing available streams from an operational CAPS server.

Input

The program reads requests from file or from standard input if no file is specified. The request format is defined as follows:

YYYY,MM,DD,HH,MM,SS YYYY,MM,DD,HH,MM,SS Network Station [Location] Channel

Each request line contains a start and an end time followed by a stream id. The fields Network, Station, Channel and Location support wild cards (*). The latter one is optional. For matching all locations please use the ‘*’ symbol, if empty it assumes that only empty locations are being requested.

Note

The request lines can be generated for a particular event using scevtstreams [13] as of the SeisComP3 release Jakarta-2018.xxx.

Example:

2010,02,18,12,00,00 2010,02,18,12,10,00 GE WLF BH*
2010,02,18,12,00,00 2010,02,18,12,10,00 GE VSU 00 BH*

Output

The output format differs by record type. Below is an overview of the available formats.

Record type	Output data format
RAW	ASCII SLIST
MSEED	MSEED
ANY	Stored data format

Note

When retrieving miniSEED data the records are not necessarily sorted by time. However, sorting by time is required, e.g., for processing in playbacks. Use scmssort [14] for sorting the records by time. Example:

scmssort -E -u data.mseed > data_sorted.mseed

Examples

• List available streams:

  capstool -H localhost:18002 -Q
  

• Secured connection:

  Connect via Secure Sockets Layer (SSL) and supply credentials for authentication.

  capstool -H localhost:18002 -s -c user:password -Q
  

• Time-based request without request file:

  Request file to load miniSEED data for some GE stations:

  2010,02,18,12,00,00 2010,02,18,12,10,00 GE WLF BH*
  2010,02,18,12,00,00 2010,02,18,12,10,00 GE VSU BH*
  

  Submit the request in req.txt to the CAPS server, and download miniSEED data to the file data.mseed.

  capstool -H localhost:18002 -o data.mseed req.txt
  

• Time-based request without request file:

  Request miniSEED data from a CAPS server. Provide request parameters from standard input. Write the miniSEED data to standard output. Re-direct the output and append it to a file, e.g., data.mseed:

  echo "2015,11,08,10,47,00 2015,11,08,11,00,00 * * BH?" |\
  capstool -H localhost:18002 >> data.mseed
  

• Event-based request:

  Request miniSEED data from a CAPS server for a particular event with ID <eventID>. Provide the request file using scevtstreams [13]. Write the miniSEED data to standard output. Re-direct the output to a file, e.g., <eventID>.mseed.

  scevtstreams -d mysql://sysop:sysop@localhost/seiscomp -E <eventID> --caps > req.txt
  capstool -H localhost:18002 req.txt > <eventID>.mseed
  

• Video data:

  Request to load video data from Station HILO. Request file:

  2013,08,01,00,00,00 2013,08,01,00,30,00 VZ HILO WLS CAM
  2013,08,01,00,00,00 2013,08,01,00,30,00 VZ HILO WLS CAM
  

  Submit the request in req.txt to the CAPS server, and download the video data to files using the given pattern:

  capstool -H localhost:18002 -o "%H%M%S.%f" req.txt
  

Command-Line Options

capstool [options]

Options

-h, --help

Show a help message and exit.

-H, --host HOST[:PORT]

Default: localhost:18002

Host and optionally port of the CAPS server (default is localhost:18002).

-s, --ssl

Use secure socket layer (SSL).

-c, --credentials USER[:PASSWORD]

Authentication credentials. If the password is omitted, it is asked for on command-line.

-P, --ping

Retrieve server version information and exit.

-Q

Print availability extents of all data streams.

-I, --info-streams FILTER

Like -Q but with a use a regular filter expression for the requested streams, e.g., AM.*.

--filter-list

Identical to -I.

Options (request file, no data download)

-G, --print-gaps

Request list of data gaps.

-S, --print-segments

Request list of continuous data segments.

--tolerance SECONDS

Threshold in seconds defining a data gap (decimal point, microsecond precision).

-R, --Resolution DAYS

The resolution in multiple of days of the returned data segments or gaps. A value of 0 returns segments based on stored data records. A value larger than zero will return the minimum and maximum data time of one, two or more days. Consecutive segments will be merged if end and start time are within the tolerance.

Options (request file and data download)

-o, --output-file FILE

Output file for received data (default: -). The file name is used as a prefix with the extension added based on the record type (MSEED, RAW, ANY, META, HELI). Multiple files are created if mixed data types are received. For ‘ANY’ records the file name may contain the following format controls: %Y - year, %j - day of year, %H - hour, %M - minute, %S - second, %F - format.

-t, --temp-file FILE

Use temporary file to store data. On success move to output-file.

--rt

Enable real time mode.

--ooo

Request data in order of transmission time instead of sampling time.

--out-of-order

Identical to --ooo.

-D, --heli

Request down-sampled data (1Hz). The server will taper, bandpass filter and re-sample the data.

--itaper SECONDS

Timespan in SECONDS for the one-sided cosine taper.

--bandpass RANGE

Corner frequency RANGE of the bandpass filter, e.g., 1.0:4.0.

-M, --meta

Request record meta data only.

-v, --version VERSION

Request a specific format version. Currently only supported in meta requests.