# M2HATS REAL BSCAN PPI Viewer Guide

This two-file teaching tool lets students create custom images from the public
REAL lidar data collected during M2HATS in 2023. It is based on the reader,
preprocessing sequence, coordinate conversion, plotting style, and sonic-array
marker used in Pierre Derian's `lidar_toolbox`, but it does not require that
larger toolbox.

The companion program is:

```text
M2HATS_REAL_bscan_PPI_viewer.py
```

It reads one BSCAN over HTTPS into memory, selects the scan nearest to a
requested UTC time, displays it in an interactive Matplotlib window, and can
save a high-resolution PNG. The raw file is not permanently copied to the
student's computer.

## Install the small set of dependencies

Python 3.10 or newer is recommended.

```bash
python -m pip install numpy scipy matplotlib
```

On some Linux systems the command may be `python3` and `pip3` instead of
`python` and `pip`.

## Simplest use

Put `M2HATS_REAL_bscan_PPI_viewer.py` in the current directory and run:

```bash
python M2HATS_REAL_bscan_PPI_viewer.py
```

The defaults select a known M2HATS PPI scan near:

```text
2023-08-04 18:18:03 UTC
```

The program opens an interactive square plot. Use the Matplotlib toolbar to
pan, zoom, reset the view, and save an image. The default color-bar limits are
−1 to 3 dB for filtered data and 26 to 40 dB for unfiltered data. The default
colormap is `nipy_spectral`, and the major coordinate ticks are spaced every
200 m.

## Typical custom image

```bash
python M2HATS_REAL_bscan_PPI_viewer.py \
  --date 2023-08-04 \
  --time 18:18:03 \
  --filtered \
  --xmin 900 --xmax 1500 \
  --ymin -100 --ymax 500 \
  --vmin -1 --vmax 3 \
  --save dust_devil.png
```

The timestamp in every REAL BSCAN filename and header is UTC. The plot title
also shows the equivalent `America/Los_Angeles` time by default.

## Filtering modes

The viewer exposes two student-facing modes:

```text
--filtered      low-pass median filter followed by high-pass median filter
--unfiltered    no median filtering
```

The default is `--filtered`.

Pierre's default filter lengths are:

```text
low-pass median length:  7 range bins
high-pass median length: 333 range bins
```

They can be changed with:

```bash
python M2HATS_REAL_bscan_PPI_viewer.py \
  --filtered \
  --lowpass-length 7 \
  --highpass-length 333
```

The high-pass operation is the signal minus a long-range median-filtered
version of the signal. Pierre's filtered processing also removes half the
high-pass window from each range edge to avoid edge effects. The unfiltered
mode skips both median filters and keeps the full processed range.

“Unfiltered” does not mean untouched binary values. Both modes still perform
the necessary REAL BSCAN decoding, polarization-channel combination,
background subtraction, range-squared correction, conversion to relative
backscatter dB, coordinate conversion, and scan-type identification.

## Useful options

```text
--date YYYY-MM-DD       requested UTC date
--time HH:MM:SS         requested UTC time
--filtered              apply both median filters
--unfiltered            apply neither median filter
--lowpass-length N      odd low-pass median length; default 7
--highpass-length N     odd high-pass median length; default 333
--xmin, --xmax          x-axis limits in meters
--ymin, --ymax          y-axis limits in meters
--vmin, --vmax          color-bar limits in dB; mode-dependent defaults
--cmap NAME             Matplotlib colormap; default nipy_spectral
--tick-step N           major tick spacing in meters; default 200
--timezone NAME         title timezone; data remain UTC
--save FILE.png         additionally save a high-resolution PNG
--dpi N                 PNG resolution; default 300
--no-array-marker       omit the white dashed M2HATS sonic-array line
--grid                  draw a coordinate grid
--no-show               save without opening a plot window
--help                  show all options
```

For example, an unfiltered, wider view with a different color scale is:

```bash
python M2HATS_REAL_bscan_PPI_viewer.py \
  --date 2023-08-04 --time 18:18:03 \
  --unfiltered \
  --xmin 500 --xmax 1900 --ymin -500 --ymax 900 \
  --vmin 26 --vmax 45 \
  --save wider_unfiltered_view.png
```

## Direct local-file testing

The public mode is the normal student mode. For testing on a machine that
already has the archive, use `--local-root`:

```bash
python M2HATS_REAL_bscan_PPI_viewer.py \
  --local-root /raid/bulk_storage/M2HATS/REAL/bscans \
  --date 2023-08-04 --time 18:18:03 \
  --save test.png --no-show
```

You can also provide one direct local path or HTTPS URL with `--file`.

## How nearest-file selection works

The program reads the Apache directory listings for the requested UTC date and
the adjacent dates, extracts filenames of the form
`REAL.YYYYMMDD_HHMMSS.bscan`, and chooses the filename with the smallest time
difference from the requested time. It then downloads only the selected BSCAN
into memory.

The public data base URL is:

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

The server's public path is an Apache alias to Typhon2's
`/raid/bulk_storage/M2HATS/` directory. Students do not need an account on
Typhon2 or Aeolus2.

## A prompt students can give to an AI

Students can upload this Markdown guide and the Python file to an AI chat and
use a prompt such as:

> I am using the REAL M2HATS BSCAN viewer. Please help me create a command for
> a scan near a requested UTC date and time. Keep the REAL data-processing
> sequence unchanged. I want to adjust only the processing mode, x/y limits,
> color-bar limits, colormap, tick spacing, or PNG filename. Explain every
> option in plain language and do not invent a different BSCAN format.

For a more advanced request, students can ask the AI to add a feature while
preserving the existing reader and checking the result against the command:

```bash
python M2HATS_REAL_bscan_PPI_viewer.py --help
```

## Scientific conventions

- REAL filename and header times are UTC.
- PPI coordinates use the meteorological convention: azimuth 0° points north,
  azimuth increases clockwise, x points east, and y points north.
- Coordinates and axis limits are in meters unless a future version explicitly
  adds another unit option.
- The default white dashed line marks the M2HATS sonic array, using Pierre's
  78.98° azimuth and 1180–1425 m range endpoints.
- The plotted field is relative backscatter intensity in dB, not a raw ADC
  value.

## Attribution and scope

This viewer is a compact educational adaptation of relevant portions of Pierre
Derian's REAL lidar processing and plotting code. It is intended for teaching
and exploration of the publicly served M2HATS data. Preserve the attribution
when sharing it, and obtain any required institutional or author permission
before redistributing it as a general public software package.
