# Particle Shape Analysis Project Guide

This project analyzes compression videos by detecting the lower particle contour, fitting left and right parabolas, and exporting frame-by-frame geometry measurements. The scripts are meant to support an experiment-versus-simulation shape comparison.

## Folder Layout

- `raw_videos/` - input videos for the analysis workflow. Choose one of these files when `analyze_particle_shape_video.py` opens the video picker.
- `output_parabola_fits/` - default output folder from a fresh analysis run. It stores overlay frames, saved fit data, and the measurement spreadsheet.
- `output_parabola_fits_experiment/` - saved experiment fit results used by the comparison figure.
- `output_parabola_fits_simulation/` - saved simulation fit results used by the comparison figure.
- `rendered_output/` - final rendered artifacts for reports or presentations, such as the overlay video and experiment-simulation comparison figure.

## Scripts

- `analyze_particle_shape_video.py` - main interactive analysis script. It opens a video, asks you to select a crop area, provides a GUI for preprocessing and baseline settings, then processes frames and writes measurements.
- `compare_experiment_simulation_shape.py` - creates `rendered_output/simulation_experiment_shape_comparison.png` and `.pdf` from saved experiment and simulation `.npz` fit files.
- `assemble_parabola_overlay_video.py` - builds `rendered_output/parabola_fit_overlay_video.mp4` from the overlay PNG frames in `output_parabola_fits/`.

## Input Videos

- `raw_videos/experiment_compression_run.mp4` - experiment compression video.
- `raw_videos/simulation_compression_3mm_per_s.mp4` - simulation compression video at 3 mm/s.

## Important Outputs

- `output_parabola_fits/frame_####.png` - visual overlays showing detected contours and fitted parabolas.
- `output_parabola_fits/frame_####.npz` - compressed fit data with contour points, polynomial coefficients, baseline position, and image midpoint.
- `output_parabola_fits/parabola_measurements.xlsx` - spreadsheet with width, height, volume, area, strain, Poisson ratio, and baseline data per frame.
- `rendered_output/simulation_experiment_shape_comparison.png` and `.pdf` - generated figure comparing experiment and simulation fits.
- `rendered_output/parabola_fit_overlay_video.mp4` - generated video assembled from overlay frames.

## Typical Workflow

1. Run `analyze_particle_shape_video.py`.
2. Select a video from `raw_videos/`.
3. Draw the crop area around the particle.
4. Adjust preprocessing, Canny thresholds, and baseline in the settings window.
5. Click `Save and Close` to process the video.
6. Review `output_parabola_fits/parabola_measurements.xlsx` and the overlay frames.
7. Run `assemble_parabola_overlay_video.py` to create an overlay video.
8. Run `compare_experiment_simulation_shape.py` to recreate the comparison figure.

## Python Packages

The scripts use `opencv-python`, `numpy`, `pandas`, `matplotlib`, `Pillow`, and `openpyxl`.
