# M2HATS Typhoon wind-field data

## Purpose of this document

This document explains how to understand, read, and display the public **Typhoon wind-field products derived from M2HATS REAL aerosol lidar data**.

It is intended for:

- researchers;
- students;
- collaborators;
- programmers;
- and AI-assisted analysis workflows.

The emphasis is practical:

- What is stored in a Typhoon netCDF file?
- What do `vx`, `vy`, `x`, `y`, and `indices` mean?
- How is the Cartesian grid defined?
- What time does a file represent?
- Which two REAL scans produced the wind field?
- What do `FULL`, `MEAN`, `NONE`, `REF`, and `initREF` mean?
- What is the Sasano scan-motion correction?
- How can a user display an existing wind field without installing or running Typhoon?

This document is about **using existing M2HATS Typhoon output files**.

It is not an installation guide for the reference Typhoon/CUDA software.

For a scientific overview of the Typhoon method itself, see:

```text
Typhoon_overview.md
```

For the REAL instrument and aerosol-image processing, see:

```text
REAL_instrument_description.md
REAL_bscan_data_file_format.md
REAL_bscan_signal_processing.md
```

---

# 1. Quick mental model

A public M2HATS Typhoon netCDF file represents a two-component horizontal vector flow field estimated from a pair of sequential REAL scans.

Conceptually:

```text
REAL scan 0
        +
REAL scan 1
        |
        v
REAL preprocessing and Cartesian gridding
        |
        v
Typhoon dense optical-flow estimation
        |
        v
optional iterative scan-motion correction
        |
        v
netCDF file containing valid x, y, vx, vy vectors
```

The important output variables are:

```text
x     West-East coordinate, East positive       meters
y     South-North coordinate, North positive    meters

vx    West-East velocity component, East positive       m/s
vy    South-North velocity component, North positive    m/s
```

The file stores only locations considered valid for the retrieval.

A user does **not** need the proprietary/reference Typhoon software merely to read or analyze these already-computed wind fields.

---

# 2. Public Typhoon data location

The existing public archive is:

```text
https://lidar.csuchico.edu/m2hats/typhoon_nc/
```

The archive currently contains compressed collections with names such as:

```text
M2HATS_REAL+typhoon_alphaExperiments.gz

M2HATS_REAL+typhoon_alphaExperiments_2.tar.gz

M2HATS_REAL+typhoon_stationnaryCases_FULL_alpha0.004.tar.gz

M2HATS_REAL+typhoon_stationnaryCases_FULL_alpha0.005.tar.gz

M2HATS_REAL+typhoon_stationnaryCases_MEAN_alpha0.004.tar.gz

M2HATS_REAL+typhoon_stationnaryCases_NONE_alpha0.004.tar.gz

M2HATS_REAL+typhoon_stationnaryCases_REF_alpha0.004.tar.gz

M2HATS_REAL+typhoon_stationnaryCases_initREF_alpha0.001.tar.gz

M2HATS_REAL+typhoon_stationnaryCases_initREF_alpha0.004.tar.gz
```

The word:

```text
stationnary
```

is misspelled in the historical archive filenames and should be treated as meaning:

```text
stationary
```

These archives were produced during M2HATS Typhoon processing and sensitivity experiments.

They should not be assumed to represent one single homogeneous final product without checking the processing metadata preserved inside each netCDF file.

---

# 3. Representative files examined for this documentation

The following five files for the same REAL scan pair were inspected directly:

```text
REAL.20230803_173858_OFseq21_FULL.nc
REAL.20230803_173858_OFseq20_MEAN.nc
REAL.20230803_173858_OFseq21_NONE.nc
REAL.20230803_173858_OFseq20_REF.nc
REAL.20230803_173858_OFseq0_initREF.nc
```

All five correspond to:

```text
scan0:
202308/20230803/REAL.20230803_173858.bscan

scan1:
202308/20230803/REAL.20230803_173916.bscan
```

All five have the same stored reference time:

```text
2023-08-03 17:39:08.397 UTC
```

and the same nominal Cartesian grid definition:

```text
grid resolution:  8 m
rows:             438
columns:          313
x origin:         500 m
y origin:        -1750 m
```

The output schema is consistent across these representative cases.

---

# 4. NetCDF global attributes

A representative M2HATS Typhoon file contains global attributes similar to:

```text
version      = 2025
description  = Motion estimated by optical flow on a Cartesian grid.
coordinate   = Cartesian
scantype     = PPI

gridRes      = 8
dimRow       = 438
dimCol       = 313
xOrigin      = 500
yOrigin      = -1750
```

The spatial convention is:

```text
+x = east
+y = north
```

The coordinate origin is the REAL lidar.

Thus:

```text
x = 1000 m
y = -500 m
```

means a point approximately:

```text
1000 m east
500 m south
```

of REAL.

---

# 5. Main variables

The principal data variables are:

| Variable | Units | Meaning |
|---|---|---|
| `time` | seconds since 1970-01-01 00:00:00 | Reference datetime for the vector field |
| `indices` | none | Zero-based location in the flattened full Cartesian grid |
| `x` | m | West-East coordinate; east positive |
| `y` | m | South-North coordinate; north positive |
| `vx` | m/s | West-East velocity component; east positive |
| `vy` | m/s | South-North velocity component; north positive |

The files also contain optimization diagnostic variables described later.

---

# 6. Sparse storage of valid vectors

The Typhoon file does **not** normally store a full `438 x 313` array of velocity values with missing values everywhere else.

Instead, it stores only valid vector locations.

For the representative `FULL` file:

```text
full nominal grid:
438 × 313 = 137,094 possible cells

stored valid vectors:
26,931
```

The variables:

```text
x
y
vx
vy
indices
```

all therefore have length:

```text
26,931
```

for that file.

Other processing configurations have slightly different numbers of valid vectors.

This storage scheme keeps the output compact and makes the valid-data domain explicit.

---

# 7. Meaning of `indices`

The variable:

```text
indices
```

is described in the netCDF metadata as:

```text
global index in a 1D (flattened) array[dimRow x dimCol]
```

For the M2HATS files examined here, it is a **zero-based row-major index**.

Let:

```text
idx = indices
ncol = dimCol
```

Then:

```text
row = floor(idx / ncol)
col = idx mod ncol
```

The physical coordinates are:

```text
x = xOrigin + col * gridRes
y = yOrigin + row * gridRes
```

For the representative files, this reconstruction reproduces the stored `x` and `y` coordinates exactly.

---

# 8. Nominal Cartesian grid

For the representative case:

```text
gridRes  = 8 m
dimRow   = 438
dimCol   = 313
xOrigin  = 500 m
yOrigin  = -1750 m
```

The full nominal grid therefore has:

```text
x = 500, 508, 516, ... , 2996 m

y = -1750, -1742, -1734, ... , 1746 m
```

The sequence metadata describes approximate requested bounds of:

```text
west:    500 m
east:   3000 m
south: -1750 m
north:  1750 m
```

Because the grid spacing is 8 m, the final grid-center coordinates do not land exactly on the east and north requested bounds.

---

# 9. Valid-vector domains differ among runs

Even when two Typhoon files have the same nominal Cartesian grid, they do not necessarily contain valid vectors at exactly the same grid cells.

For the representative scan pair:

| Case | Valid vectors |
|---|---:|
| `FULL` | 26,931 |
| `MEAN` | 27,889 |
| `NONE` | 26,706 |
| `REF` | 27,479 |
| `initREF` | 26,851 |

Therefore:

> **Do not compare two Typhoon fields element-by-element merely because their arrays have similar sizes.**

When comparing two processing cases, match vectors by:

```text
indices
```

or by:

```text
x, y
```

coordinates.

---

# 10. Time variable

The netCDF variable:

```text
time
```

has units:

```text
seconds since 1970-01-01 00:00:00
```

and is described as:

```text
reference datetime
```

For the representative files:

```text
time = 2023-08-03 17:39:08.397 UTC
```

The netCDF file also records the two source REAL BSCAN files.

This provides strong provenance:

```text
source scans
        +
Typhoon reference time
        +
wind vectors
```

are preserved together.

## Important caution

Do not infer the exact rule used to calculate the stored reference datetime solely from the BSCAN filenames.

The netCDF `time` value should be treated as the authoritative reference datetime for the wind field unless the Typhoon processing source is being examined explicitly.

---

# 11. Source REAL scans

The netCDF group:

```text
user_info
```

contains attributes:

```text
scan0
scan1
```

For the representative file:

```text
scan0 =
202308/20230803/REAL.20230803_173858.bscan

scan1 =
202308/20230803/REAL.20230803_173916.bscan
```

This makes it possible to trace a wind retrieval back to the original REAL measurements.

The relative paths correspond to the public raw REAL BSCAN archive under:

```text
https://lidar.csuchico.edu/M2HATS-data/REAL/bscans/
```

---

# 12. Processing provenance in `user_info`

The `user_info` group also preserves important processing provenance.

Representative attributes include:

```text
source
created_on
toolbox_version
sequence
```

The `sequence` attribute is a serialized processing-configuration dictionary.

For the representative `FULL alpha0.004` file, important values include:

```text
id                    = 21

lowpass_length        = 7
highpass_length       = 333

grid_cell_width       = 8.0 m

west_bound            = 500 m
east_bound            = 3000 m
south_bound           = -1750 m
north_bound           = 1750 m

sasano_correction     = FULL

snr_halfwidth         = 128

valid_mask            = bin_median
mask threshold        = 3.0
mask bin size         = 100 m
mask margin           = 300 m

num_moment            = 10
num_decomposed        = 8
num_estimated         = 8
num_initialized       = 8
num_pyramid_step      = 1

alpha_regularization  = 0.004
```

This metadata is extremely valuable.

Users should preserve it when copying or reformatting Typhoon products.

---

# 13. `alpha` and regularization experiments

Archive names such as:

```text
alpha0.001
alpha0.004
alpha0.005
```

refer to values of Typhoon's optical-flow regularization parameter:

```text
alpha_regularization
```

The regularization parameter helps control the balance between:

- fitting image motion;
- and enforcing spatial smoothness / regularity in the retrieved flow field.

Different `alpha` values therefore produce somewhat different flow fields.

The public archive contains sensitivity experiments using multiple values.

Do not assume that files with different alpha values are numerically interchangeable.

For examples in this document, `alpha = 0.004` is used because representative files were available and inspected directly.

This should not be interpreted as a claim that every `alpha0.004` archive is the uniquely preferred or final M2HATS product.

---

# 14. Why scan-motion correction is needed

A scanning lidar does not acquire an entire PPI image at one instant.

The beam moves through azimuth while the atmosphere continues to move.

Thus an aerosol feature can move appreciably during the time required to complete one scan.

The image therefore contains **scan-time distortion**.

This problem was described explicitly by:

> Sasano et al. (1982)

for wind retrieval from scanning-lidar aerosol patterns.

The basic issue is:

```text
true aerosol distribution
        +
finite scan speed
        +
aerosol motion during the scan
        |
        v
observed spatial pattern is distorted
```

If the distortion is ignored, part of the apparent displacement between two lidar scans can result from acquisition timing rather than from the desired instantaneous displacement field.

---

# 15. Sasano et al. (1982)

The foundational paper is:

> Sasano, Y., H. Hirohara, T. Yamasaki, H. Shimizu, N. Takeuchi, and T. Kawamura (1982), "Horizontal Wind Vector Determination from the Displacement of Aerosol Distribution Patterns Observed by a Scanning Lidar," *Journal of Applied Meteorology*, **21**, 1516-1523.

DOI:

```text
https://doi.org/10.1175/1520-0450(1982)021<1516:HWVDFT>2.0.CO;2
```

The paper recognized that finite scanning speed causes a moving aerosol distribution to appear spatially distorted.

Its iterative procedure can be summarized as:

```text
1. Estimate an initial wind vector from two observed scans.

2. Use that wind estimate and the known scan timing
   to infer approximate instantaneous aerosol patterns.

3. Re-estimate the wind from the corrected patterns.

4. Repeat until the wind estimate converges.
```

Sasano et al. used a pattern-matching / two-dimensional cross-correlation method and formulated the original correction using an area-wide wind vector.

The correction was referenced to a standard time associated with the scan geometry.

This is the conceptual origin of the scan-motion correction used in the REAL/Typhoon processing chain.

---

# 16. How Typhoon extends the Sasano idea

The Typhoon workflow uses the **Sasano correction principle** but combines it with a much more spatially detailed motion estimator.

Sasano et al. originally estimated displacement primarily through area-based spatial correlation.

Typhoon instead estimates a dense two-component motion field.

Conceptually, the modern REAL/Typhoon workflow is:

```text
estimate dense motion field with Typhoon
        |
        v
use wind estimate to correct scan-time distortion
        |
        v
re-grid corrected aerosol data
        |
        v
estimate Typhoon motion again
        |
        v
repeat as required
```

The 2015 REAL/Typhoon validation paper explicitly describes this iterative correction as following Sasano et al. (1982).

---

# 17. Sasano correction modes in the M2HATS archive

The M2HATS processing experiments include several ways of handling scan-motion correction.

## `NONE`

```text
sasano_correction = NONE
```

No Sasano scan-motion correction is applied.

For the representative file:

```text
Typhoon estimation iterations = 1
```

This case is useful for evaluating what the correction changes.

---

## `MEAN`

```text
sasano_correction = MEAN
```

The scan-motion correction uses a **spatially averaged wind vector** rather than the full spatially varying Typhoon field.

This is conceptually closer to the original uniform-wind correction described by Sasano et al.

For the representative file:

```text
Typhoon estimation iterations = 3
```

---

## `FULL`

```text
sasano_correction = FULL
```

The correction uses the **full spatially varying Typhoon velocity field**.

This allows the scan distortion itself to vary spatially according to the retrieved flow.

For the representative file:

```text
Typhoon estimation iterations = 3
```

The inspected `FULL alpha0.004` sequence carries the comment:

```text
Same as legacy OF sequence 59 used for JTECH 2015 wavelet paper,
besides mask and domain, plus testing alpha & sasano correction
```

Thus the M2HATS configuration is directly connected to the earlier published REAL/Typhoon processing lineage.

---

## `REF`

```text
sasano_correction = REF
```

Local inspection of the M2HATS Typhoon source code on the Chico research system indicates that this mode uses an **external reference wind field**, associated with M2HATS ISFS measurements, in the scan-motion correction / initialization workflow.

For the representative `REF` file:

```text
Typhoon estimation iterations = 1
```

Because the external-reference mechanism belongs to the Typhoon processing code rather than the generic netCDF schema, users doing detailed algorithm comparisons should consult the processing source or additional project documentation.

---

# 18. `initREF` is not a separate Sasano keyword

The historical archive contains filenames labeled:

```text
initREF
```

However, the inspected `initREF` netCDF file internally stores:

```text
sasano_correction = REF
```

Its own processing comment is:

```text
REF init, no correction, lower nD&nE, no pyramid
```

Compared with the normal `REF`, `FULL`, `MEAN`, and `NONE` sensitivity cases, the representative `initREF` configuration uses:

```text
num_decomposed    = 6
num_estimated     = 6
num_initialized   = 0
num_pyramid_step  = 0
```

rather than:

```text
num_decomposed    = 8
num_estimated     = 8
num_initialized   = 8
num_pyramid_step  = 1
```

Therefore:

> **`initREF` should be treated as an experimental REF-derived processing configuration, not as a fifth value of the `sasano_correction` parameter.**

---

# 19. Comparison of representative correction cases

For the same REAL scan pair and `alpha = 0.004`:

| Archive label | Stored `sasano_correction` | Valid vectors | Estimation iterations |
|---|---|---:|---:|
| `FULL` | `FULL` | 26,931 | 3 |
| `MEAN` | `MEAN` | 27,889 | 3 |
| `NONE` | `NONE` | 26,706 | 1 |
| `REF` | `REF` | 27,479 | 1 |
| `initREF` | `REF` | 26,851 | 1 |

The different valid-vector counts show that the processing choices can change not only the velocity estimates but also the valid retrieval domain.

---

# 20. Optimization diagnostic variables

The representative netCDF files contain:

```text
return_codes
function_values
gradient_norms
model_values
regularization_values
```

These are stored over the:

```text
estim_iters
```

dimension.

Their metadata describe them as:

| Variable | Meaning |
|---|---|
| `return_codes` | Typhoon estimation return code |
| `function_values` | Total cost-function value |
| `gradient_norms` | Norm of cost-function gradient |
| `model_values` | Data/model term of the cost function |
| `regularization_values` | Regularization term of the cost function |

For the representative files examined for this document, the stored return codes are zero.

Users interested only in plotting an existing wind field normally do not need these diagnostics.

They are valuable for:

- processing provenance;
- algorithm development;
- sensitivity studies;
- debugging;
- checking convergence behavior.

The precise interpretation of nonzero return codes should be taken from the Typhoon implementation that produced the file.

---

# 21. These files do not contain the source aerosol image

The representative Typhoon netCDF files contain:

- vector coordinates;
- velocity components;
- reference time;
- source-scan filenames;
- grid metadata;
- processing configuration;
- optimizer diagnostics.

They do **not** contain the full processed REAL aerosol image used as input.

If an aerosol-backscatter background is desired for visualization, it must be obtained from:

- the original BSCAN files;
- pre-made REAL PNG products;
- or a separately processed REAL image.

---

# 22. Python: read a local Typhoon netCDF file

These Typhoon files use the netCDF4/HDF5 file format.

A simple Python reader can use `h5py`.

```python
import h5py

filename = "REAL.20230803_173858_OFseq21_FULL.nc"

with h5py.File(filename, "r") as f:

    x = f["x"][:]
    y = f["y"][:]

    vx = f["vx"][:]
    vy = f["vy"][:]

    indices = f["indices"][:]

    time_seconds = f["time"][0]

    grid_res = float(f.attrs["gridRes"][0])
    dim_row = int(f.attrs["dimRow"][0])
    dim_col = int(f.attrs["dimCol"][0])

    x_origin = float(f.attrs["xOrigin"][0])
    y_origin = float(f.attrs["yOrigin"][0])

    scan0 = f["user_info"].attrs["scan0"].decode()
    scan1 = f["user_info"].attrs["scan1"].decode()
```

---

# 23. Python: read directly from the public web server

Because an individual Typhoon netCDF file is relatively small, a convenient Python workflow is to retrieve the file into memory and open it with `h5py`.

```python
import io
import requests
import h5py

url = (
    "https://lidar.csuchico.edu/m2hats/typhoon_nc/"
    "PATH_TO_ONE_NETCDF_FILE.nc"
)

response = requests.get(url)
response.raise_for_status()

with h5py.File(io.BytesIO(response.content), "r") as f:

    x = f["x"][:]
    y = f["y"][:]

    vx = f["vx"][:]
    vy = f["vy"][:]
```

This example downloads the individual netCDF file into memory.

It does **not** require downloading an entire Typhoon archive or installing Typhoon itself.

The exact public URL of an individual netCDF file depends on how the archive has been unpacked or exposed on the web server.

---

# 24. Python: display the vector field

The simplest useful plot does not require reconstructing the full Cartesian array.

```python
import matplotlib.pyplot as plt

# Decimate arrows only for visual clarity.
step = 20

plt.figure(figsize=(9, 7))

plt.quiver(
    x[::step],
    y[::step],
    vx[::step],
    vy[::step]
)

plt.axis("equal")
plt.xlabel("East-West distance from REAL (m)")
plt.ylabel("South-North distance from REAL (m)")
plt.title("M2HATS Typhoon horizontal vector field")
plt.grid()

plt.show()
```

The arrows are decimated only for readability.

The underlying file contains many more vectors.

---

# 25. Python: reconstruct the full Cartesian arrays

Some analyses are easier if `vx` and `vy` are placed back into the complete grid.

```python
import numpy as np

row = indices // dim_col
col = indices % dim_col

VX = np.full((dim_row, dim_col), np.nan)
VY = np.full((dim_row, dim_col), np.nan)

VX[row, col] = vx
VY[row, col] = vy

X = x_origin + np.arange(dim_col) * grid_res
Y = y_origin + np.arange(dim_row) * grid_res
```

Now:

```text
VX[row, col]
VY[row, col]
```

represent the full rectangular Cartesian grid, with `NaN` at locations where no valid vector was stored.

---

# 26. Python: verify the stored coordinates

The stored coordinates can be reconstructed from `indices`.

```python
x_check = x_origin + col * grid_res
y_check = y_origin + row * grid_res

print(np.max(np.abs(x - x_check)))
print(np.max(np.abs(y - y_check)))
```

For the representative files inspected for this documentation, both maximum differences are:

```text
0
```

within the stored numerical precision.

---

# 27. MATLAB: download and read one Typhoon netCDF file

Because these are netCDF4/HDF5 files served from an ordinary HTTPS server, the most robust simple MATLAB workflow is to download the **individual** file to a temporary local filename and then use MATLAB's netCDF functions.

```matlab
url = ['https://lidar.csuchico.edu/m2hats/typhoon_nc/' ...
       'PATH_TO_ONE_NETCDF_FILE.nc'];

tmp = [tempname '.nc'];

websave(tmp,url);

x  = ncread(tmp,'x');
y  = ncread(tmp,'y');

vx = ncread(tmp,'vx');
vy = ncread(tmp,'vy');

indices = ncread(tmp,'indices');

time_seconds = ncread(tmp,'time');

delete(tmp);
```

This transfers only the selected Typhoon file.

It does not require downloading a multi-hundred-megabyte archive if the desired individual netCDF file is exposed directly on the server.

---

# 28. MATLAB: display the vector field

A simple quiver plot is:

```matlab
step = 20;

figure

quiver( ...
    x(1:step:end), ...
    y(1:step:end), ...
    vx(1:step:end), ...
    vy(1:step:end))

axis equal
grid on

xlabel('East-West distance from REAL (m)')
ylabel('South-North distance from REAL (m)')
title('M2HATS Typhoon horizontal vector field')
```

Again, arrow decimation is only for visual clarity.

---

# 29. MATLAB: reconstruct the full grid

The `indices` variable is zero based.

MATLAB array indices are one based.

Therefore:

```matlab
dimRow = 438;
dimCol = 313;

row = floor(double(indices) ./ dimCol);
col = mod(double(indices), dimCol);

VX = nan(dimRow,dimCol);
VY = nan(dimRow,dimCol);

I = sub2ind( ...
    [dimRow dimCol], ...
    row + 1, ...
    col + 1);

VX(I) = vx;
VY(I) = vy;
```

Do not simply use:

```matlab
VX(indices + 1) = vx;
```

because MATLAB's linear indexing is column-major while the stored Typhoon `indices` correspond to the row-major flattened grid convention described above.

---

# 30. Converting the Typhoon time in Python

The stored time is a Unix/POSIX timestamp.

```python
from datetime import datetime, timezone

t = datetime.fromtimestamp(
    float(time_seconds),
    tz=timezone.utc
)

print(t)
```

For the representative files:

```text
2023-08-03 17:39:08.397 UTC
```

---

# 31. Converting the Typhoon time in MATLAB

```matlab
t = datetime( ...
    double(time_seconds), ...
    'ConvertFrom','posixtime', ...
    'TimeZone','UTC');
```

For local Nevada/California summer time:

```matlab
t.TimeZone = 'America/Los_Angeles';
```

---

# 32. Wind speed and direction

Horizontal wind-speed magnitude can be calculated as:

```text
speed = sqrt(vx^2 + vy^2)
```

Python:

```python
speed = np.hypot(vx, vy)
```

MATLAB:

```matlab
speed = hypot(vx,vy);
```

Because:

```text
vx = eastward component
vy = northward component
```

meteorological wind direction requires care.

A vector pointing toward the northeast represents air **moving toward** the northeast, whereas meteorological wind direction is normally named for the direction **from which** the wind comes.

Do not use `atan2(vy,vx)` and label the result "meteorological wind direction" without converting conventions explicitly.

---

# 33. Comparing two Typhoon processing cases

Suppose `FULL` and `NONE` are being compared.

Their valid-vector locations are not necessarily identical.

A safe procedure is:

```text
1. Read indices from both files.
2. Find the intersection of the two index sets.
3. Compare vx and vy only at matching Cartesian cells.
```

Python example:

```python
common, i_full, i_none = np.intersect1d(
    idx_full,
    idx_none,
    return_indices=True
)

dvx = vx_full[i_full] - vx_none[i_none]
dvy = vy_full[i_full] - vy_none[i_none]
```

This avoids comparing different physical locations.

---

# 34. Do not confuse grid spacing with independent resolution

The representative M2HATS files use:

```text
8-m Cartesian grid spacing
```

This does **not** mean that every vector represents an independent 8-m-resolution wind measurement.

Typhoon is a regularized dense optical-flow estimator.

The effective spatial resolution depends on:

- REAL image resolution;
- aerosol texture;
- Typhoon wavelet scales;
- regularization;
- masking;
- preprocessing;
- scan-motion correction;
- processing parameters.

This distinction is especially important for turbulence and spectral analyses.

For the scientific interpretation of Typhoon spatial resolution, see the 2015 JTECH validation paper described in:

```text
Typhoon_overview.md
```

---

# 35. Do not treat every stored vector as equally independent or certain

The valid-data mask is designed to exclude regions lacking adequate coherent aerosol structure.

However:

- neighboring vectors remain coupled through the optical-flow solution;
- the output is regularized;
- image information varies spatially;
- retrieval quality depends on atmospheric conditions.

A stored vector should therefore be understood as part of a spatially coupled retrieved field.

The netCDF file does not currently provide a simple per-vector uncertainty estimate in units of m/s.

---

# 36. Relationship to REAL images

Typhoon operates on sequential REAL aerosol images.

The current M2HATS REAL documentation describes how raw BSCAN data are converted into relative-backscatter imagery:

```text
REAL_bscan_signal_processing.md
```

The full reference Typhoon workflow includes additional processing required for motion estimation, including:

- valid-data masking;
- scan-motion correction;
- Cartesian gridding.

Therefore:

> A public high-pass-filtered REAL PNG and a Typhoon input field are closely related, but they should not automatically be assumed to be numerically identical products.

---

# 37. Public PNG wind-field products

Pre-rendered M2HATS Typhoon wind-field images are available at:

```text
https://lidar.csuchico.edu/m2hats/images/winds/
```

These are useful for:

- visual inspection;
- identifying interesting events;
- presentations;
- quick browsing.

For quantitative analysis, use the numerical Typhoon netCDF data rather than extracting vectors from PNG images.

---

# 38. Recommended public workflow

For most users, the practical workflow is:

```text
1. Read Typhoon_overview.md.

2. Identify a time/event of interest.

3. Inspect pre-made REAL and wind-field images if useful.

4. Obtain the corresponding Typhoon netCDF file.

5. Read:
       time
       x
       y
       vx
       vy
       indices

6. Inspect user_info / sequence metadata.

7. Plot or analyze the stored valid vectors.

8. If comparing processing cases, match by indices.

9. Return to the source BSCAN files only when the
   underlying aerosol imagery is needed.
```

Users should not need to compile or run Typhoon merely to work with already-computed M2HATS wind fields.

---

# 39. Current status of the public Typhoon archive

The existing public Typhoon archive contains several sensitivity and processing experiments.

The representative files inspected for this document demonstrate that the netCDF schema itself is well structured and preserves substantial provenance.

However, the entire archive has **not yet been audited file by file** for:

- completeness;
- temporal coverage;
- preferred processing configuration;
- alpha sensitivity;
- all stationary-case selections;
- all source-scan pairs;
- missing/corrupt files;
- final scientific recommendation among the processing cases.

Therefore this document describes **how to read and interpret the products that exist**.

It does not declare the entire current directory to be a single final canonical M2HATS Typhoon data product.

---

# 40. References

## Typhoon atmospheric-wind application

Dérian, P., C. F. Mauzey, and S. D. Mayor (2015), "Wavelet-Based Optical Flow for Two-Component Wind Field Estimation from Single Aerosol Lidar Data," *Journal of Atmospheric and Oceanic Technology*, **32**, 1759-1778.

```text
https://doi.org/10.1175/JTECH-D-15-0010.1
```

## Original wavelet optical-flow formulation

Dérian, P., P. Héas, C. Herzet, and E. Mémin (2013), "Wavelets and Optical Flow Motion Estimation," *Numerical Mathematics: Theory, Methods and Applications*, **6**, 116-137.

```text
https://inria.hal.science/hal-00737566v1
```

## Sasano scan-distortion correction

Sasano, Y., H. Hirohara, T. Yamasaki, H. Shimizu, N. Takeuchi, and T. Kawamura (1982), "Horizontal Wind Vector Determination from the Displacement of Aerosol Distribution Patterns Observed by a Scanning Lidar," *Journal of Applied Meteorology*, **21**, 1516-1523.

```text
https://doi.org/10.1175/1520-0450(1982)021<1516:HWVDFT>2.0.CO;2
```

Stable JSTOR record:

```text
https://www.jstor.org/stable/26180769
```

---

# 41. Related M2HATS documentation

Experiment overview:

```text
M2HATS_overview.md
```

Public data locations:

```text
M2HATS_data_locations.md
```

ISFS data:

```text
M2HATS_ISFS_data.md
```

REAL documentation:

```text
REAL_instrument_description.md
REAL_bscan_data_file_format.md
REAL_bscan_signal_processing.md
```

Typhoon scientific overview:

```text
Typhoon_overview.md
```

---

# 42. Compact summary for a new user or AI

> An M2HATS Typhoon netCDF file contains a sparse set of valid two-component horizontal wind vectors on a defined Cartesian grid centered on REAL. `x` and `vx` are east-positive; `y` and `vy` are north-positive. `indices` gives the zero-based row-major location of every valid vector in the full `dimRow x dimCol` grid. The file records a reference UTC time, the two source REAL BSCAN files, Cartesian-grid metadata, Typhoon processing parameters, scan-motion-correction mode, and optimizer diagnostics. The `FULL`, `MEAN`, and `NONE` cases test different treatments of the finite-scan-time distortion first addressed by Sasano et al. (1982); `REF` uses an external reference-wind workflow, while `initREF` is an experimental REF-derived configuration rather than a separate `sasano_correction` keyword. Users can read and analyze these output files without installing or running Typhoon itself.
