mth5.io.zen.z3d_header

• Tools for reading and writing files for Zen and processing software

• Tools for copying data from SD cards

• Tools for copying schedules to SD cards

Created on Tue Jun 11 10:53:23 2013 Updated August 2020 (JP)

copyright:

Jared Peacock (jpeacock@usgs.gov)

license:

MIT

Classes

Z3DHeader

Read header information from a Z3D file and make each metadata entry an attribute.

Module Contents

class mth5.io.zen.z3d_header.Z3DHeader(fn: str | pathlib.Path | None = None, fid: BinaryIO | None = None, **kwargs: Any)

Read header information from a Z3D file and make each metadata entry an attribute.

Parameters:

• fn (str or pathlib.Path, optional) – Full path to Z3D file.

• fid (BinaryIO, optional) – File object (e.g., open(Z3Dfile, ‘rb’)).

• **kwargs (dict) – Additional keyword arguments to set as attributes.

_header_len

Length of header in bits (512).

Type:

int

ad_gain

Gain of channel.

Type:

float or None

ad_rate

Sampling rate in Hz.

Type:

float or None

alt

Altitude of the station (not reliable).

Type:

float or None

attenchannelsmask

Attenuation channels mask.

Type:

str or None

box_number

ZEN box number.

Type:

float or None

box_serial

ZEN box serial number.

Type:

str or None

channel

Channel number of the file.

Type:

float or None

channelserial

Serial number of the channel board.

Type:

str or None

ch_factor

Channel factor (default 9.536743164062e-10).

Type:

float

channelgain

Channel gain (default 1.0).

Type:

float

duty

Duty cycle of the transmitter.

Type:

float or None

fid

File object.

Type:

BinaryIO or None

fn

Full path to Z3D file.

Type:

str or pathlib.Path or None

fpga_buildnum

Build number of one of the boards.

Type:

float or None

gpsweek

GPS week (default 1740).

Type:

int

header_str

Full header string.

Type:

bytes or None

lat

Latitude of station in degrees.

Type:

float or None

logterminal

Log terminal setting.

Type:

str or None

long

Longitude of the station in degrees.

Type:

float or None

main_hex_buildnum

Build number of the ZEN box in hexadecimal.

Type:

float or None

numsats

Number of GPS satellites.

Type:

float or None

old_version

Whether this is an old version Z3D file (default False).

Type:

bool

period

Period of the transmitter.

Type:

float or None

tx_duty

Transmitter duty cycle.

Type:

float or None

tx_freq

Transmitter frequency.

Type:

float or None

version

Version of the firmware.

Type:

float or None

Examples

>>> from mth5.io.zen import Z3DHeader
>>> Z3Dfn = r"/home/mt/mt01/mt01_20150522_080000_256_EX.Z3D"
>>> header_obj = Z3DHeader(fn=Z3Dfn)
>>> header_obj.read_header()

logger

fn: str | pathlib.Path | None = None

fid: BinaryIO | None = None

header_str: bytes | None = None

ad_gain: float | None = None

ad_rate: float | None = None

alt: float | None = None

attenchannelsmask: str | None = None

box_number: float | None = None

box_serial: str | None = None

channel: float | None = None

channelserial: str | None = None

duty: float | None = None

fpga_buildnum: float | None = None

gpsweek: int = 1740

lat: float | None = None

logterminal: str | None = None

long: float | None = None

main_hex_buildnum: float | None = None

numsats: float | None = None

period: float | None = None

tx_duty: float | None = None

tx_freq: float | None = None

version: float | None = None

old_version: bool = False

ch_factor: float = 9.536743164062e-10

channelgain: float = 1.0

property data_logger: str

Data logger name as ZEN{box_number}.

Returns:

Data logger name formatted as ‘ZEN’ followed by zero-padded box number.

Return type:

str

Raises:

TypeError – If box_number is None or cannot be converted to int.

read_header(fn: str | pathlib.Path | None = None, fid: BinaryIO | None = None) → None

Read the header information into appropriate attributes.

Parses the header information from a Z3D file and populates the object’s attributes with the extracted values. Supports both modern and legacy Z3D file formats.

Parameters:

• fn (str or pathlib.Path, optional) – Full path to Z3D file. If None, uses the instance’s fn attribute.

• fid (BinaryIO, optional) – File object (e.g., open(Z3Dfile, ‘rb’)). If None, uses the instance’s fid attribute or opens the file specified by fn.

Raises:

UnicodeDecodeError – If header bytes cannot be decoded as text.

Notes

This method reads the first 512 bytes of the Z3D file as the header. It supports two formats:

1. Modern format: key=value pairs separated by newlines

2. Legacy format: comma-separated key:value pairs

The method automatically detects legacy format and sets old_version=True.

Coordinate values (lat/long) are automatically converted from radians to degrees, with validation to ensure they fall within valid ranges.

Examples

>>> header_obj = Z3DHeader()
>>> header_obj.read_header("/path/to/file.Z3D")

>>> with open("/path/to/file.Z3D", "rb") as fid:
...     header_obj.read_header(fid=fid)

convert_value(key_string: str, value_string: str) → float | str

Convert the value to the appropriate units given the key.

Converts string values to appropriate types based on the key name. Special handling is provided for latitude and longitude values, which are converted from radians to degrees with validation.

Parameters:

• key_string (str) – The metadata key name, used to determine conversion type.

• value_string (str) – The string value to convert.

Returns:

Converted value. Returns float for numeric values, str for non-numeric values. Latitude and longitude values are converted from radians to degrees.

Return type:

float or str

Notes

• Attempts to convert all values to float first

• If conversion fails, returns original string

• For keys containing ‘lat’, ‘lon’, or ‘long’: - Converts from radians to degrees using np.rad2deg - Validates latitude range (±90°), sets to 0.0 if invalid - Validates longitude range (±180°), sets to 0.0 if invalid

Examples

>>> header = Z3DHeader()
>>> header.convert_value("version", "4147")
4147.0
>>> header.convert_value("lat", "0.706816081")  # radians
40.49757833327694  # degrees
>>> header.convert_value("channelserial", "0xD474777C")
'0xD474777C'