# 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 optional CuPy acceleration
- **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 (NVIDIA GPU support)
## Installation
Install via pip:
```bash
# Basic CPU-only installation
pip install spacial_boxcounting
# With GPU support (NVIDIA CUDA)
pip install spacial_boxcounting[gpu]
# Development installation
pip install -e .
```
Ensure dependencies are installed: numpy, numba, Pillow, matplotlib, hilbertcurve, pandas, and optionally cupy for GPU acceleration.
## Quick Start
### Processing a Single File
```python
from spacial_boxcounting.api import boxcount_from_file, fractal_dimension_from_file
# Get spatial box count map (2D maps of box count ratios and lacunarity)
result_spatial = boxcount_from_file('path/to/your/image.jpg', mode='spatial')
print('Spatial Box Count Map shape:', [r.shape for r in result_spatial])
# Get overall box count & lacunarity
result_single = boxcount_from_file('path/to/your/image.jpg', mode='single')
print('Box Count & Lacunarity:', result_single)
# Compute fractal dimension
fd = fractal_dimension_from_file('path/to/your/image.jpg')
print('Fractal Dimension:', fd)
```
### 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
result_spatial = boxcount_from_array(arr, mode='spatial')
print('Spatial Result shape:', [r.shape for r in result_spatial])
# Single value processing
result_single = boxcount_from_array(arr, mode='single')
print('Single Result:', result_single)
# Fractal dimension
fd = fractal_dimension_from_array(arr)
print('Fractal Dimension:', fd)
```
## Command-Line Interface
Process images directly from the command line:
```bash
# Process a single file
spacial-boxcount single --file path/to/image.jpg --mode spatial
# Process all images in a directory
spacial-boxcount batch --folder path/to/images/ --mode single
# Process with Hilbert curve mapping (for binary files)
spacial-boxcount single --file path/to/data.bin --mode spatial --hilbert
```
## 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
# Process binary file with Hilbert curve mapping
result = boxcount_from_file('data.bin', mode='spatial', hilbert=True)
fd = fractal_dimension_from_file('data.bin', hilbert=True)
```
## GPU Acceleration
If Cupy is installed with CUDA support, GPU accelerated functions will automatically be used:
```python
import numpy as np
from spacial_boxcounting.core import spacialBoxcount_gpu
arr = np.random.randint(0, 256, size=(512, 512)).astype(np.uint8)
# GPU processing for large images (significant speedup)
result_gpu = spacialBoxcount_gpu(arr, iteration=2, MaxValue=256) # box size 8
print('GPU spatial result shape:', [r.shape for r in result_gpu])
```
## Batch Processing
Process multiple images with progress tracking:
```python
from spacial_boxcounting.batch import batch_boxcount
# Process all images in a directory
results = batch_boxcount('path/to/images/', mode='single')
for filename, result in results.items():
print(f'{filename}: {result}')
```
## Performance
Performance varies by hardware and image size:
- **Small images (< 256x256)**: CPU often faster due to GPU overhead
- **Large images (> 512x512)**: GPU provides 2-10x speedup
- **Batch processing**: GPU provides 5-50x speedup for large batches
- **AMD users**: CPU optimization available (ROCm support experimental)
## License
See [LICENSE.txt](LICENSE.txt) for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/spacial-boxcounting-cpu-gpu",
"name": "spacial-boxcounting",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Your Name <your.email@example.com>",
"keywords": "fractal-analysis, box-counting, image-processing, spatial-analysis, gpu-acceleration",
"author": "Your Name",
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/91/60/137e9f653df90beb304c04d935b92271633b8cabed4f274bf5dfb7b5d2da/spacial_boxcounting-0.1.0.tar.gz",
"platform": null,
"description": "# spacial-boxcounting: Spatial Boxcount Algorithm & Fractal Analysis\n\nAn implementation of a spatial boxcount algorithm for fractal analysis, with both CPU and GPU support for accelerated computation.\n\n## Abstract\nThis 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.\n\n## Key Features\n- **Spatial Box Counting**: Produces 2D maps of box count ratios and lacunarity\n- **Fractal Dimension Analysis**: Multi-scale fractal dimension computation\n- **Multiple Processing Modes**: Spatial maps or single-value results\n- **CPU & GPU Support**: Numba JIT compilation and optional CuPy acceleration\n- **Batch Processing**: Process entire directories of images\n- **Multiple Input Formats**: JPEG, BMP, PNG, and binary files\n- **Hilbert Curve Mapping**: Preserves data locality for binary file analysis\n- **Cross-Platform**: Works on Windows, Linux, and macOS (NVIDIA GPU support)\n\n## Installation\nInstall via pip:\n\n```bash\n# Basic CPU-only installation\npip install spacial_boxcounting\n\n# With GPU support (NVIDIA CUDA)\npip install spacial_boxcounting[gpu]\n\n# Development installation\npip install -e .\n```\n\nEnsure dependencies are installed: numpy, numba, Pillow, matplotlib, hilbertcurve, pandas, and optionally cupy for GPU acceleration.\n\n## Quick Start\n### Processing a Single File\n\n```python\nfrom spacial_boxcounting.api import boxcount_from_file, fractal_dimension_from_file\n\n# Get spatial box count map (2D maps of box count ratios and lacunarity)\nresult_spatial = boxcount_from_file('path/to/your/image.jpg', mode='spatial')\nprint('Spatial Box Count Map shape:', [r.shape for r in result_spatial])\n\n# Get overall box count & lacunarity\nresult_single = boxcount_from_file('path/to/your/image.jpg', mode='single')\nprint('Box Count & Lacunarity:', result_single)\n\n# Compute fractal dimension\nfd = fractal_dimension_from_file('path/to/your/image.jpg')\nprint('Fractal Dimension:', fd)\n```\n\n### Processing from a Numpy Array\n\n```python\nimport numpy as np\nfrom spacial_boxcounting.api import boxcount_from_array, fractal_dimension_from_array\n\narr = np.random.randint(0, 256, size=(256, 256)).astype(np.uint8)\n\n# Spatial processing\nresult_spatial = boxcount_from_array(arr, mode='spatial')\nprint('Spatial Result shape:', [r.shape for r in result_spatial])\n\n# Single value processing\nresult_single = boxcount_from_array(arr, mode='single')\nprint('Single Result:', result_single)\n\n# Fractal dimension\nfd = fractal_dimension_from_array(arr)\nprint('Fractal Dimension:', fd)\n```\n\n## Command-Line Interface\nProcess images directly from the command line:\n\n```bash\n# Process a single file\nspacial-boxcount single --file path/to/image.jpg --mode spatial\n\n# Process all images in a directory\nspacial-boxcount batch --folder path/to/images/ --mode single\n\n# Process with Hilbert curve mapping (for binary files)\nspacial-boxcount single --file path/to/data.bin --mode spatial --hilbert\n```\n\n## Hilbert Curve Mapping for Binary Data\nFor binary files, the Hilbert curve mapping preserves data locality when converting 1D data streams to 2D arrays for spatial analysis:\n\n```python\n# Process binary file with Hilbert curve mapping\nresult = boxcount_from_file('data.bin', mode='spatial', hilbert=True)\nfd = fractal_dimension_from_file('data.bin', hilbert=True)\n```\n\n## GPU Acceleration\nIf Cupy is installed with CUDA support, GPU accelerated functions will automatically be used:\n\n```python\nimport numpy as np\nfrom spacial_boxcounting.core import spacialBoxcount_gpu\n\narr = np.random.randint(0, 256, size=(512, 512)).astype(np.uint8)\n# GPU processing for large images (significant speedup)\nresult_gpu = spacialBoxcount_gpu(arr, iteration=2, MaxValue=256) # box size 8\nprint('GPU spatial result shape:', [r.shape for r in result_gpu])\n```\n\n## Batch Processing\nProcess multiple images with progress tracking:\n\n```python\nfrom spacial_boxcounting.batch import batch_boxcount\n\n# Process all images in a directory\nresults = batch_boxcount('path/to/images/', mode='single')\nfor filename, result in results.items():\n print(f'{filename}: {result}')\n```\n\n## Performance\nPerformance varies by hardware and image size:\n- **Small images (< 256x256)**: CPU often faster due to GPU overhead\n- **Large images (> 512x512)**: GPU provides 2-10x speedup\n- **Batch processing**: GPU provides 5-50x speedup for large batches\n- **AMD users**: CPU optimization available (ROCm support experimental)\n\n## License\nSee [LICENSE.txt](LICENSE.txt) for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Convenient package for spatial box counting and fractal analysis across data types with CPU and GPU support",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/yourusername/spacial-boxcounting-cpu-gpu/issues",
"Documentation": "https://github.com/yourusername/spacial-boxcounting-cpu-gpu#readme",
"Homepage": "https://github.com/yourusername/spacial-boxcounting-cpu-gpu",
"Repository": "https://github.com/yourusername/spacial-boxcounting-cpu-gpu",
"Source Code": "https://github.com/yourusername/spacial-boxcounting-cpu-gpu"
},
"split_keywords": [
"fractal-analysis",
" box-counting",
" image-processing",
" spatial-analysis",
" gpu-acceleration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f7f2719b95e361b6934063cbf67742aa1d98803c9c9b99dacfa4e26e5faeddcb",
"md5": "9e9f706a5881853ee6e22010601db05c",
"sha256": "3a17b54b600807d99ef1eac814367533aef22f301d48cb750a09263e27ffa8e0"
},
"downloads": -1,
"filename": "spacial_boxcounting-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e9f706a5881853ee6e22010601db05c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14846,
"upload_time": "2025-08-04T19:38:04",
"upload_time_iso_8601": "2025-08-04T19:38:04.139775Z",
"url": "https://files.pythonhosted.org/packages/f7/f2/719b95e361b6934063cbf67742aa1d98803c9c9b99dacfa4e26e5faeddcb/spacial_boxcounting-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9160137e9f653df90beb304c04d935b92271633b8cabed4f274bf5dfb7b5d2da",
"md5": "155795a20747f06bb218865d60efcbf3",
"sha256": "ecce7ecdf6ba5e046b63a180f611b41b07e3e7a806a4c6abc875e65ac5807a56"
},
"downloads": -1,
"filename": "spacial_boxcounting-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "155795a20747f06bb218865d60efcbf3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15312,
"upload_time": "2025-08-04T19:38:05",
"upload_time_iso_8601": "2025-08-04T19:38:05.698228Z",
"url": "https://files.pythonhosted.org/packages/91/60/137e9f653df90beb304c04d935b92271633b8cabed4f274bf5dfb7b5d2da/spacial_boxcounting-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 19:38:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "spacial-boxcounting-cpu-gpu",
"github_not_found": true,
"lcname": "spacial-boxcounting"
}
JSON
