win32conv

A modern, refactored C implementation of WIN/WIN32 seismic data conversion tools. This project provides a clean-room implementation to ensure license clarity and improved portability while maintaining compatibility with the original WIN format.

License and Attribution

This project provides a modern implementation for handling WIN/WIN32 formats. Some components are inspired by win32tools and fwin, but have been extensively refactored or rewritten to ensure code quality and license clarity under GPL-2.0.

Credits

• WIN System: The original WIN System and its specifications were developed by the Earthquake Research Institute, The University of Tokyo and other contributing institutions.
• WIN32 Tools Package (NIED): The functional design, command-line interfaces, and overall utility of the conversion tools in this project (such as win2sc and win2h5) are heavily inspired by the original win32tools (e.g., win2sac_32) developed and maintained by the National Research Institute for Earth Science and Disaster Resilience (NIED). We deeply respect their pioneering work in providing tools for operating WIN32 format waveform data.
• Decoding Logic (fwin): The core decoding algorithms are based on the fwin library by Takuto Maeda (GitHub Repository). Original fwin is licensed under the MIT License.
• Porting, HDF5, and Physical Conversion: Pure C implementation by K. Nishida (Earthquake Research Institute, The University of Tokyo), including a complete clean-room reimplementation of channel table parsing and metadata handling logic.

License

This software is distributed under the GNU General Public License v2 (GPLv2), following the original WIN System license. By providing a clean C implementation based only on the core WIN specifications and the MIT-licensed fwin logic, we aim to ensure a transparent and consistent licensing model. See the LICENSE file for details.

Prerequisites

• CMake (3.10 or higher)
• HDF5 (C and High-Level components)
• OpenMP (Optional, for parallelized processing in win2h5)

You can build the project by simply running make in the top directory.

make

Alternatively, you can use CMake directly:

mkdir build && cd build
cmake ..
cmake --build .

Note for macOS Users (OpenMP)

The default clang on macOS does not support OpenMP. To enable OpenMP, install gcc via Homebrew and specify the compiler:

# Example with GCC 15
mkdir build && cd build
CC=/opt/homebrew/bin/gcc-15 cmake ..
cmake --build .

Performance Tuning (OpenMP)

Both win2sc and win2h5 are parallelized across channels using OpenMP.

• win2sc: Parallelizes both data transformation and SAC file writing.
• win2h5: Parallelizes data transformation. Writing to the HDF5 file is performed sequentially for stability.

You can control the number of threads via the OMP_NUM_THREADS environment variable.

# Run with 4 threads
export OMP_NUM_THREADS=4
./build/win2sc -c channels.tbl ...

If not specified, it defaults to using all available CPU cores.

Memory Optimization (Batch Processing)

For environments with limited memory or when processing extremely large observation networks (thousands of channels), use the batch versions of the tools:

• win2sc_batch
• win2h5_batch

These tools process channels in blocks (using the -b option), drastically reducing the peak memory footprint while maintaining the same performance benefits of OpenMP.

Tools

win2sc / win2sc_batch

Converts WIN files to SAC files. Output files are named as {STATION}.{COMPONENT}.SAC. win2sc_batch is optimized for memory-constrained environments.

win2h5 / win2h5_batch

Converts WIN files to HDF5 format (.h5). Supports data compression and efficient storage for large datasets. win2h5_batch adds memory-efficient looping logic for large channel sets.

Reading HDF5 in Python (ObsPy)

You can use the provided Python script to load the generated HDF5 files into an ObsPy Stream:

# Basic usage
./scripts/read_winh5.py data/20260580000.h5

# Plotting
./scripts/read_winh5.py data/20260580000.h5 --plot

The script automatically maps HDF5 attributes (station, channel, timing, sensitivity) to ObsPy's Trace.stats.

Preparing F-net Channel Files

Hi-net format channel files provided by NIED for F-net data often contain dummy values for the corner period (typically 20.0s) and damping constant. To correctly perform deconvolution or response compensation (using the -s option in win2sc or win2h5), you must update these values to reflect the actual response of the VBB seismometers (e.g., STS-1 or STS-2).

Use the provided scripts/fnet_ch_conv.py script to automatically update these values based on the sensitivity:

# Correct dummy values in the F-net channel table
./scripts/fnet_ch_conv.py original_channels.tbl > corrected_channels.tbl

The script infers whether the sensor is an STS-1 (360s) or STS-2 (120s) based on its sensitivity and updates the natural period and damping constant accordingly.

Options

The following options are supported by both win2sc and win2h5 unless otherwise noted:

• -c file: (Required) Path to the channel definition file (Hi-net format).
• -d dir: Output directory. Defaults to the current directory (.).
• -n channel: Process only specified channels. Accepts a single ID (e.g., 4ce1), a comma-separated list, or a text file containing IDs. Default is ALL.
• -u: Output time in UTC. By default, the tool assumes WIN data is in JST and preserves it. See Timezone Handling for details.
• -s: Pseudo STS-2 conversion / Deconvolution.
  • For velocity channels, applies standard inverse STS-2 filter.
  • New: For Tiltmeter (rad) and Acceleration (m/s/s) channels, it automatically applies a physical conversion:
    1. Tilt: Converts Radian to Acceleration using gravity.
    2. Response: Applies STS-2 transfer function to convert Acceleration to Velocity.
    3. Standardization: Scales data to physical values (nm/s) and updates metadata.
  • Citation: Maeda, T., K. Obara, T. Furumura, and T. Saito (2011), Interference of long-period seismic wavefield observed by dense Hi-net array in Japan, J. Geophys. Res., 116, B10303.
• -r factor: Decimate data by an integer factor (e.g., -r 2 halves the sampling rate).
• -f srate: Resample data to a target sampling rate (Hz) by decimation.
• -l file: Apply logger noise reduction using the specified coefficients file.
  • Citation: Takagi, R., Nishida, K., Aoki, Y., Maeda, T., Masuda, K., Takeo, M., et al. (2015), A Single Bit Matters: Coherent Noise of Seismic Data Loggers, Seismological Research Letters, 86(3), 901–907.
• -a file: Apply component azimuth corrections (cmpaz) using the specified list.
• -z [s]: (win2h5 only) Enable HDF5 compression.
  • Default: Shuffle filter + Deflate (GZIP).
  • -z s: Uses SZIP compression.
• -b size: (Batch versions only) Set the number of channels to process per batch (default: 100). Reducing this value further lowers memory usage.

Timezone Handling

WIN format data is typically recorded in Japanese Standard Time (JST).

• Default Behavior: The tools preserve the JST timestamps found in the WIN files. This behavior is consistent and independent of the execution environment's local timezone settings (internal calculations use GMT/UTC to avoid system-dependent offsets).
• UTC Conversion (-u option): When the -u flag is provided, the software shifts the time by -9 hours to convert JST to UTC. In win2sc, this updates the SAC header fields (nzyear, nzhour, etc.) accordingly.

Data structure of HDF5

    data/+sta1/+ sta_hdr
         |     |    string: kstnm, kevnm
         |     |    float:   stla, stlo, stel
         |     +ch1/+ch1ch_hdr:
         |     |    |       string:kcmpnm, sunit
         |     |    |       flaot:cmpaz, smpinc
         |     |    |       time_t:tm0 => time_t
         |     |    |       float delta
         |     |    |       int: npts, sr
         |     |    +sgram (Dataset)
         |     +ch2
         |     +ch3
         +sta2
         |
       +sta3

Citation

If you use win32conv in your research, please cite it as follows:

APA: Nishida, K. (2026). win32conv: A modern C implementation of WIN/WIN32 seismic data conversion tools (Version 1.0.0). [Software]. Available at https://github.com/qnishida/win32conv. DOI: 10.5281/zenodo.19879657

BibTeX:

@software{nishida_win32conv_2026,
  author = {Nishida, Kiwamu},
  title = {win32conv: A modern C implementation of WIN/WIN32 seismic data conversion tools},
  version = {1.0.0},
  doi = {10.5281/zenodo.19879657},
  url = {[https://github.com/qnishida/win32conv](https://github.com/qnishida/win32conv)},
  date = {2026-04-22}
}