SegVis

SegVis is a lightweight Python implementation of the image-based workflow used to estimate granular segregation degree from front-view and top-view images.

This repository is intended as a clean, public-facing companion to the paper workflow. It keeps the reusable method separate from the larger internal analysis workspace used for manuscript figures.

What Is Included

• HSV-based red/green particle segmentation.
• Front-view normalized centroid-height features.
• Top-view color area-ratio features.
• The front-view segregation indicator s_f.
• A random-forest regressor for mapping visual features to s_true.
• A small sample case with five image pairs and a compact training table.

Project Layout

SegVis/
  segvis/                     # Reusable Python package
  examples/
    run_sample_case.py        # End-to-end example
    sample_case/
      images/                 # Five front/top image pairs
      training_data.csv       # Lightweight table for model training
      sample_truth.csv        # Reference values for the sample frames
      outputs/                # Generated when the example is run
  tests/                      # Minimal sanity tests
  docs/project_analysis.md    # Notes on what was extracted from the internal project
  requirements.txt
  pyproject.toml

Quick Start

From this directory:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python examples/run_sample_case.py

The example writes:

examples/sample_case/outputs/extracted_features.csv
examples/sample_case/outputs/predictions.csv
examples/sample_case/outputs/sample_case_summary.png

Command-Line Usage

Train a model from a CSV/XLSX table:

python -m segvis.cli train ^
  --data examples/sample_case/training_data.csv ^
  --model examples/sample_case/outputs/segvis_rf.joblib

Predict from an extracted feature table:

python -m segvis.cli predict ^
  --model examples/sample_case/outputs/segvis_rf.joblib ^
  --data examples/sample_case/outputs/extracted_features.csv ^
  --output examples/sample_case/outputs/predictions_cli.csv

Data Columns

The default paper model uses these feature columns:

volume_ratio, size_ratio, density_ratio, s_f, p_green

The target column is:

s_true

Legacy manuscript column names such as 体积比, 粒径比, 密度比, S_ce, and S_true are automatically mapped to stable English names.

Method Notes

SegVis does not perform single-particle tracking. It segments color regions, computes statistical image features, and uses a supervised model to estimate segregation degree.

The default HSV thresholds are:

• red: H=0-10 and H=160-179, S=100-255, V=100-255
• green: H=35-85, S=50-255, V=50-255

These thresholds are suitable for the included DEM-rendered example. Real experiments may require recalibration or adaptive color segmentation.

License

This project is released under the MIT License.

Citation

If you use SegVis, please cite the associated manuscript. The DOI will be added after publication.