| Name | focusstacker JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Advanced focus stacking using Laplacian pyramid merging |
| upload_time | 2025-10-06 03:41:09 |
| maintainer | None |
| docs_url | None |
| author | Mohammad Darwish |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2025 FocusStacker Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
computer-vision
focus-stacking
image-processing
photography
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FocusStacker
[](https://www.python.org/downloads/)
[](LICENSE)
**FocusStacker** is a high-performance Python library for advanced focus stacking using Laplacian pyramid merging. It combines multiple images taken at different focus distances to create a single image with extended depth of field.
## Features
- **Advanced Laplacian Pyramid Merging**: Uses sophisticated algorithms for optimal focus stacking
- **SIFT-based Alignment**: Automatic image alignment using Scale-Invariant Feature Transform
- **Memory Efficient**: Optimized for processing large images with minimal memory usage
- **Configurable Parameters**: Fine-tune alignment and blending parameters
- **Resource Monitoring**: Built-in memory and disk space monitoring
- **Comprehensive Error Handling**: Detailed exceptions for debugging
- **Type Safety**: Full type annotations for better development experience
## Installation
### Using pip
```bash
pip install focusstacker
```
### Using uv
```bash
uv add focusstacker
```
## Quick Start
### Basic Usage
```python
from focusstacker import stack_images
# Define your input images
image_paths = [
"images/focus_1.jpg",
"images/focus_2.jpg",
"images/focus_3.jpg"
]
# Stack the images
stack_images(
image_paths=image_paths,
destimation_image_path="output/stacked_image.jpg"
)
```
### Advanced Usage
```python
from focusstacker import stack_images
from focusstacker.common.enums import AlignerChoice, BlenderChoice
stack_images(
image_paths=[
"images/focus_1.jpg",
"images/focus_2.jpg",
"images/focus_3.jpg",
"images/focus_4.jpg"
],
destimation_image_path="output/high_quality_stack.jpg",
aligner=AlignerChoice.SIFT,
blender=BlenderChoice.LAPLACIAN_PYRAMID_BALANCED,
levels=6 # More pyramid levels for higher quality
)
```
## API Reference
### `stack_images()`
The main function for focus stacking.
#### Parameters
- **`image_paths`** (`list[str | Path]`): List of input image paths (2-50 images)
- **`destimation_image_path`** (`str | Path`): Output path for the stacked image
- **`aligner`** (`AlignerChoice`, optional): Alignment algorithm (default: `SIFT`)
- **`blender`** (`BlenderChoice`, optional): Blending algorithm (default: `LAPLACIAN_PYRAMID_BALANCED`)
- **`levels`** (`int`, optional): Number of pyramid levels 3-8 (default: 5)
#### Supported Formats
- **Input**: JPEG (.jpg, .jpeg)
- **Output**: JPEG (.jpg, .jpeg)
## Configuration Options
### Alignment Algorithms
#### SIFT (Scale-Invariant Feature Transform)
- **Best for**: General photography, landscapes, macro
- **Features**: Robust to scale, rotation, and illumination changes
- **Performance**: High accuracy, moderate speed
### Blending Algorithms
#### Laplacian Pyramid Balanced
- **Best for**: Most photography scenarios
- **Features**: Soft blending, natural transitions
- **Performance**: Balanced quality and speed
#### Laplacian Pyramid Max Sharpness
- **Best for**: Technical photography, maximum detail
- **Features**: Aggressive sharpness selection
- **Performance**: Highest detail, slower processing
### Pyramid Levels
- **3-4 levels**: Fast processing, good for previews
- **5-6 levels**: Balanced quality and speed (recommended)
- **7-8 levels**: Highest quality, slower processing
## Error Handling
FocusStacker provides comprehensive error handling with specific exception types:
```python
from focusstacker.common.exceptions import (
FocusStackerValidationException,
FocusStackerAlignmentException,
FocusStackerStackingException,
FocusStackerFileException,
FocusStackerMemoryException
)
try:
stack_images(
image_paths=["img1.jpg", "img2.jpg"],
destimation_image_path="result.jpg"
)
except FocusStackerValidationException as e:
print(f"Validation error: {e}")
except FocusStackerAlignmentException as e:
print(f"Alignment failed: {e}")
except FocusStackerStackingException as e:
print(f"Stacking failed: {e}")
except FocusStackerMemoryException as e:
print(f"Insufficient memory: {e}")
except FocusStackerFileException as e:
print(f"File operation failed: {e}")
```
### Exception Types
- **`FocusStackerValidationException`**: Input validation errors
- **`FocusStackerAlignmentException`**: Image alignment failures
- **`FocusStackerStackingException`**: Blending/stacking failures
- **`FocusStackerFileException`**: File I/O errors
- **`FocusStackerMemoryException`**: Memory/resource issues
- **`FocusStackerImageProcessingException`**: Image processing errors
- **`FocusStackerDirectoryException`**: Directory operation errors
## Best Practices
### Image Preparation
1. **Consistent Lighting**: Use consistent lighting across all images
2. **Stable Camera**: Use a tripod or stable surface
3. **Overlapping Focus**: Ensure focus ranges overlap between images
4. **Image Quality**: Use high-quality, sharp images
5. **File Format**: Use JPEG format for best compatibility
### Performance Optimization
1. **Image Size**: Resize large images before processing if memory is limited
2. **Pyramid Levels**: Use fewer levels for faster processing
3. **Batch Processing**: Process multiple stacks sequentially
4. **Memory Monitoring**: Monitor system resources during processing
## System Requirements
### Minimum Requirements
- Python 3.9+
- 4GB RAM
- 1GB free disk space
### Recommended Requirements
- 8GB+ RAM
- 5GB+ free disk space
- SSD storage for better performance
### Dependencies
- `numpy>=1.24.4`
- `opencv-contrib-python>=4.12.0.88`
- `psutil>=7.1.0`
- `pydantic>=2.11.9`
## Troubleshooting
### Common Issues
#### Memory Errors
```
FocusStackerMemoryException: Insufficient memory
```
**Solution**: Reduce image size or use fewer pyramid levels
#### Alignment Failures
```
FocusStackerAlignmentException: Alignment failed
```
**Solution**: Ensure images have sufficient overlap and features
#### File Access Errors
```
FocusStackerFileException: Could not load image
```
**Solution**: Check file paths and permissions
### Performance Tips
1. **Use SSD storage** for temporary files
2. **Close other applications** during processing
3. **Monitor system resources** with task manager
4. **Use appropriate pyramid levels** for your needs
### Development Setup
```bash
# Clone the repository
git clone https://github.com/yourusername/focus-stacking.git
cd focus-stacking
# Install development dependencies
uv install --dev
# Run tests
uv run pytest
# Run type checking
uv run ty check
# Run linting
uv run ruff check
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- OpenCV for computer vision algorithms
- NumPy for numerical computations
- The focus stacking community for inspiration and feedback
## Changelog
### v0.1.0
- Initial release
- SIFT-based alignment
- Laplacian pyramid blending
- Memory-efficient processing
- Comprehensive error handling
Raw data
{
"_id": null,
"home_page": null,
"name": "focusstacker",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "computer-vision, focus-stacking, image-processing, photography",
"author": "Mohammad Darwish",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c3/d7/7f7c0742e8ebb7508808e1db5cb91981d301443002707cfb7d6b4d32deea/focusstacker-0.1.0.tar.gz",
"platform": null,
"description": "# FocusStacker\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n\n**FocusStacker** is a high-performance Python library for advanced focus stacking using Laplacian pyramid merging. It combines multiple images taken at different focus distances to create a single image with extended depth of field.\n\n## Features\n\n- **Advanced Laplacian Pyramid Merging**: Uses sophisticated algorithms for optimal focus stacking\n- **SIFT-based Alignment**: Automatic image alignment using Scale-Invariant Feature Transform\n- **Memory Efficient**: Optimized for processing large images with minimal memory usage\n- **Configurable Parameters**: Fine-tune alignment and blending parameters\n- **Resource Monitoring**: Built-in memory and disk space monitoring\n- **Comprehensive Error Handling**: Detailed exceptions for debugging\n- **Type Safety**: Full type annotations for better development experience\n\n## Installation\n\n### Using pip\n\n```bash\npip install focusstacker\n```\n\n### Using uv\n\n```bash\nuv add focusstacker\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom focusstacker import stack_images\n\n# Define your input images\nimage_paths = [\n \"images/focus_1.jpg\",\n \"images/focus_2.jpg\", \n \"images/focus_3.jpg\"\n]\n\n# Stack the images\nstack_images(\n image_paths=image_paths,\n destimation_image_path=\"output/stacked_image.jpg\"\n)\n```\n\n### Advanced Usage\n\n```python\nfrom focusstacker import stack_images\nfrom focusstacker.common.enums import AlignerChoice, BlenderChoice\n\nstack_images(\n image_paths=[\n \"images/focus_1.jpg\",\n \"images/focus_2.jpg\",\n \"images/focus_3.jpg\",\n \"images/focus_4.jpg\"\n ],\n destimation_image_path=\"output/high_quality_stack.jpg\",\n aligner=AlignerChoice.SIFT,\n blender=BlenderChoice.LAPLACIAN_PYRAMID_BALANCED,\n levels=6 # More pyramid levels for higher quality\n)\n```\n\n## API Reference\n\n### `stack_images()`\n\nThe main function for focus stacking.\n\n#### Parameters\n\n- **`image_paths`** (`list[str | Path]`): List of input image paths (2-50 images)\n- **`destimation_image_path`** (`str | Path`): Output path for the stacked image\n- **`aligner`** (`AlignerChoice`, optional): Alignment algorithm (default: `SIFT`)\n- **`blender`** (`BlenderChoice`, optional): Blending algorithm (default: `LAPLACIAN_PYRAMID_BALANCED`)\n- **`levels`** (`int`, optional): Number of pyramid levels 3-8 (default: 5)\n\n#### Supported Formats\n\n- **Input**: JPEG (.jpg, .jpeg)\n- **Output**: JPEG (.jpg, .jpeg)\n\n## Configuration Options\n\n### Alignment Algorithms\n\n#### SIFT (Scale-Invariant Feature Transform)\n- **Best for**: General photography, landscapes, macro\n- **Features**: Robust to scale, rotation, and illumination changes\n- **Performance**: High accuracy, moderate speed\n\n### Blending Algorithms\n\n#### Laplacian Pyramid Balanced\n- **Best for**: Most photography scenarios\n- **Features**: Soft blending, natural transitions\n- **Performance**: Balanced quality and speed\n\n#### Laplacian Pyramid Max Sharpness\n- **Best for**: Technical photography, maximum detail\n- **Features**: Aggressive sharpness selection\n- **Performance**: Highest detail, slower processing\n\n### Pyramid Levels\n\n- **3-4 levels**: Fast processing, good for previews\n- **5-6 levels**: Balanced quality and speed (recommended)\n- **7-8 levels**: Highest quality, slower processing\n\n## Error Handling\n\nFocusStacker provides comprehensive error handling with specific exception types:\n\n```python\nfrom focusstacker.common.exceptions import (\n FocusStackerValidationException,\n FocusStackerAlignmentException,\n FocusStackerStackingException,\n FocusStackerFileException,\n FocusStackerMemoryException\n)\n\ntry:\n stack_images(\n image_paths=[\"img1.jpg\", \"img2.jpg\"],\n destimation_image_path=\"result.jpg\"\n )\nexcept FocusStackerValidationException as e:\n print(f\"Validation error: {e}\")\nexcept FocusStackerAlignmentException as e:\n print(f\"Alignment failed: {e}\")\nexcept FocusStackerStackingException as e:\n print(f\"Stacking failed: {e}\")\nexcept FocusStackerMemoryException as e:\n print(f\"Insufficient memory: {e}\")\nexcept FocusStackerFileException as e:\n print(f\"File operation failed: {e}\")\n```\n\n### Exception Types\n\n- **`FocusStackerValidationException`**: Input validation errors\n- **`FocusStackerAlignmentException`**: Image alignment failures\n- **`FocusStackerStackingException`**: Blending/stacking failures\n- **`FocusStackerFileException`**: File I/O errors\n- **`FocusStackerMemoryException`**: Memory/resource issues\n- **`FocusStackerImageProcessingException`**: Image processing errors\n- **`FocusStackerDirectoryException`**: Directory operation errors\n\n## Best Practices\n\n### Image Preparation\n\n1. **Consistent Lighting**: Use consistent lighting across all images\n2. **Stable Camera**: Use a tripod or stable surface\n3. **Overlapping Focus**: Ensure focus ranges overlap between images\n4. **Image Quality**: Use high-quality, sharp images\n5. **File Format**: Use JPEG format for best compatibility\n\n### Performance Optimization\n\n1. **Image Size**: Resize large images before processing if memory is limited\n2. **Pyramid Levels**: Use fewer levels for faster processing\n3. **Batch Processing**: Process multiple stacks sequentially\n4. **Memory Monitoring**: Monitor system resources during processing\n\n## System Requirements\n\n### Minimum Requirements\n- Python 3.9+\n- 4GB RAM\n- 1GB free disk space\n\n### Recommended Requirements\n- 8GB+ RAM\n- 5GB+ free disk space\n- SSD storage for better performance\n\n### Dependencies\n- `numpy>=1.24.4`\n- `opencv-contrib-python>=4.12.0.88`\n- `psutil>=7.1.0`\n- `pydantic>=2.11.9`\n\n## Troubleshooting\n\n### Common Issues\n\n#### Memory Errors\n```\nFocusStackerMemoryException: Insufficient memory\n```\n**Solution**: Reduce image size or use fewer pyramid levels\n\n#### Alignment Failures\n```\nFocusStackerAlignmentException: Alignment failed\n```\n**Solution**: Ensure images have sufficient overlap and features\n\n#### File Access Errors\n```\nFocusStackerFileException: Could not load image\n```\n**Solution**: Check file paths and permissions\n\n### Performance Tips\n\n1. **Use SSD storage** for temporary files\n2. **Close other applications** during processing\n3. **Monitor system resources** with task manager\n4. **Use appropriate pyramid levels** for your needs\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/focus-stacking.git\ncd focus-stacking\n\n# Install development dependencies\nuv install --dev\n\n# Run tests\nuv run pytest\n\n# Run type checking\nuv run ty check\n\n# Run linting\nuv run ruff check\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- OpenCV for computer vision algorithms\n- NumPy for numerical computations\n- The focus stacking community for inspiration and feedback\n\n## Changelog\n\n### v0.1.0\n- Initial release\n- SIFT-based alignment\n- Laplacian pyramid blending\n- Memory-efficient processing\n- Comprehensive error handling\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 FocusStacker Contributors\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Advanced focus stacking using Laplacian pyramid merging",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://medium.com/@mohddarwish/focus-stacking-computer-vision-for-perfectly-sharp-images-a6cdf2f428af",
"Repository": "https://github.com/mdarwish228/FocusStacker"
},
"split_keywords": [
"computer-vision",
" focus-stacking",
" image-processing",
" photography"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "43a8d81349f46158ddfb30abc9334c346685f09b6aaab6cb7566217219a0e329",
"md5": "cc89954d93483a2e9ae7f2faeba67335",
"sha256": "2db39102d5f24971a769208037dd2add19ec3a5195d9cd65c03c44f9ef6514fc"
},
"downloads": -1,
"filename": "focusstacker-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc89954d93483a2e9ae7f2faeba67335",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 31815,
"upload_time": "2025-10-06T03:41:07",
"upload_time_iso_8601": "2025-10-06T03:41:07.930181Z",
"url": "https://files.pythonhosted.org/packages/43/a8/d81349f46158ddfb30abc9334c346685f09b6aaab6cb7566217219a0e329/focusstacker-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c3d77f7c0742e8ebb7508808e1db5cb91981d301443002707cfb7d6b4d32deea",
"md5": "e210887b1187fec2038bb233845c5e90",
"sha256": "c727a48e428a001cc8f253109e499df22f94fcbdaedd4318b34fbe8d10ac9f5b"
},
"downloads": -1,
"filename": "focusstacker-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e210887b1187fec2038bb233845c5e90",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13023297,
"upload_time": "2025-10-06T03:41:09",
"upload_time_iso_8601": "2025-10-06T03:41:09.067048Z",
"url": "https://files.pythonhosted.org/packages/c3/d7/7f7c0742e8ebb7508808e1db5cb91981d301443002707cfb7d6b4d32deea/focusstacker-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 03:41:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mdarwish228",
"github_project": "FocusStacker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "focusstacker"
}
