FieldVector

Generic 2D scalar field patch similarity search using gradient, statistical, and spectral features with HNSW indexing.

Note: Forked from terravector and generalized for any 2D scalar field data.

Overview

FieldVector converts any 2D scalar field (temperature, pressure, density, etc.) into searchable vector embeddings. Each patch gets a "fingerprint" based on gradient structure, statistical moments, and spectral content. An HNSW index enables O(log N) similarity queries across millions of patches.

Use cases:

• Find similar patterns in simulation output
• Detect anomalies in sensor data
• Compare fields across different experiments
• Match patterns in climate/weather data
• Quality control in manufacturing (surface inspection)

Installation

git clone https://github.com/bshepp/fieldvector.git
cd fieldvector
pip install -r requirements.txt

Quick Start

Desktop Viewer

python viewer.py path/to/field.npy path/to/index.idx

Web UI

python app.py

Command Line

# Build index from 2D array
python cli.py build field.npy --patch-size 64 --output field.idx

# Build with gradient preset
python cli.py build field.npy --config gradient --output grad.idx

# Query for similar patches
python cli.py query field.idx --patch 42 --k 10

Signature Types

Statistical Features

Patch-level statistics:

• Mean, variance, skewness, kurtosis
• Min, max, range, median
• Percentiles

Gradient Features

Spatial derivative analysis:

• Gradient magnitude statistics
• Gradient direction histogram
• Laplacian (curvature)
• Divergence, curl (for vector fields)

Spectral Features

Frequency domain analysis:

• FFT power spectrum
• Directional FFT
• Dominant frequencies

Decomposition Features

Signal processing:

• Multi-scale decomposition
• Wavelet features
• Morphological filtering

Presets

Preset	Features	Use Case
default	Statistical + Gradient	General purpose
statistical	Full statistics	Distribution matching
gradient	Gradient focus	Edge/flow patterns
spectral	FFT features	Periodic patterns
hybrid	All features	Maximum discrimination

Supported Formats

• NumPy (.npy, .npz) - Primary format
• NetCDF (.nc) - Climate/scientific data
• HDF5 (.h5, .hdf5) - Large datasets
• TIFF (.tif) - Image-like data

Requirements

• Python 3.8+
• numpy, scipy, scikit-image
• nmslib (HNSW implementation)
• xarray, h5py, netCDF4 (optional, for format support)
• gradio, napari (UI)

License

Apache 2.0

Citation

@software{fieldvector2025,
  author = {Shepp, B.},
  title = {FieldVector: 2D Scalar Field Patch Similarity Search},
  year = {2025},
  url = {https://github.com/bshepp/fieldvector}
}