Metadata-Version: 2.4
Name: spacial_boxcounting
Version: 0.3.1
Summary: Convenient package for spatial box counting and fractal analysis across data types with CPU and GPU support
Home-page: https://github.com/ollimacp/spacial-boxcounting-cpu-gpu
Author: Ole Peters
Author-email: Ole Peters <ollimacp@gmail.com>
Maintainer-email: Ole Peters <ollimacp@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ollimacp/spacial-boxcounting-cpu-gpu
Project-URL: Repository, https://github.com/ollimacp/spacial-boxcounting-cpu-gpu
Project-URL: Documentation, https://github.com/ollimacp/spacial-boxcounting-cpu-gpu#readme
Project-URL: Bug Reports, https://github.com/ollimacp/spacial-boxcounting-cpu-gpu/issues
Project-URL: Source Code, https://github.com/ollimacp/spacial-boxcounting-cpu-gpu
Keywords: fractal-analysis,box-counting,image-processing,spatial-analysis,gpu-acceleration
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.20.0
Requires-Dist: numba>=0.53.0
Requires-Dist: Pillow>=8.0.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: hilbertcurve>=1.0.0
Requires-Dist: pandas>=1.3.0
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=9.0.0; extra == "gpu"
Provides-Extra: gpu-amd
Requires-Dist: cupy-rocm-5-0>=12.0.0; extra == "gpu-amd"
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: sphinx>=4.0.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: safety>=3.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# spacial-boxcounting: Spatial Boxcount Algorithm & Fractal Analysis

An implementation of a spatial boxcount algorithm for fractal analysis, with both CPU and GPU support for accelerated computation.

## Abstract
This project implements a spatial boxcount algorithm that characterizes 2D arrays by topological complexity and spatial heterogeneity. With both CPU and GPU support, it enables spatial similarity search, edge detection, and statistical analysis of image datasets.

## Key Features
- **Spatial Box Counting**: Produces 2D maps of box count ratios and lacunarity
- **Fractal Dimension Analysis**: Multi-scale fractal dimension computation
- **Multiple Processing Modes**: Spatial maps or single-value results
- **CPU & GPU Support**: Numba JIT compilation and CuPy acceleration — switch via `backend="cpu"|"gpu"`
- **Batch Processing**: Process entire directories of images
- **Multiple Input Formats**: JPEG, BMP, PNG, and binary files
- **Hilbert Curve Mapping**: Preserves data locality for binary file analysis
- **Cross-Platform**: Works on Windows, Linux, and macOS

## Installation
Install via pip:

```bash
# Basic CPU-only installation
pip install spacial_boxcounting

# With GPU support (NVIDIA CUDA)
pip install spacial_boxcounting[gpu]

# With GPU support (AMD ROCm — experimental)
pip install spacial_boxcounting[gpu-amd]

# Development installation
pip install -e ".[dev]"
```

## Quick Start

### Processing from a Numpy Array

```python
import numpy as np
from spacial_boxcounting.api import boxcount_from_array, fractal_dimension_from_array

arr = np.random.randint(0, 256, size=(256, 256)).astype(np.uint8)

# Spatial processing (CPU)
result = boxcount_from_array(arr, mode='spatial')
print('Spatial Result shape:', [r.shape for r in result])

# Single value processing (CPU)
result = boxcount_from_array(arr, mode='single')
print('Box Count & Lacunarity:', result)

# GPU-accelerated — just add backend='gpu'
result_gpu = boxcount_from_array(arr, mode='single', backend='gpu')
print('GPU Result:', result_gpu)

# Fractal dimension (CPU or GPU)
fd_cpu = fractal_dimension_from_array(arr)
fd_gpu = fractal_dimension_from_array(arr, backend='gpu')
print(f'Fractal Dimension: CPU={fd_cpu:.3f}, GPU={fd_gpu:.3f}')
```

### Processing a File

```python
from spacial_boxcounting.api import boxcount_from_file, fractal_dimension

# CPU
result = boxcount_from_file('path/to/image.jpg', mode='spatial')
fd = fractal_dimension('path/to/image.jpg')

# GPU
result = boxcount_from_file('path/to/image.jpg', mode='spatial', backend='gpu')
fd = fractal_dimension('path/to/image.jpg', backend='gpu')
```

## Command-Line Interface

```bash
# CPU (default)
spacial-boxcount single --file path/to/image.jpg --mode spatial

# GPU — just add --backend gpu
spacial-boxcount single --file path/to/image.jpg --mode spatial --backend gpu

# Batch processing with GPU
spacial-boxcount batch --folder path/to/images/ --mode single --backend gpu

# With Hilbert curve mapping (for binary files)
spacial-boxcount single --file path/to/data.bin --mode spatial --hilbert
```

## GPU Acceleration

GPU acceleration is available via CuPy. Use the `backend="gpu"` parameter:

```python
from spacial_boxcounting.api import boxcount_from_array

# All API functions accept backend='cpu' (default) or backend='gpu'
result = boxcount_from_array(arr, mode='single', backend='gpu')
```

If CuPy is not installed, requesting `backend="gpu"` raises a clear `ImportError`:

```
ImportError: GPU backend requested but CuPy is not installed.
Install with: pip install spacial_boxcounting[gpu]
```

### GPU Backend Detection

```python
from spacial_boxcounting import CUPY_AVAILABLE, GPU_BACKEND

print(f'CuPy available: {CUPY_AVAILABLE}')
print(f'GPU backend: {GPU_BACKEND}')  # 'cuda', 'rocm', or None
```

### Performance

Measured on RTX 4060 Ti (batched 4D-tensor implementation):

| Image Size | Boxsize=2 | Boxsize=4 | Boxsize=16 |
|------------|-----------|-----------|------------|
| 128×128    | 9×        | 5×        | 1×         |
| 256×256    | 9×        | 18×       | 4×         |
| 512×512    | 3×        | 12×       | 16×        |
| 1024×1024  | 2.6×      | 11×       | **35×**    |

- **Small images (< 128×128)**: CPU may be faster due to GPU transfer overhead
- **Large images (> 512×512)**: GPU provides 2–35× speedup
- **AMD users**: ROCm support is experimental (`pip install spacial_boxcounting[gpu-amd]`)

## Hilbert Curve Mapping for Binary Data
For binary files, the Hilbert curve mapping preserves data locality when converting 1D data streams to 2D arrays for spatial analysis:

```python
result = boxcount_from_file('data.bin', mode='spatial', hilbert=True)
fd = fractal_dimension('data.bin', hilbert=True)
```

## Batch Processing
Process multiple images with progress tracking:

```python
from spacial_boxcounting.batch import batch_boxcount

results = batch_boxcount('path/to/images/', mode='single')
for filename, result in results.items():
    print(f'{filename}: {result}')
```

## License
See [LICENSE.txt](LICENSE.txt) for details.
