# StarsAlign - A package developed for aligning and comparing high density astronomical images with extreme precision
StarsAlign is a tool for aligning and comparing astronomical images using the Scale-Invariant Feature Transform (SIFT) algorithm and FLANN based matcher.
It contains functions such as ```fast_align()``` and ```fast_diff()``` that aligns and compute the difference of two single channel images.
The package also contains ```align()``` and ```diff()``` functions for extreme precision, but they may require more resources.
Another useful tool of this package is the ```normalize()``` function, wich normalize the image by subtracting the mean from all pixels of the image and then dividing by the standard deviation. This can be useful in cases where the images have different brightness levels.
Examples of this package usage can be found inside the folder: https://github.com/nagonzalezf/starsalign/tree/main/examples
| Reference Image | Science Image | Raw Difference Image |
| ------------- | ------------- | ------------- |
| <img src="https://i.ibb.co/hDQhcy7/001-ref-image.png" width="240"> | <img src="https://i.ibb.co/kmGznJg/002-science-image.png" width="240"> | <img src="https://i.ibb.co/LPXqhCy/003-raw-diff-image.png" width="240"> |
| Reference Image | Aligned Science Image | Aligned Difference Image |
| ------------- | ------------- | ------------- |
| <img src="https://i.ibb.co/hDQhcy7/001-ref-image.png" width="240"> | <img src="https://i.ibb.co/CtHtLbb/004-aligned-image.png" width="240"> | <img src="https://i.ibb.co/vPs7zLD/005-diff-image.png" width="240"> |
### Important ###
Functions ```fast_align()``` and ```fast_diff()``` were specifically designed to work with images that have a high amount of information, such as 4096x2048 pixels, with float32 data type, and a range of values between -40000 and 40000.
It is recommended to use the ```align()``` and ```diff()``` functions on lower resolution or lower density images, but it may result in prolonged waiting times for bigger images.
# Installation
Using pip:
```bash
pip install starsalign
```
Using ```setup.py``` file from root directory
```bash
python setup.py install
```
# Examples
Getting the aligned science image using ```fast_align()``` function (faster method)
```
>>> import starsalign as sa
>>> aligned_image = sa.fast_align(ref_image, science_image)
```
Getting the aligned difference image with a more precise alignment using ```diff()``` function (slower but more accurate)
```
>>> import starsalign as sa
>>> aligned_difference_image = sa.diff(ref_image, science_image)
```
# Supported input formats
By default the package is intended to be use over **float 32** single channel images of wide range, but it can also process other formats such as **uint8** images or even binary images.
The ```fast_align()``` and ```fast_diff()``` functions will only support single channel images.
If you want to process multi channel images you have two options:
1. You can use the ```align()``` and ```diff()``` functions, these will automatically get rid of the multi channels and perform the calculations over temporary buffer single channel images to finally process and extract the original multi channel images as output.
2. You can get rid of the extra channels yourself performing some pre-processing tasks such as opencv ```cvtColor()``` functions for color space conversions or similar methods and then process the images using the ```fast_align()``` and ```fast_diff()``` functions.
# Difference Image Analysis (DIA) application examples
The main idea behind this technique is to subtract two images of the same portion of the sky, removing all photometrically stable stars, but tipically this images are not aligned by default.
## Example 1 - ```fast_align()``` & ```fast_diff()``` functions
We are working over two wide-range float32 images of the NGC6569 globular cluster in the constellation Sagittarius. These images were captured using the Dark Energy Camera (DECam) instrument of the Victor M. Blanco 4-meter Telescope at the Cerro Tololo Inter-American Observatory (CTIO) in the Chilean Andes. They were pre-processed using the data reduction pipelines developed by the Rubin Observatory (LSST pipelines).
| Reference Image | Science Image | Raw Difference Image |
| ------------- | ------------- | ------------- |
| <img src="https://i.ibb.co/bQsdzKh/001-ref-image.png" width="240"> | <img src="https://i.ibb.co/R7z22P0/002-science-image.png" width="240"> | <img src="https://i.ibb.co/9yPDhMk/003-raw-diff-image.png" width="240"> |
The reference and science images are not aligned, so the raw difference results are incorrect.
We process the image using ```fast_align()``` and ```fast_diff()``` functions (faster method):
```
>>> import starsalign as sa
>>> aligned_image = sa.fast_align(ref_image, science_image)
>>> aligned_difference_image = sa.fast_diff(ref_image, science_image)
```
And we get the desired difference result:
| Reference Image | Aligned Science Image | Aligned Difference Image |
| ------------- | ------------- | ------------- |
| <img src="https://i.ibb.co/bQsdzKh/001-ref-image.png" width="240"> | <img src="https://i.ibb.co/d49V0Zc/004-aligned-image.png" width="240"> | <img src="https://i.ibb.co/GCy1qKc/005-diff-image.png" width="240"> |
### Note: ###
This results were obtained using the lsst.dirac.dev resources (CPU, RAM) and they were calculated in about 8 seconds. If we perform the proccesing under the same conditions using ```align()``` and ```diff()``` functions, then it takes about 20 minutes to complete and we get a slightly more accurate x and y displacement value calculations.
The source float32 images used for this examples can be found at:
https://github.com/nagonzalezf/starsalign/blob/main/examples/ref_image.npy
https://github.com/nagonzalezf/starsalign/blob/main/examples/science_image.npy
# Documentation
Documentation is under construction, in the meantime you can check:
SIFT algorithm docs at: https://docs.opencv.org/4.x/da/df5/tutorial_py_sift_intro.html
FLANN feature matcher docs at: https://docs.opencv.org/4.x/d5/d6f/tutorial_feature_flann_matcher.html
Raw data
{
"_id": null,
"home_page": "https://github.com/nagonzalezf/starsalign",
"name": "starsalign",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "align alignment alignment-algorithm astro astronomy astronomical-images astrophysics displacement-estimation difference-image-analysis flann-matchers galaxies image-processing image-subtraction keypoint-detection numpy opencv sift-algorithm stars starsalign",
"author": "Nicolas Antonio Gonzalez Figueroa",
"author_email": "nagonzalezf@ing.ucsc.cl",
"download_url": "https://files.pythonhosted.org/packages/7e/a7/b6c8635c2a1c35a703b32123419158212c8fe007aec8cb539fb61dfcd3e9/starsalign-1.1.0.tar.gz",
"platform": null,
"description": "# StarsAlign - A package developed for aligning and comparing high density astronomical images with extreme precision\n\nStarsAlign is a tool for aligning and comparing astronomical images using the Scale-Invariant Feature Transform (SIFT) algorithm and FLANN based matcher.\n\nIt contains functions such as ```fast_align()``` and ```fast_diff()``` that aligns and compute the difference of two single channel images.\n\nThe package also contains ```align()``` and ```diff()``` functions for extreme precision, but they may require more resources.\n\nAnother useful tool of this package is the ```normalize()``` function, wich normalize the image by subtracting the mean from all pixels of the image and then dividing by the standard deviation. This can be useful in cases where the images have different brightness levels.\n\nExamples of this package usage can be found inside the folder: https://github.com/nagonzalezf/starsalign/tree/main/examples\n\n| Reference Image | Science Image | Raw Difference Image |\n| ------------- | ------------- | ------------- |\n| <img src=\"https://i.ibb.co/hDQhcy7/001-ref-image.png\" width=\"240\"> | <img src=\"https://i.ibb.co/kmGznJg/002-science-image.png\" width=\"240\"> | <img src=\"https://i.ibb.co/LPXqhCy/003-raw-diff-image.png\" width=\"240\"> |\n\n| Reference Image | Aligned Science Image | Aligned Difference Image |\n| ------------- | ------------- | ------------- |\n| <img src=\"https://i.ibb.co/hDQhcy7/001-ref-image.png\" width=\"240\"> | <img src=\"https://i.ibb.co/CtHtLbb/004-aligned-image.png\" width=\"240\"> | <img src=\"https://i.ibb.co/vPs7zLD/005-diff-image.png\" width=\"240\"> |\n\n### Important ###\n\nFunctions ```fast_align()``` and ```fast_diff()``` were specifically designed to work with images that have a high amount of information, such as 4096x2048 pixels, with float32 data type, and a range of values between -40000 and 40000.\n\nIt is recommended to use the ```align()``` and ```diff()``` functions on lower resolution or lower density images, but it may result in prolonged waiting times for bigger images.\n\n# Installation\n\nUsing pip:\n\n```bash\npip install starsalign\n```\n\nUsing ```setup.py``` file from root directory\n\n```bash\npython setup.py install\n```\n# Examples\n\nGetting the aligned science image using ```fast_align()``` function (faster method)\n```\n>>> import starsalign as sa\n>>> aligned_image = sa.fast_align(ref_image, science_image)\n```\n\nGetting the aligned difference image with a more precise alignment using ```diff()``` function (slower but more accurate)\n```\n>>> import starsalign as sa\n>>> aligned_difference_image = sa.diff(ref_image, science_image)\n```\n# Supported input formats\n\nBy default the package is intended to be use over **float 32** single channel images of wide range, but it can also process other formats such as **uint8** images or even binary images.\n\nThe ```fast_align()``` and ```fast_diff()``` functions will only support single channel images.\n\nIf you want to process multi channel images you have two options:\n\n1. You can use the ```align()``` and ```diff()``` functions, these will automatically get rid of the multi channels and perform the calculations over temporary buffer single channel images to finally process and extract the original multi channel images as output.\n\n2. You can get rid of the extra channels yourself performing some pre-processing tasks such as opencv ```cvtColor()``` functions for color space conversions or similar methods and then process the images using the ```fast_align()``` and ```fast_diff()``` functions.\n\n# Difference Image Analysis (DIA) application examples\n\nThe main idea behind this technique is to subtract two images of the same portion of the sky, removing all photometrically stable stars, but tipically this images are not aligned by default.\n\n## Example 1 - ```fast_align()``` & ```fast_diff()``` functions\n\nWe are working over two wide-range float32 images of the NGC6569 globular cluster in the constellation Sagittarius. These images were captured using the Dark Energy Camera (DECam) instrument of the Victor M. Blanco 4-meter Telescope at the Cerro Tololo Inter-American Observatory (CTIO) in the Chilean Andes. They were pre-processed using the data reduction pipelines developed by the Rubin Observatory (LSST pipelines).\n\n| Reference Image | Science Image | Raw Difference Image |\n| ------------- | ------------- | ------------- |\n| <img src=\"https://i.ibb.co/bQsdzKh/001-ref-image.png\" width=\"240\"> | <img src=\"https://i.ibb.co/R7z22P0/002-science-image.png\" width=\"240\"> | <img src=\"https://i.ibb.co/9yPDhMk/003-raw-diff-image.png\" width=\"240\"> |\n\nThe reference and science images are not aligned, so the raw difference results are incorrect.\n\nWe process the image using ```fast_align()``` and ```fast_diff()``` functions (faster method):\n\n```\n>>> import starsalign as sa\n>>> aligned_image = sa.fast_align(ref_image, science_image)\n>>> aligned_difference_image = sa.fast_diff(ref_image, science_image)\n```\nAnd we get the desired difference result:\n\n| Reference Image | Aligned Science Image | Aligned Difference Image |\n| ------------- | ------------- | ------------- |\n| <img src=\"https://i.ibb.co/bQsdzKh/001-ref-image.png\" width=\"240\"> | <img src=\"https://i.ibb.co/d49V0Zc/004-aligned-image.png\" width=\"240\"> | <img src=\"https://i.ibb.co/GCy1qKc/005-diff-image.png\" width=\"240\"> |\n\n### Note: ###\nThis results were obtained using the lsst.dirac.dev resources (CPU, RAM) and they were calculated in about 8 seconds. If we perform the proccesing under the same conditions using ```align()``` and ```diff()``` functions, then it takes about 20 minutes to complete and we get a slightly more accurate x and y displacement value calculations.\n\nThe source float32 images used for this examples can be found at:\nhttps://github.com/nagonzalezf/starsalign/blob/main/examples/ref_image.npy\nhttps://github.com/nagonzalezf/starsalign/blob/main/examples/science_image.npy\n\n# Documentation\n\nDocumentation is under construction, in the meantime you can check:\n\nSIFT algorithm docs at: https://docs.opencv.org/4.x/da/df5/tutorial_py_sift_intro.html\n\nFLANN feature matcher docs at: https://docs.opencv.org/4.x/d5/d6f/tutorial_feature_flann_matcher.html\n",
"bugtrack_url": null,
"license": "",
"summary": "A package for aligning and comparing astronomical images",
"version": "1.1.0",
"split_keywords": [
"align",
"alignment",
"alignment-algorithm",
"astro",
"astronomy",
"astronomical-images",
"astrophysics",
"",
"",
"",
"",
"",
"",
"",
"",
"displacement-estimation",
"difference-image-analysis",
"flann-matchers",
"galaxies",
"image-processing",
"",
"",
"",
"",
"",
"",
"",
"",
"image-subtraction",
"keypoint-detection",
"numpy",
"opencv",
"sift-algorithm",
"stars",
"starsalign"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50e954cc310c8bfe3d72b8d765ca005276ab388e79fb692ebcbf5ee81ad33fb0",
"md5": "46d11fb2fb43a7816e299ab4d666e0e1",
"sha256": "9c3221c18c8ec4e5fa5e92a3887b427bb7912796513773131157db16a7430cd6"
},
"downloads": -1,
"filename": "starsalign-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46d11fb2fb43a7816e299ab4d666e0e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6788,
"upload_time": "2023-01-17T20:08:51",
"upload_time_iso_8601": "2023-01-17T20:08:51.397061Z",
"url": "https://files.pythonhosted.org/packages/50/e9/54cc310c8bfe3d72b8d765ca005276ab388e79fb692ebcbf5ee81ad33fb0/starsalign-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7ea7b6c8635c2a1c35a703b32123419158212c8fe007aec8cb539fb61dfcd3e9",
"md5": "c2ec065e3b190c09f89ec58f07cdfe64",
"sha256": "7625b4aa182925582664b31c74b5284d8182b04b4a2869dd51ba760474e32b11"
},
"downloads": -1,
"filename": "starsalign-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c2ec065e3b190c09f89ec58f07cdfe64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7076,
"upload_time": "2023-01-17T20:08:53",
"upload_time_iso_8601": "2023-01-17T20:08:53.279105Z",
"url": "https://files.pythonhosted.org/packages/7e/a7/b6c8635c2a1c35a703b32123419158212c8fe007aec8cb539fb61dfcd3e9/starsalign-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-17 20:08:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "nagonzalezf",
"github_project": "starsalign",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "starsalign"
}
JSON
