SplineAnalyzer is a research-grade software framework developed within the context of PhD dissertation research on analytical spline surfaces and their applications in image analysis. The system implements sophisticated mathematical models for unsupervised clustering and discriminant analysis based on B-spline basis functions.
The core methodology centers on the analytical representation of bivariate spline surfaces using the double summation formula:
where
Key Research Contributions:
- Analytical Spline Surfaces: Continuous mathematical model eliminating discrete approximations
- B-spline Basis: Orthogonal polynomial basis for optimal function approximation
- Unsupervised Clustering: Gradient-based mode seeking with analytical convergence guarantees
- Discriminant Analysis: Statistical classification based on spline-derived probability distributions
- Python: Version 3.10 or higher
- Operating System: Windows 10/11, Linux, or macOS
- RAM: Minimum 8 GB (16 GB recommended for large datasets)
Install all required packages using the provided requirements file:
pip install -r requirements.txtCore Dependencies:
numpy>=1.21.0— Numerical computing foundationscipy>=1.7.0— Scientific computing utilitiesPyQt6>=6.2.0— Graphical user interface frameworkmatplotlib>=3.4.0— Visualization and plottingopencv-python>=4.5.0— Image processing operationspandas>=1.3.0— Data manipulation and analysis
To start the application with full GUI capabilities:
python scripts/run_app.pyThis command initializes the PyQt6-based interface, providing access to:
- Spline Laboratory: Interactive environment for detailed spline analysis
- Experimental Research Module: Parameter exploration and model visualization
- Benchmark Laboratory: Comparative algorithm evaluation framework opened from the main GUI route
- Analysis Pipeline: End-to-end image processing workflow
The benchmark GUI is opened from the main application through Tools -> Benchmark Laboratory.
For batch processing or server environments without display capabilities, use python scripts/run_app.py --headless or call the service-layer pipeline directly.
src/
└── spline_analyzer/
├── main.py # Application entry point
├── core/ # Domain Layer (Mathematical Core)
│ ├── spline_core.py # S_{2,0} spline implementation
│ ├── jax_spline_s20.py # Архівна JAX-реалізація (довідково)
│ ├── clustering.py # Fast analytical clustering
│ ├── feature_extractor.py # Integral image statistics
│ ├── pipeline_v2.py # Analysis orchestration
│ ├── spline_model_v3.py # High-level Spline Model (v3)
├── services/ # Service Layer (Business Logic)
│ ├── analysis_service.py # Analysis coordination
│ ├── visualization_service.py # Data visualization
│ └── clustering_service.py # Clustering logic orchestration
├── gui/ # Interface Layer (PyQt6)
│ ├── main_interface.py # Main application window
│ ├── spline_laboratory.py # Interactive analysis lab
│ └── benchmarks/ # Benchmarking tools
└── benchmark/ # Benchmarking infrastructure
├── algorithm_runner.py # Comparative algorithm execution
├── benchmark_engine.py # Benchmark orchestration facade
├── metrics.py # Metrics entry layer
└── metrics/ # Unified metric implementations
Each pixel is mapped to a 2D feature vector via a sliding window of radius k:
- Local mean: m(i,j) = average intensity over a (2k+1)×(2k+1) window
- Local std: σ(i,j) = standard deviation over the same window
Both are computed in O(1) per pixel via Summed-Area Tables (integral images), giving O(N) total cost instead of naive O(N · window_size). The features are provably invariant: σ is invariant to additive brightness shift (shadow-robust), and both m and σ are invariant to 90° rotation/mirroring of the window (flight-direction independent) — Theorems 2.1–2.2 of the dissertation.
The resulting (m, σ) point cloud is binned onto an A_m × A_σ histogram grid (G = A_m · A_σ cells) and fit by an S_{2,0} biquadratic spline density surface — the same mean-preserving, C¹, O(h²)-accurate surface described in the Abstract above.
Once the local maxima ("modes") {M_k} of the S_{2,0} surface are found — coarse grid search → gradient-ascent refinement → Hessian sign verification → non-max-suppression merge, all O(G) — pixels are assigned to clusters by one of two independent strategies:
SplineS20-GA — Convergent Potential. For pixel X and mode M_k, the convergent potential P_k(X) = ∇S(X) · û_k(X) projects the local density gradient onto the unit direction toward M_k; the pixel is assigned to the mode whose direction the gradient "points toward" most strongly: label(X) = argmax_k P_k(X). Cost: O(K) per pixel.
SplineS20-DL — Discriminant Lines. For every mode pair (M_A, M_B), a rhombus-shaped zone between them is scanned for valley (minimum-density) points; those points are fit with a straight line by Total Least Squares (SVD-based, orthogonal-distance fit). Each pixel is then classified by its sign pattern against all C(K,2) discriminant lines. Cost: O(K²) per pixel, but no per-pixel gradient evaluation — on the 150-scene benchmark this makes DL ~4.3× faster than GA at inference (541 ms vs 2342 ms average, see below).
A barrier-strength score B_s ∈ [0,1] quantifies how well two modes are separated (0 = effectively merged, 1 = deep density valley); pairs below B_min = 0.05 may be merged before line-fitting.
After labeling, an optional density-based post-selection filter keeps, for
each cluster, only the top p_auto fraction of pixels by local S_{2,0}
density — i.e. it drops the noisiest/most boundary-adjacent pixels of each
cluster rather than keeping the full basin of attraction.
Measured effect (150-scene real-image benchmark, p_auto = 0.5 vs. no filtering): ARI +33.3% (GA), +30.4% (DL); Silhouette +57.0% (GA), +56.3% (DL); the filtered variant wins on 64.7% (GA) / 63.3% (DL) of individual scenes in a pairwise per-scene comparison against its own unfiltered baseline.
The definitive dissertation benchmark uses the enhanced benchmark suite with 30 synthetic images, 7 methods, and comprehensive statistical analysis.
Parameters: G=48, threshold_rel=0.05, min_dist=3, SEED=42
# Run the canonical benchmark dry-run
python tools/run_all_benchmarks.py --dry-run
# Run the canonical full benchmark pipeline
python tools/run_all_benchmarks.py
# Run individual benchmark scripts when needed
python scripts/benchmarks/benchmark_v6.py
python scripts/benchmarks/benchmark_v6_tuned.py
python scripts/benchmarks/run_full_benchmark_with_pauto_metrics.pyPrimary benchmark artifacts are written under final_benchmark_results/, results/benchmark_v6/, results/benchmark_v6_tuned/, results/benchmark_v6_pauto/, results/article_experiments/, and results/article_experiments_top50/.
| Rank | Algorithm | ARI | V-measure | CHI | |Δk| | Time (ms) | Type | |------|-----------|-----|-----------|-----|------|-----------|------| | 1 | SplineS20_Grad | 0.983±0.037 | 0.985±0.023 | 596,295 | 0.03 | 272 | Dissertation ✨ | | 2 | SplineS20_Discr | 0.981±0.038 | 0.983±0.023 | 590,033 | 0.03 | 2,420 | Dissertation ✨ | | 3 | GMM_BIC | 0.953±0.027 | 0.963±0.017 | 429,269 | 5.6 | 18,360 | Auto-k baseline | | 4 | HDBSCAN | 0.934±0.072 | 0.955±0.033 | 256,712 | 15.9 | 1,237 | Non-parametric | | 5 | GMM* (Oracle K) | 0.817±0.027 | 0.921±0.018 | 220,220 | 0.0 | 1,249 | Oracle baseline | | 6 | Agglom* (Oracle K) | 0.801±0.028 | 0.904±0.020 | 224,308 | 0.0 | 1,349 | Oracle baseline | | 7 | KMeans* (Oracle K) | 0.797±0.024 | 0.900±0.018 | 227,741 | 0.0 | 244 | Oracle baseline |
Note: Methods marked with * receive Oracle K (ground truth number of clusters). SplineS20, GMM_BIC, and HDBSCAN detect k automatically.
- SplineS20_Grad ranks #1 with ARI=0.983 and V-measure=0.985 — significantly outperforms all competitors
- Exact k detection in 29/30 images (97%) — |Δk|=0.03, far superior to GMM_BIC (|Δk|=5.6) and HDBSCAN (|Δk|=15.9)
- Fastest auto-k method: 272 ms — 67× faster than GMM_BIC (18,360 ms)
- O(1) time complexity: computational time independent of dataset size (slope α=−0.12)
- Fully deterministic: σ=0 across repeated runs (unlike KMeans/GMM which vary by up to 0.042 ARI)
- Pareto-dominant: simultaneously better ARI AND faster time than all competitors except oracle KMeans*
- Bayesian Signed-Rank: P(SplineS20 wins) > 0.985 for all comparisons
| Test | Result |
|---|---|
| Friedman χ² | 150.55, p = 5.92×10⁻³⁰ |
| Nemenyi CD | 1.645 (SplineS20_Grad significantly better than all except SplineS20_Discr) |
| Bayesian Signed-Rank | P(win) > 0.985 vs all competitors |
| Pareto Dominance | P > 0.999 for Agglom*, GMM*, GMM_BIC, HDBSCAN, SplineS20_Discr |
| Effect Size (Cohen's d) | d > 0.85 (LARGE) vs all competitors except SplineS20_Discr |
| Determinism | SplineS20: σ=0 (YES), KMeans*/GMM*/GMM_BIC: σ>0 (NO) |
| N | SplineS20 (ms) | KMeans (ms) | GMM (ms) | SplineS20/KMeans | SplineS20/GMM |
|---|---|---|---|---|---|
| 1,000 | 519 | 20 | 26 | 0.04x | 0.05x |
| 50,000 | 220 | 168 | 471 | 0.8x | 2.2x |
| 500,000 | 346 | 2,070 | 5,122 | 6.8x faster | 16.0x faster |
SplineS20 scaling: α=−0.12 (O(1)); KMeans: α=0.73 (O(N⁰·⁷³)); GMM: α=0.86 (O(N⁰·⁸⁶))
Separate from the n=30 synthetic benchmark above, the dissertation's central experimental result is a comparison on 150 real aerial images drawn from three independent sources (own UAV footage, LoveDA, OpenEarthMap) — 1,050 total measurements (150 scenes × 7 methods), no execution failures.
Table — mean quality metrics across 150 real scenes, ranked by ARI
| Method | ARI | NMI | mIoU | mDice | Silhouette | Davies–Bouldin | Time (ms) |
|---|---|---|---|---|---|---|---|
| GA + p_auto=0.5 | 0.134 | 0.151 | 0.409 | 0.267 | 0.635 | 0.49 | 2342 |
| DL + p_auto=0.5 | 0.121 | 0.136 | 0.402 | 0.255 | 0.611 | 0.54 | 541 |
| GMM | 0.117 | 0.134 | 0.248 | 0.300 | 0.395 | 0.99 | 1310 |
| Agglomerative | 0.115 | 0.122 | 0.244 | 0.288 | 0.447 | 0.85 | 33 |
| K-Means | 0.114 | 0.123 | 0.244 | 0.292 | 0.457 | 0.83 | 267 |
| GA (baseline, no post-selection) | 0.100 | 0.116 | 0.393 | 0.256 | 0.405 | 0.89 | 2342 |
| DL (baseline, no post-selection) | 0.093 | 0.107 | 0.390 | 0.251 | 0.391 | 0.95 | 537 |
GA + p_auto=0.5 ranks first on 5 of 6 quality metrics (ARI, NMI, mIoU, Silhouette, Davies–Bouldin); GMM leads only on mDice, attributable to a difference in the number of detected clusters. Classical methods (GMM, K-Means, Agglomerative) receive Oracle K; the spline methods detect K automatically, matching it exactly in 32% of scenes with a mild under-segmentation tendency (mean ΔK = −0.54).
Note on scale vs. the n=30 synthetic benchmark above: ARI on real imagery (0.09–0.13) is far lower than on the clean synthetic benchmark (0.80–0.98) — this is expected: real aerial scenes have no ground-truth class boundaries as clean as synthetic Gaussian blobs, and mIoU/Silhouette tell a more forgiving story (mIoU up to 0.41, Silhouette up to 0.64) on the same real data. The two benchmarks measure different things and should not be compared directly.
| Metric | GA | GA+p_auto | Δ | Δ% | DL | DL+p_auto | Δ | Δ% |
|---|---|---|---|---|---|---|---|---|
| ARI | 0.100 | 0.134 | +0.033 | +33.3% | 0.093 | 0.121 | +0.028 | +30.4% |
| NMI | 0.116 | 0.151 | +0.035 | +30.4% | 0.107 | 0.136 | +0.029 | +26.9% |
| mIoU | 0.393 | 0.409 | +0.016 | +4.1% | 0.390 | 0.402 | +0.013 | +3.2% |
| Silhouette | 0.405 | 0.635 | +0.231 | +57.0% | 0.391 | 0.611 | +0.220 | +56.3% |
Per-scene pairwise comparison: GA+p_auto beats plain GA on 97/150 scenes (64.7%), loses on 29 (19.3%), ties on 24 (16.0%); DL+p_auto beats plain DL on 95/150 (63.3%).
benchmark_results_headless/
├── phd_benchmark_study_YYYYMMDD_*/ # 🎨 Synthetic benchmark results
│ ├── results.csv # Raw metrics per algorithm/image
│ ├── tables/summary_table.tex # LaTeX tables for dissertation
│ ├── plots/ # Bar charts and visualizations
│ └── images/ # Segmentation mask outputs
│
└── real_images_phd_study_YYYYMMDD_*/ # 📷 Real images benchmark results
├── results.csv
└── tables/
To run benchmarks on your own images:
images/
├── input/ # 📁 Your input images (*.jpg, *.png)
│ ├── 1.jpg
│ ├── 2.jpg
│ └── ...
└── annotat/ # 📁 CSV annotations (bounding boxes)
├── 1.csv # Same name as corresponding image
├── 2.csv
└── ...
Annotation format (CSV):
xmin,ymin,xmax,ymax,category_id
100,150,200,250,0
300,400,450,500,1This repository does not redistribute any raw imagery. The pipeline is dataset-agnostic (any RGB image + optional CSV annotation in the format above) and has been developed and validated using the following public, freely available remote-sensing datasets, alongside synthetic benchmark scenes:
- LoveDA — Wang, J., Zheng, Z., Ma, A., Lu, X., & Zhong, Y. (2021). "LoveDA: A Remote Sensing Land-Cover Dataset for Domain Adaptive Semantic Segmentation." NeurIPS 2021 Track on Datasets and Benchmarks. arXiv:2110.08733 · Zenodo DOI: 10.5281/zenodo.5706578
- OpenEarthMap — Xia, J., Yokoya, N., Adriano, B., & Broni-Bediako, C. (2023). "OpenEarthMap: A Benchmark Dataset for Global High-Resolution Land Cover Mapping." WACV 2023, 6254–6264. arXiv:2210.10732
To reproduce the real-image benchmark yourself:
- Download LoveDA and/or OpenEarthMap from the sources above under their respective licenses.
- Convert the scenes you want to test into the
images/input/+images/annotat/layout shown above (one RGB image + one CSV of bounding boxes per scene). - Run the benchmark commands from the
Benchmark Results section above against your
prepared
images/directory.
If you utilize this software in your research, please cite the corresponding dissertation work:
@phdthesis{zhultynska2026spline,
title={Spline-Based Methods for Image Analysis and Clustering},
author={Zhultynska, A.},
year={2026},
school={National University "Kyiv Aviation Institute"},
note={Scientific advisor: P. Prystavka}
}SplineAnalyzer is released as open academic research for image analysis, clustering, and anomaly detection (e.g. remote sensing, precision agriculture, environmental and land-cover monitoring, industrial quality inspection). It is not intended, tuned, or validated for military targeting, surveillance, or reconnaissance applications. No real-world military, defense, or classified imagery is included in this repository. Any use of this work that supports the Russian Federation's aggression against Ukraine is explicitly prohibited.
This software is developed for academic research purposes. Please refer to the license terms provided with the distribution.
For technical inquiries or collaboration proposals related to this research, please contact the dissertation author.
SplineAnalyzer — Advancing image analysis through analytical spline methodology.