🚗 VTX - Vehicle Tracking Xcorr

Vehicle Tracking Xcorr is a Python-based framework to apply Multichannel Analysis of Surface Waves (MASW) to surface waves generated by vehicles (cars or trains) recorded with Distributed Acoustic Sensing (DAS) systems along roads or railways. The workflow automates the end-to-end process — from signal tracking to cross-correlation and interpretation — allowing efficient and reproducible seismic data analysis on DAS infrastructure.

---

Overview

The program is structured into three independent processing stages, each controlled through configuration files and launched via a single supervising script, main.py.

1. Tracking Process (tracking_process.py) Detects and tracks surface-wave events generated by moving vehicles along the DAS cable.

2. Cross-Correlation Process (xcorr_process.py) Computes cross-correlations between selected traces or segments to derive virtual shot gathers and enhance coherent wavefields.

3. Interpretation Process (interpretation_process.py) Performs dispersion analysis, visualization, and interpretation of the correlated wavefield to extract MASW-type information such as phase velocity and dispersion curves.

Each stage can be activated or deactivated in the configuration file, depending on your analysis needs.

---

Project Structure

DAS-VTX/
├── main.py                     # Supervises and executes the full workflow
├── config_train.py              # Configuration for train-based DAS data
├── config_cars.py            # Configuration for car-based DAS data
│
├── tracking_process.py          # Vehicle detection and tracking module
├── xcorr_process.py             # Cross-correlation computation module
├── interpretation_process.py    # Dispersion and interpretation module
│
├── data_loader.py               # Handles DAS data import and preprocessing
├── func_data_imports.py         # Helper functions for data management
├── utils.py                     # Utility functions (I/O, formatting, etc.)
│
├── SW_class.py                  # Class for surface wave processing
├── Disp_class.py                # Class for dispersion analysis
├── Tracker_class.py             # Class for vehicle tracking
├── VSG_class.py                 # Class for virtual shot gather handling
│
├── out_test/                    # Example output directory
├── test.log                     # Example log file generated during run

---

Running the Code

0. Configure the workflow

Setup a folder containing all DAS-VTX scripts. Addapt the import function in the helper func_data_imports.py depending on interrogation-unit version and source files.

1. Configure the Run

Edit one of the configuration files:

• config_cars.py → for car-related experiments
• config_trains.py → for train-related experiments

Set:

• the wished configuration file in main.py

2. Launch the Workflow

Run:

python main.py
or
./launch_main.sh

main.py reads the selected configuration file, launches the activated processes in sequence, and logs the progress in test.log.

3. Check Outputs

Processed data and results are written to the output folder defined in the config file (e.g. outputs/).

---

Outputs

The output directory is organized into the following subfolders:

detects/

Files are stored in NumPy .npy format and are classified by date and time according to the corresponding input DAS data file. Contains detection results, stored in form a surface wave window object. It includes tracked trajectories (attributes veh_state_t and veh_state_x), and extracted surface-wave data windows (attributes x_axis, t_axis and data).

VSGs/

Contains Virtual Shot Gathers (VSGs). Files are stored in NumPy .npz format. The archive includes multiple arrays:

• The correlation parameters (keyword parameters)
• The stacked VSG (keyword stack),in form of a VSG object, which attributes include the axis (t_axis and x_axis) and the data (XCF_out)
• Metadata describing the SNR evolution as a function of the number of stacked individual VSGs (keyword SNR and vsg_times)

DISPs/

Contains dispersion spectra derived from stacked VSGs. Files are stored in NumPy .npz format. The archive includes multiple arrays:

• The analysis parameters (keyword parameters)
• The stacked dispersion spectrum (keyword disp)
• Frequency array (keyword freqs)
• Phase-velocity array (keyword vels)
• The mask used in the inter-channel distance dependant masking (keyword mask)

FIGs/

Contains diagnostic figures generated during processing, including:

• Dispersion spectra
• SNR evolution versus number of stacked VSGs
• Stacked VSG visualizations

All processing steps and execution details are recorded in a timestamped log file located in the main output directory.

---

Dependencies

numpy
scipy
matplotlib
obspy
h5py
pandas
tqdm

DAS Processing Parameters

The following table summarize the input parameters and give examples for two types of infrastrctures: a fiber optic cable running along a road with frequent car signals, and along a railway. It includes also short descriptions for each parameter

Workflow control and execution. Processing steps can be activated as a standalone or part of the entire workflow

Parameter	Example 1 - Along road	Example 2 - Along railways	Description
RUN_TRACKING	True or False	True or False	Enables automated vehicle detection and tracking along the fiber
RUN_XCORR	True or False	True or False	Activates cross-correlation and VSG retrieval (including stacking)
RUN_INTERPRETATION	True or False	True or False	Enables dispersion analysis and post-processing of stacked VSGs
n_processes	10	10	int, number of parallel CPU processes used for computation

Tracking geometry and temporal selection

tracking_sections	(1750, 2100, 2450) m	(15200, 15550, 15900) m	Fiber section used for detection and tracking (start, pivot, end)
tracking_start_date	2023-04-04	2025-04-01	Start date of tracking period
tracking_end_date	2023-04-20	2025-06-30	End date of tracking period
start_hour	2	2	Start hour (UTC) to restrict processing to periods with traffic
end_hour	22	22	End hour (UTC)
tracking_data_decimation_factor	10	5	Temporal decimation applied before tracking to reduce data volume while preserving kinematics

DAS acquisition and geometry

dx	9.6 m	9.6 m	Inter-channel spacing along the fiber

Preprocessing prior to tracking

smoothing	(21, 15)	(21, 15)	Time and space smoothing windows
FK.slope_lo	3.6/70 m/s	—	Lower apparent velocity bound for FK filtering
FK.slope_hi	3.6/20 m/s	—	Upper apparent velocity bound for FK filtering
BP.freq_lo	0.2 Hz	0.2 Hz	Lower band-pass corner for surface waves
BP.freq_hi	1.0 Hz	1.0 Hz	Upper band-pass corner
SQRT	True	True	Square-root amplitude scaling to reduce dominance of strong events
spatial_av_vel	50/3.6 m/s	70/3.6 m/s	Reference velocity used to align signals before spatial averaging
av_win	5	5	Spatial averaging window (channels)
oversampling_factor	5	5	Temporal oversampling to improve detection and alignment

Detection and Kalman-filter tracking

minprominence	0.3	0.3	Minimum prominence for peak detection
minseparation	1	1	Minimum separation between detections
prominenceWindow	600	600	Window for prominence estimation
sigma_a	0.1	0.1	Process noise in Kalman filter (trajectory smoothness)
R	5	10	Measurement noise covariance
nx_init	3	3	Number of detections required to initialize a track
reverse_amp	True	True	Detects vehicles as amplitude minima or maxima

Trajectory preselection and quality control

max_adjacent_nan	50	50	Maximum number of consecutive missing samples
max_total_nan	0.2	0.2	Maximum fraction of missing samples
average_speed	30–60 km/h	20–100 km/h	Accepted average velocity range
curve_break	(5, 1.8, 0.1, 25)	(5, 1.8, 0.1, 25)	Rejects trajectories with strong curvature breaks
speed_fluctuations	(1.5, 0.1)	(1.5, 0.1)	Rejects trajectories with excessive speed variability

Surface-wave window extraction

wlen_sw	80 s	80 s	Temporal length of extracted SW windows
length_sw	740 m	740 m	Spatial aperture of SW windows
taper	4 s	4 s	Apodization length
temporal_spacing	wlen_sw - taper	wlen_sw - taper	Minimum spacing between successive detection windows

Cross-correlation and VSG construction

wlen	2.3 s	5.8 s	Correlation window length
overlap	0.0	0.0	Overlap between correlation windows
delta_t	0.2 s	0.5 s	At a pivot channel, time shift between the correlation window and the estimated trajectory
time_window_to_xcorr	3 s	6 s	If overlaped windows, time window in which correlation windowds are defined
norm	True	True	Temporal normalization before correlation
norm_amp	True	True	Amplitude normalization
sw_whiten	True	True	Spectral whitening of SW windows
freq_lo	0.5 Hz	0.5 Hz	Lower frequency bound for the analysis of surface waves
freq_hi	40 Hz	40 Hz	Upper frequency bound

Dispersion analysis and post-processing

coherence_enhancing	True	True	Enhances coherent surface-wave energy
slw_list	1/250–1/1200 s/m	1/250–1/1200 s/m	Slowness grid for coherence analysis
freqs	0.7–25 Hz	0.7–25 Hz	Frequency grid for dispersion imaging
vels	19–2100 m/s	19–2100 m/s	Phase-velocity grid
stack_norm	False	False	Normalization of stacked VSGs
offsets_to_keep	both	both	Causal and acausal offsets
lags_to_keep	causal	causal	Restriction to causal lags

Dispersion masking (aperture-dependent)

disp_masking	True	True	Activates recursive aperture-dependent dispersion masking
max_cut_dist	500 m	500 m	Maximum inter-channel distance
min_cut_dist	150 m	150 m	Minimum inter-channel distance
step_factor	4	4	Aperture reduction step (multiple of dx)