| Name | astrosr JSON |
| Version |
1.0.4
JSON |
| download |
| home_page | None |
| Summary | Astronomical super-resolution with drizzle for wide field-of-view images |
| upload_time | 2025-10-14 11:14:29 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2025 Gabriel Ferrer
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 |
astronomy
astrophysics
drizzle
super-resolution
fits
wcs
image-processing
scientific-computing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# astroSR: Astronomical Super-Resolution with Drizzle Algorithm
[](https://github.com/dot-gabriel-ferrer/astroSR/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/astrosr/)
[](https://codecov.io/gh/dot-gabriel-ferrer/astroSR)
## Overview
astroSR implements the Drizzle algorithm (Fruchter & Hook, 2002) for astronomical image combination and super-resolution reconstruction. The package provides precise photometric flux conservation through pixel-to-pixel mapping with configurable overlap area calculations, enabling resolution enhancement beyond the native pixel scale of input images.
## Key Features
- **Faithful Drizzle Implementation**: Complete implementation of the Fruchter & Hook (2002) algorithm with exact flux conservation
- **Resolution Enhancement**: Achieves spatial resolution improvement through optimal dithering pattern exploitation
- **Flexible Weighting**: Supports per-image weighting based on exposure time, image quality, or other metrics
- **Multiple Kernel Types**: Square, Gaussian, and tophat kernels for different reconstruction requirements
- **WCS Support**: Full World Coordinate System handling for precise geometric transformations
- **Noise Control**: Configurable pixel fraction parameter for noise correlation management
## Theoretical Background
The achievable resolution gain depends on:
- Number of input images and their dithering pattern
- Alignment precision and point spread function characteristics
- Signal-to-noise ratio of individual exposures
For well-dithered observations, the effective resolution improvement typically ranges from 1.5× to 3× the native pixel scale, with optimal results achieved using 4-9 input images.
## Installation
### From PyPI (Recommended)
```bash
pip install astrosr
```
### From Source
```bash
git clone https://github.com/dot-gabriel-ferrer/astroSR.git
cd astroSR
pip install .
```
### Development Installation
```bash
git clone https://github.com/dot-gabriel-ferrer/astroSR.git
cd astroSR
pip install -e .[dev]
```
## Requirements
- Python ≥ 3.9
- NumPy ≥ 1.20.0
- Astropy ≥ 6.0
- SciPy ≥ 1.7.0
- Matplotlib ≥ 3.5.0
- DrizzlePac ≥ 3.6.0
## Usage
### Command Line Interface
Basic usage for combining dithered images:
```bash
astrosr \
--input img1.fits img2.fits img3.fits img4.fits \
--output combined.fits \
--scale-factor 2.0 \
--pixfrac 0.8
```
Advanced usage with custom weighting:
```bash
astrosr \
--input obs1.fits obs2.fits obs3.fits \
--output result.fits \
--scale-factor 2.0 \
--pixfrac 0.8 \
--weights 1.0 2.0 1.5 \
--kernel gaussian \
--save-weight-map
```
### Python API
```python
from astrosr import drizzle_super_resolution
# Basic combination
drizzle_super_resolution(
input_files=['img1.fits', 'img2.fits', 'img3.fits', 'img4.fits'],
output_file='superres.fits',
scale_factor=2.0,
pixfrac=0.8
)
# Advanced configuration
result = drizzle_super_resolution(
input_files=['obs1.fits', 'obs2.fits', 'obs3.fits'],
output_file='output.fits',
scale_factor=2.0,
pixfrac=0.8,
weights=[1.0, 1.2, 0.8],
kernel='gaussian',
pixel_scale=0.5, # arcsec/pixel
save_weight_map=True,
preserve_flux=True
)
```
## Parameters
| Parameter | Type | Default | Description |
| ------------------- | ----- | -------- | ------------------------------------------- |
| `input_files` | list | - | List of input FITS files |
| `output_file` | str | - | Output FITS filename |
| `scale_factor` | float | 2.0 | Resolution improvement factor |
| `pixfrac` | float | 0.8 | Drizzle pixel fraction (0.6-1.0) |
| `kernel` | str | 'square' | Kernel type: 'square', 'gaussian', 'tophat' |
| `weights` | list | None | Per-image weights |
| `pixel_scale` | float | auto | Output pixel scale (arcsec/pixel) |
| `save_weight_map` | bool | False | Save weight map alongside output |
## Applications
### Dithered Observations
Combine multiple exposures with sub-pixel offsets to achieve super-resolution:
```python
drizzle_super_resolution(
input_files=['dither_01.fits', 'dither_02.fits', 'dither_03.fits', 'dither_04.fits'],
output_file='superres.fits',
scale_factor=2.0
)
```
### Quality-Weighted Combination
Weight images by exposure time or image quality:
```python
drizzle_super_resolution(
input_files=['short_exp.fits', 'long_exp.fits'],
output_file='weighted.fits',
weights=[1.0, 3.0], # 3x weight for longer exposure
scale_factor=1.8
)
```
### Mosaic Construction
Combine overlapping fields into a unified high-resolution image:
```python
drizzle_super_resolution(
input_files=['field_a.fits', 'field_b.fits', 'field_c.fits'],
output_file='mosaic.fits',
scale_factor=1.5
)
```
## Validation and Testing
The implementation has been validated for:
- Photometric accuracy (< 1% flux conservation error)
- Geometric precision in coordinate transformations
- Proper handling of NaN pixels and image boundaries
- Resolution enhancement verification
Comprehensive test suite available in `tests/` directory.
## Documentation
- [Usage Guide](docs/usage.md) - Detailed examples and parameter descriptions
- [Algorithm Reference](docs/algorithm.md) - Mathematical foundations and implementation details
- [API Documentation](docs/api.md) - Complete function reference
## Scientific References
1. Fruchter, A. S., & Hook, R. N. (2002). Drizzle: A method for the linear reconstruction of undersampled images. *Publications of the Astronomical Society of the Pacific*, 114(792), 144-152. https://doi.org/10.1086/338393
2. Gonzaga, S., et al. (2012). *The DrizzlePac Handbook*. Space Telescope Science Institute.
3. Koekemoer, A. M., et al. (2003). *HST Dither Handbook*. Space Telescope Science Institute.
4. Fruchter, A. S., et al. (2016). The panchromatic Hubble Andromeda Treasury. *Astrophysical Journal*, 83(1), 6. https://doi.org/10.3847/0004-637X/83/1/6
## Project Structure
```
astrosr/
├── src/astrosr/
│ ├── __init__.py
│ └── drizzle_super_resolution.py
├── tests/
│ └── test_drizzle_super_resolution.py
├── scripts/
│ ├── run_drizzle.py
│ └── batch_drizzle.py
├── docs/
│ ├── usage.md
│ ├── algorithm.md
│ └── api.md
├── examples/
│ ├── demo_drizzle.py
│ └── README.md
├── pyproject.toml
└── README.md
```
## Contributing
Contributions are welcome. Please follow these guidelines:
1. Fork the repository
2. Create a feature branch from `main`
3. Implement changes with comprehensive tests
4. Ensure all tests pass and documentation is updated
5. Submit a pull request with detailed description
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Citation
If you use astroSR in your research, please cite:
```
Ferrer Jorge, E. Gabriel (2025). astroSR: Astronomical Super-Resolution with Drizzle Algorithm [Computer software]. https://github.com/dot-gabriel-ferrer/astroSR
```
## Contact
**Elías Gabriel Ferrer Jorge**
Email: gabrielferrerjorge@gmail.com
GitHub: [dot-gabriel-ferrer](https://github.com/dot-gabriel-ferrer)
## Acknowledgments
- Original Drizzle algorithm: Andrew Fruchter and Richard Hook (Space Telescope Science Institute)
- DrizzlePac reference implementation: Space Telescope Science Institute
- Astropy community for astronomical Python ecosystem
Raw data
{
"_id": null,
"home_page": null,
"name": "astrosr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "El\u00edas Gabriel Ferrer Jorge <gabrielferrerjorge@gmail.com>",
"keywords": "astronomy, astrophysics, drizzle, super-resolution, fits, wcs, image-processing, scientific-computing",
"author": null,
"author_email": "El\u00edas Gabriel Ferrer Jorge <gabrielferrerjorge@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a3/51/1ea9082fe2a0af7991fb484413836fac32cc7f6c165e3bac0ab40a6a0b16/astrosr-1.0.4.tar.gz",
"platform": null,
"description": "# astroSR: Astronomical Super-Resolution with Drizzle Algorithm\n\n[](https://github.com/dot-gabriel-ferrer/astroSR/actions/workflows/ci.yml)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/astrosr/)\n[](https://codecov.io/gh/dot-gabriel-ferrer/astroSR)\n\n## Overview\n\nastroSR implements the Drizzle algorithm (Fruchter & Hook, 2002) for astronomical image combination and super-resolution reconstruction. The package provides precise photometric flux conservation through pixel-to-pixel mapping with configurable overlap area calculations, enabling resolution enhancement beyond the native pixel scale of input images.\n\n## Key Features\n\n- **Faithful Drizzle Implementation**: Complete implementation of the Fruchter & Hook (2002) algorithm with exact flux conservation\n- **Resolution Enhancement**: Achieves spatial resolution improvement through optimal dithering pattern exploitation\n- **Flexible Weighting**: Supports per-image weighting based on exposure time, image quality, or other metrics\n- **Multiple Kernel Types**: Square, Gaussian, and tophat kernels for different reconstruction requirements\n- **WCS Support**: Full World Coordinate System handling for precise geometric transformations\n- **Noise Control**: Configurable pixel fraction parameter for noise correlation management\n\n## Theoretical Background\n\nThe achievable resolution gain depends on:\n\n- Number of input images and their dithering pattern\n- Alignment precision and point spread function characteristics\n- Signal-to-noise ratio of individual exposures\n\nFor well-dithered observations, the effective resolution improvement typically ranges from 1.5\u00d7 to 3\u00d7 the native pixel scale, with optimal results achieved using 4-9 input images.\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install astrosr\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/dot-gabriel-ferrer/astroSR.git\ncd astroSR\npip install .\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/dot-gabriel-ferrer/astroSR.git\ncd astroSR\npip install -e .[dev]\n```\n\n## Requirements\n\n- Python \u2265 3.9\n- NumPy \u2265 1.20.0\n- Astropy \u2265 6.0\n- SciPy \u2265 1.7.0\n- Matplotlib \u2265 3.5.0\n- DrizzlePac \u2265 3.6.0\n\n## Usage\n\n### Command Line Interface\n\nBasic usage for combining dithered images:\n\n```bash\nastrosr \\\n --input img1.fits img2.fits img3.fits img4.fits \\\n --output combined.fits \\\n --scale-factor 2.0 \\\n --pixfrac 0.8\n```\n\nAdvanced usage with custom weighting:\n\n```bash\nastrosr \\\n --input obs1.fits obs2.fits obs3.fits \\\n --output result.fits \\\n --scale-factor 2.0 \\\n --pixfrac 0.8 \\\n --weights 1.0 2.0 1.5 \\\n --kernel gaussian \\\n --save-weight-map\n```\n\n### Python API\n\n```python\nfrom astrosr import drizzle_super_resolution\n\n# Basic combination\ndrizzle_super_resolution(\n input_files=['img1.fits', 'img2.fits', 'img3.fits', 'img4.fits'],\n output_file='superres.fits',\n scale_factor=2.0,\n pixfrac=0.8\n)\n\n# Advanced configuration\nresult = drizzle_super_resolution(\n input_files=['obs1.fits', 'obs2.fits', 'obs3.fits'],\n output_file='output.fits',\n scale_factor=2.0,\n pixfrac=0.8,\n weights=[1.0, 1.2, 0.8],\n kernel='gaussian',\n pixel_scale=0.5, # arcsec/pixel\n save_weight_map=True,\n preserve_flux=True\n)\n```\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n| ------------------- | ----- | -------- | ------------------------------------------- |\n| `input_files` | list | - | List of input FITS files |\n| `output_file` | str | - | Output FITS filename |\n| `scale_factor` | float | 2.0 | Resolution improvement factor |\n| `pixfrac` | float | 0.8 | Drizzle pixel fraction (0.6-1.0) |\n| `kernel` | str | 'square' | Kernel type: 'square', 'gaussian', 'tophat' |\n| `weights` | list | None | Per-image weights |\n| `pixel_scale` | float | auto | Output pixel scale (arcsec/pixel) |\n| `save_weight_map` | bool | False | Save weight map alongside output |\n\n## Applications\n\n### Dithered Observations\n\nCombine multiple exposures with sub-pixel offsets to achieve super-resolution:\n\n```python\ndrizzle_super_resolution(\n input_files=['dither_01.fits', 'dither_02.fits', 'dither_03.fits', 'dither_04.fits'],\n output_file='superres.fits',\n scale_factor=2.0\n)\n```\n\n### Quality-Weighted Combination\n\nWeight images by exposure time or image quality:\n\n```python\ndrizzle_super_resolution(\n input_files=['short_exp.fits', 'long_exp.fits'],\n output_file='weighted.fits',\n weights=[1.0, 3.0], # 3x weight for longer exposure\n scale_factor=1.8\n)\n```\n\n### Mosaic Construction\n\nCombine overlapping fields into a unified high-resolution image:\n\n```python\ndrizzle_super_resolution(\n input_files=['field_a.fits', 'field_b.fits', 'field_c.fits'],\n output_file='mosaic.fits',\n scale_factor=1.5\n)\n```\n\n## Validation and Testing\n\nThe implementation has been validated for:\n\n- Photometric accuracy (< 1% flux conservation error)\n- Geometric precision in coordinate transformations\n- Proper handling of NaN pixels and image boundaries\n- Resolution enhancement verification\n\nComprehensive test suite available in `tests/` directory.\n\n## Documentation\n\n- [Usage Guide](docs/usage.md) - Detailed examples and parameter descriptions\n- [Algorithm Reference](docs/algorithm.md) - Mathematical foundations and implementation details\n- [API Documentation](docs/api.md) - Complete function reference\n\n## Scientific References\n\n1. Fruchter, A. S., & Hook, R. N. (2002). Drizzle: A method for the linear reconstruction of undersampled images. *Publications of the Astronomical Society of the Pacific*, 114(792), 144-152. https://doi.org/10.1086/338393\n2. Gonzaga, S., et al. (2012). *The DrizzlePac Handbook*. Space Telescope Science Institute.\n3. Koekemoer, A. M., et al. (2003). *HST Dither Handbook*. Space Telescope Science Institute.\n4. Fruchter, A. S., et al. (2016). The panchromatic Hubble Andromeda Treasury. *Astrophysical Journal*, 83(1), 6. https://doi.org/10.3847/0004-637X/83/1/6\n\n## Project Structure\n\n```\nastrosr/\n\u251c\u2500\u2500 src/astrosr/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 drizzle_super_resolution.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_drizzle_super_resolution.py\n\u251c\u2500\u2500 scripts/\n\u2502 \u251c\u2500\u2500 run_drizzle.py\n\u2502 \u2514\u2500\u2500 batch_drizzle.py\n\u251c\u2500\u2500 docs/\n\u2502 \u251c\u2500\u2500 usage.md\n\u2502 \u251c\u2500\u2500 algorithm.md\n\u2502 \u2514\u2500\u2500 api.md\n\u251c\u2500\u2500 examples/\n\u2502 \u251c\u2500\u2500 demo_drizzle.py\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 README.md\n```\n\n## Contributing\n\nContributions are welcome. Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch from `main`\n3. Implement changes with comprehensive tests\n4. Ensure all tests pass and documentation is updated\n5. Submit a pull request with detailed description\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use astroSR in your research, please cite:\n\n```\nFerrer Jorge, E. Gabriel (2025). astroSR: Astronomical Super-Resolution with Drizzle Algorithm [Computer software]. https://github.com/dot-gabriel-ferrer/astroSR\n```\n\n## Contact\n\n**El\u00edas Gabriel Ferrer Jorge**\nEmail: gabrielferrerjorge@gmail.com\nGitHub: [dot-gabriel-ferrer](https://github.com/dot-gabriel-ferrer)\n\n## Acknowledgments\n\n- Original Drizzle algorithm: Andrew Fruchter and Richard Hook (Space Telescope Science Institute)\n- DrizzlePac reference implementation: Space Telescope Science Institute\n- Astropy community for astronomical Python ecosystem\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Gabriel Ferrer\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.\n ",
"summary": "Astronomical super-resolution with drizzle for wide field-of-view images",
"version": "1.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/dot-gabriel-ferrer/astroSR/issues",
"Changelog": "https://github.com/dot-gabriel-ferrer/astroSR/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/dot-gabriel-ferrer/astroSR#readme",
"Homepage": "https://github.com/dot-gabriel-ferrer/astroSR",
"Repository": "https://github.com/dot-gabriel-ferrer/astroSR"
},
"split_keywords": [
"astronomy",
" astrophysics",
" drizzle",
" super-resolution",
" fits",
" wcs",
" image-processing",
" scientific-computing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b51870f9d52ba365d9f242c19119f8e691298cd9d62a463a1a5326a6674691c",
"md5": "3087591e33fa86f04d87b9336ca19dbc",
"sha256": "2e0325809949ee90f9c734e42a07d5c536a4bacd2b629c4c7c4f362a4af00969"
},
"downloads": -1,
"filename": "astrosr-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3087591e33fa86f04d87b9336ca19dbc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14562,
"upload_time": "2025-10-14T11:14:28",
"upload_time_iso_8601": "2025-10-14T11:14:28.458051Z",
"url": "https://files.pythonhosted.org/packages/4b/51/870f9d52ba365d9f242c19119f8e691298cd9d62a463a1a5326a6674691c/astrosr-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a3511ea9082fe2a0af7991fb484413836fac32cc7f6c165e3bac0ab40a6a0b16",
"md5": "19f42cf457f18f6363235913b85b5c5e",
"sha256": "007e22c0691690edd1c71077fda3fc0a6a94d9aceeb00d5a4d7f6d797c8bd056"
},
"downloads": -1,
"filename": "astrosr-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "19f42cf457f18f6363235913b85b5c5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 27719,
"upload_time": "2025-10-14T11:14:29",
"upload_time_iso_8601": "2025-10-14T11:14:29.607357Z",
"url": "https://files.pythonhosted.org/packages/a3/51/1ea9082fe2a0af7991fb484413836fac32cc7f6c165e3bac0ab40a6a0b16/astrosr-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 11:14:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dot-gabriel-ferrer",
"github_project": "astroSR",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "astrosr"
}
