# Field Demo Package

This directory contains a demo for reconstructing and visualizing a 2D scalar field from scattered sample points.

**Contents:**
- `visualize_field.py`: Builds an IDW interpolator from a CSV and renders a 3D surface.
- `generate_field_data.py`: Generates one demo CSV in `field_demo/`.
- `generate_examples.py`: Clears `examples/`, creates fresh example datasets, makes scatter plots, and calls `visualize_field.py` to render surface plots.
- `examples/`: Output folder for generated CSV files, scatter plots, and surface images.
- `README.md`: Setup and usage notes.
- `intro.md`: Short package overview.

**Use Case:**
Load sparse field measurements and reconstruct the field at arbitrary points for visualization or further processing. The script respects the original sample positions and efficiently interpolates values using inverse distance weighting.

**How It Works:**
1. Load scattered sample points from a CSV.
2. Build an IDW interpolator using KD-tree acceleration.
3. Generate a 3D surface over a grid.
4. Save the resulting image for inspection.

**Run the visualizer directly:**
```bash
python visualize_field.py --input path/to/input.csv --output path/to/output.png
```

Optional arguments:
- `--grid-size` controls rendering resolution.
- `--neighbors` controls how many nearest points contribute to each interpolation.
- `--power` controls the IDW distance falloff.

**Generate examples:**
When you run `generate_examples.py`, it clears the `examples/` directory and recreates it with fresh outputs. Each example produces:
- one CSV file of sampled points,
- one scatter plot showing where the points are and what values they carry,
- one surface image produced by calling `visualize_field.py`.

Run all examples:
```bash
python generate_examples.py
```

Run only the random examples:
```bash
python generate_examples.py --example random --num-random-examples 5
```

Run only the zero-grid plus three clusters example:
```bash
python generate_examples.py --example zero_grid_three_clusters
```

Example with all options:
```bash
python generate_examples.py --example all --num-random-examples 5 --n-points 140 --seed-offset 0 --cluster-seed 42 --grid-size 180 --neighbors 8 --power 2.0
```

**Special example: `zero_grid_three_clusters`**
This example starts with a baseline 10x10 grid of 100 points, all with value zero, then adds three dense sampled clusters:
- one strong positive peak,
- one strong negative trough,
- one secondary positive peak.

It is designed to make the large-scale peaks and troughs easy to inspect in the reconstructed surface.
