Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New Features and Improvements to AstroImages #30

Merged
merged 181 commits into from
Jun 15, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
181 commits
Select commit Hold shift + click to select a range
1bf197c
Begin pulling in code for other image packages to support headers.
sefffal Dec 28, 2021
9f80446
Add colormap support to `render`
sefffal Dec 28, 2021
ba8459d
Initial implementation of auto-updating the WCSTransform when headers…
sefffal Dec 28, 2021
29df5c8
Fix plot recipes after struct changes
sefffal Dec 28, 2021
34360e4
Added `percent` limit helper. Maybe this should go in PlotUtils?
sefffal Dec 28, 2021
b675ff3
Allow `percent` to work with `plot` as well as `imshow`
sefffal Dec 28, 2021
056207e
Filling out abstract array interface
sefffal Dec 29, 2021
73d4272
ds9 stretches and imshow edge cases
sefffal Dec 29, 2021
c332a39
Add default stretch option
sefffal Dec 29, 2021
b72b7b0
Add back additional file loading methods
sefffal Dec 29, 2021
65d126e
Rename `imshow` to `imview`
sefffal Dec 29, 2021
5972a7c
Improve documentation
sefffal Dec 30, 2021
f0d7b7f
Better support for `reproject`
sefffal Dec 30, 2021
7ca7ea6
Performance fix for vector indexing
sefffal Dec 30, 2021
2879636
Work around issue introduced for displaying subranges
sefffal Dec 30, 2021
b175aef
Fix for retrieving single elements from an image that happen to be mi…
sefffal Dec 30, 2021
80f7484
Added docstrings
sefffal Dec 30, 2021
747b748
Remove duplicate recipe
sefffal Dec 30, 2021
0c3cf72
export load and save from FileIO
sefffal Dec 30, 2021
f86fcc7
Typo
sefffal Jan 2, 2022
8d237d6
Move from accessing fields directly to getfield to allow future heade…
sefffal Jan 3, 2022
18df410
Add missing WCS-relevant headers
sefffal Jan 3, 2022
3ef9cd0
Temporary patches to other packages for smoother usage
sefffal Jan 3, 2022
ade4206
Verify cmap is valid before setting it as default
sefffal Jan 3, 2022
5920089
WIP on plot recipes
sefffal Jan 3, 2022
b02cacc
Fix getindex for AstroImage of non numerical data
sefffal Jan 3, 2022
b4f0bc8
RGB images should also stay as AstroImages and share headers
sefffal Jan 3, 2022
5d1453c
Forward wcs_stale in calls to similar
sefffal Jan 4, 2022
4161bdd
WIP plot recipes
sefffal Jan 4, 2022
72edafc
Allow compose to work with regular arrays in addition to AstroImages
sefffal Jan 5, 2022
38887ad
Improvements to plot recipes
sefffal Jan 5, 2022
65bf3ce
WIP wcs axes in plots
sefffal Jan 6, 2022
9e9bd1a
Overhaul of WCS ticks
sefffal Jan 7, 2022
07fdbe0
Refactor to create WCS Grid struct
sefffal Jan 8, 2022
747af1a
edge cases 1
sefffal Jan 8, 2022
4be5a04
corner cases 2
sefffal Jan 8, 2022
b8454c7
WCSGrid improvements
sefffal Jan 9, 2022
e48625c
Address more corner cases
sefffal Jan 10, 2022
2d9d378
More corner cases
sefffal Jan 10, 2022
a7b00ae
Adaptively add more grid lines
sefffal Jan 10, 2022
52b78b0
Add easy `plot(img, grid=true)` to show WCSGrid
sefffal Jan 11, 2022
bbaf300
Plot formatting improvements
sefffal Jan 11, 2022
1d629c0
Organize exports
sefffal Jan 11, 2022
0fa711b
Fixed plot recipes for images with unequal sized axes
sefffal Jan 14, 2022
ba8729d
Improved grid annotations
sefffal Jan 14, 2022
e7f478a
RIght align gridlabels
sefffal Jan 14, 2022
21a5299
Add error hint for imview
sefffal Jan 16, 2022
2209269
Organize code
sefffal Jan 16, 2022
e8eb678
Experiment on tracking axes
sefffal Jan 31, 2022
3a4a061
Improving wcs grid calculation code
sefffal Jan 31, 2022
42512f6
Merge branches 'master' and 'master' of https://github.com/sefffal/As…
sefffal Jan 31, 2022
0fc7d9e
Prelim work on tracking indices and slices
sefffal Mar 9, 2022
8096796
Fix copy & similar
sefffal Mar 11, 2022
fbb0d3d
WIP in adapting DimensionalData
sefffal Mar 12, 2022
b6a2164
Continued WIP migrating to DimensionalData
sefffal Mar 13, 2022
a1e3d54
Delete empty file
sefffal Mar 13, 2022
4177b7b
Export some symbols from DimensionalData
sefffal Mar 13, 2022
522ebd0
Store settings in RefValue not Ref (typestability)
sefffal Mar 13, 2022
f6f7a28
Prototype automatic display of complex images
sefffal Mar 13, 2022
2d62d96
Fleshed out pix_to_world implementation
sefffal Mar 14, 2022
2c7eeef
WIP adapting plot recipes
sefffal Mar 14, 2022
3998477
WIP on world_to_pix
sefffal Mar 20, 2022
32f0a12
WIP move to implot recipe
sefffal Mar 20, 2022
43cc672
Fixes for WCS plotting with new DimensionalData approach
sefffal Mar 21, 2022
886d1fd
Allow grid to adapt to fit enough ticks
sefffal Mar 21, 2022
a90b27b
Better handling of empty or all non-finite/missing images
sefffal Mar 21, 2022
2a3f28c
Set title using refdims
sefffal Mar 21, 2022
c2a3826
Improved WCS header support
sefffal Mar 22, 2022
ddaaf06
Better handling of empty HDUs
sefffal Mar 22, 2022
8ec98bb
Cleanup imports
sefffal Mar 22, 2022
44441f2
Support for saving AstroImages, arrays, and tables to FITS.
sefffal Mar 22, 2022
2476fad
Interactive cube manipulation
sefffal Mar 23, 2022
bc0be85
Fix cmap
sefffal Mar 25, 2022
991a1c9
Detect additional WCS headers
sefffal Mar 25, 2022
5740516
Auto display images with missing data
sefffal Mar 25, 2022
a4ca804
Remove interactive cube functionality
sefffal Mar 25, 2022
75e3789
Reduce dependencies
sefffal Mar 25, 2022
0936a47
Fix imview of complex images
sefffal Mar 25, 2022
2973ba5
Support cmap=nothing again
sefffal Mar 25, 2022
9c9db60
Begin work on docs
sefffal Mar 27, 2022
abeff6f
Restructure code layout for methods that extend other packages
sefffal Mar 27, 2022
3472912
Colorbar support
sefffal Mar 27, 2022
6f93c35
Keep AstroImage wrapper after FFT operations
sefffal Mar 27, 2022
86e1c55
Improved plotting support with complex images to match imview
sefffal Mar 27, 2022
6b33e54
Default to more ticks
sefffal Mar 27, 2022
52f254e
default complex colorbar titles
sefffal Mar 27, 2022
f4c2934
Sorted out layouts for combinations of colorbar={true,false} and elty…
sefffal Mar 27, 2022
dbb93f1
Fixed logic for colorbar title
sefffal Mar 27, 2022
41804d4
Allow grid to adapt to fill user's xlims and ylims
sefffal Mar 27, 2022
30d464a
Disable equal aspectratios when...
sefffal Mar 27, 2022
69f1325
Fix `percent` on matrices
sefffal Mar 27, 2022
519b98b
Support for standalone labelled dims...
sefffal Mar 28, 2022
dd21ea2
Improved polquiver
sefffal Mar 29, 2022
28eff9a
Tweaks to polquiver
sefffal Mar 29, 2022
39da97a
Standardize dimensions during loading
sefffal Mar 29, 2022
ffe5f77
Add contrast & bias adjustments after stretch and clip
sefffal Apr 7, 2022
36d9034
Fix coordinate offset from 1 based arrays
sefffal Apr 7, 2022
257c9de
Change percent to a callable struct instead of a closure
sefffal Apr 7, 2022
78f25c4
Ensure overplotting implot works as expected
sefffal Apr 7, 2022
53d8e5e
Support arbitrary color gradients in addition to named colorschemes
sefffal Apr 7, 2022
df520f3
Automatically downscale images before plotting,but maintain correct c…
sefffal Apr 8, 2022
dfbb9f7
Support rendering cubes, vectors using imview. Useful for animations.
sefffal Apr 8, 2022
bc7c66f
Improved support for plotly
sefffal Apr 8, 2022
918db4f
For empty HDUs return a zero dim array of missing.
sefffal Apr 8, 2022
747fcc8
Removed WCS Axes concept in favour of tracking the order of dims insi…
sefffal Apr 10, 2022
68eb2c7
remove wcsdims flag
sefffal Apr 10, 2022
2efd538
Standardize variable names
sefffal Apr 10, 2022
24713ac
Fix readme
sefffal Apr 11, 2022
b91c7ea
Update docs/Project.toml
sefffal Apr 11, 2022
80603d3
Update src/wcs.jl
sefffal Apr 11, 2022
0774e71
Update src/io.jl
sefffal Apr 11, 2022
67d9edf
Update src/plot-recipes.jl
sefffal Apr 11, 2022
c396595
Merge branch 'master' of https://github.com/sefffal/AstroImages.jl
sefffal Apr 11, 2022
ee42cbf
!!! admonitions.
sefffal Apr 11, 2022
e90afa3
Clean up clampednormedview
sefffal Apr 11, 2022
c73adb2
Cleanup Zscale struct
sefffal Apr 11, 2022
5c9d590
Typo
sefffal Apr 11, 2022
4e57573
Add precompile and clean up exports
sefffal Apr 11, 2022
95e2e34
Additional precompile directives
sefffal Apr 11, 2022
6e94d7d
Begin adapting tests and fixing breakages
sefffal Apr 11, 2022
2c51c02
Fixes for categorical (e.g. pol.) dimensions
sefffal Apr 11, 2022
3972fd1
Allow turning grid off with `grid=false`
sefffal Apr 11, 2022
574c51a
Fix precompile
sefffal Apr 11, 2022
a48b4c3
Support multiple wcs
sefffal Apr 11, 2022
9ebb74c
Cleanup exports
sefffal Apr 11, 2022
a65be92
Fix ffts with non-default parameters
sefffal Apr 11, 2022
3767528
Adjust project requirements
sefffal Apr 18, 2022
6204824
Add explicit writefits function for use without FileIO
sefffal Apr 18, 2022
3510ec9
Fallbacks for more FITS keywords encountered in the wild
sefffal Apr 18, 2022
fea17c7
Explicit aspect_ratio=1 for backends that do not have this as a defau…
sefffal Apr 18, 2022
6aa1533
Add `recenter` function
sefffal Apr 18, 2022
5628d29
Symbols aren't iterable
sefffal Apr 18, 2022
9fbf3a4
Trust WCS naxis over length of dims for WCS computations
sefffal Apr 18, 2022
66db70c
Use steps of dims for images.pixelspacing
sefffal Apr 18, 2022
e4d9f0f
Add compat for Interpolations.
sefffal Apr 18, 2022
c4fba11
Revert previous
sefffal Apr 18, 2022
ded071c
Bump version number and add author
sefffal Apr 18, 2022
9500c95
Reproject holding back interpolations
sefffal Apr 18, 2022
f1a5a7a
Skip reproject dependency
sefffal Apr 18, 2022
c6aad34
Fix for empty HDU header access
sefffal Apr 18, 2022
5e9caa1
one -> oneunit
sefffal Apr 25, 2022
5442bfa
one -> oneunit
sefffal Apr 25, 2022
4a4baba
Drop dep on ImageTransformations; swap ImageCore for ImageBase
sefffal Apr 25, 2022
25a9077
Update src/ccd2rgb.jl
sefffal Apr 25, 2022
1c92df9
Update src/AstroImages.jl
sefffal Apr 25, 2022
43f751f
Add platescale option to implot
sefffal Apr 25, 2022
6e8d890
Support rendering to an arbitrary colorant or named color.
sefffal May 22, 2022
e7e7d07
Add composecolors
sefffal May 22, 2022
443bb3b
Merge branch 'master' of https://github.com/sefffal/AstroImages.jl
sefffal May 22, 2022
25d0f59
For cmap=nothing, use a completely linear grayscale colormap instead …
sefffal May 24, 2022
e2ce839
Begin adding tests
sefffal May 24, 2022
2d5fff2
Migrate to Github actions
sefffal May 24, 2022
a978932
Fix test dependencies
sefffal May 24, 2022
cb916f6
Attempt 2 to fix test dependencies
sefffal May 24, 2022
b161d0c
Resolve syntax error in Julia 1.6 by sticking to .& instead of .&&
sefffal May 24, 2022
091e6a5
Stop exporting Between
sefffal May 30, 2022
2647d7a
Improve CI & docs according to @giordano's suggestions
sefffal May 30, 2022
7de1b7f
CI typo
sefffal May 30, 2022
077c1df
Use DemoCards.jl for examples
sefffal May 30, 2022
84efb96
Fix set_cmap!
sefffal May 30, 2022
a507739
cleanup
sefffal May 30, 2022
edc9357
docs WIP
sefffal May 30, 2022
d2431f5
Add keyword argument version of DimensionalData.rebuild
sefffal Jun 2, 2022
edba8f0
Docs WIP
sefffal Jun 2, 2022
bbcff54
Cleanup
sefffal Jun 3, 2022
a967da6
Update README
sefffal Jun 3, 2022
e9dfae0
Project.toml cleanup
sefffal Jun 3, 2022
990c782
Drop `arraydata` in favour of Base.parent for consistency with Dimens…
sefffal Jun 3, 2022
8d25e20
Need to keep UUIDs until registered with FileIO
sefffal Jun 3, 2022
e0fb31e
Turn on deploy
sefffal Jun 3, 2022
ac1771f
Drop accidental electron display dep
sefffal Jun 3, 2022
dd6e349
Turn on docs push_preview
sefffal Jun 3, 2022
2d524f3
Silence printlng from runtests.jl
sefffal Jun 3, 2022
e2e2081
Add doc strings
sefffal Jun 3, 2022
d3ae34f
Docs WIP
sefffal Jun 3, 2022
30b5938
WIP docs
sefffal Jun 3, 2022
e8359ec
First crack at a logo
sefffal Jun 3, 2022
b89f09d
Docs WIP
sefffal Jun 4, 2022
cc218a5
Docs WIP
sefffal Jun 4, 2022
e9a5d0a
Docs WIP
sefffal Jun 5, 2022
383299f
Address review comments
sefffal Jun 15, 2022
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
name: CI
on:
pull_request:
branches:
- master
push:
branches:
- master
tags: '*'
jobs:
test:
name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
version:
- '1.6' # Replace this with the minimum Julia version that your package supports. E.g. if your package requires Julia 1.5 or higher, change this to '1.5'.
- '1' # Leave this line unchanged. '1' will automatically expand to the latest stable 1.x release of Julia.
- 'nightly'
os:
- ubuntu-latest
arch:
- x64
steps:
- uses: actions/checkout@v3
- uses: julia-actions/setup-julia@v1
with:
version: ${{ matrix.version }}
arch: ${{ matrix.arch }}
- uses: julia-actions/cache@v1
- uses: julia-actions/julia-buildpkg@v1
- uses: julia-actions/julia-runtest@v1
- uses: julia-actions/julia-processcoverage@v1
- uses: codecov/codecov-action@v1
with:
file: lcov.info
26 changes: 26 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: Documentation

on:
push:
branches:
- master
tags: '*'
pull_request:

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: julia-actions/setup-julia@latest
with:
version: '1.7'
- name: Install dependencies
run: julia --color=yes --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
- uses: julia-actions/cache@v1
- name: Build and deploy
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
# DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is necessary, I guess

run: julia --color=yes --project=docs/ docs/make.jl

4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,7 @@ Manifest.toml

# test files
/test/data


# built docs
/docs/build
48 changes: 35 additions & 13 deletions Project.toml
Original file line number Diff line number Diff line change
@@ -1,29 +1,51 @@
name = "AstroImages"
uuid = "fe3fc30c-9b16-11e9-1c73-17dabf39f4ad"
authors = ["Mosè Giordano", "Rohit Kumar"]
version = "0.2.0"
authors = ["Mosè Giordano", "Rohit Kumar", "William Thompson"]
version = "0.3.0"

[deps]
AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"
AstroAngles = "5c4adb95-c1fc-4c53-b4ea-2a94080c53d2"
ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
DimensionalData = "0703355e-b756-11e9-17c0-8b28908087d0"
FITSIO = "525bcba6-941b-5504-bd06-fd0dc1a4d2eb"
FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
Interact = "c601a237-2ae4-5e1e-952c-7a85b0c7eef1"
ImageAxes = "2803e5a7-5153-5ecf-9a86-9b4c37f5f5ac"
ImageBase = "c817782e-172a-44cc-b673-b171935fbb9e"
ImageShow = "4e3cecfd-b093-5904-9786-8bbb286a6a31"
MappedArrays = "dbb5928d-eab1-5f90-85c2-b9b0edb7c900"
PlotUtils = "995b91a9-d308-5afd-9ec6-746e21dbc043"
Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
Reproject = "d1dcc2e6-806e-11e9-2897-3f99785db2ae"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you need it, Reproject.jl v0.3.1 allows the latest version of Interpolations.jl

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @giordano! I had just run into that issue.

One thing I am wondering is whether it might be better to have the opposite relationship, with Reproject.jl depending on AstroImages.
What are your thoughts?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reproject.jl was meant to be a small self-contained low-level package for rotating images (much like its Python counterpart). How are you dealing with the rotations?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right now there is nothing that rotates or otherwise transforms images, except for the RGB composite functions that first call reproject.
I was considering separating this out to look something like:

composechannels([
    astroimg1,
    reproject(astroimg2, wcs(astroimg1,1)),
    reproject(astroimg3, wcs(astroimg1,1)),
],   ...)

where composechannels is a shortcut for 0.3 imview(img1, cmap=:reds) .+ 0.3 imview(img1, cmap=:greens) .+ ...

One thing that doesn't yet work is reprojecting one slice of a cube, but it should be possible with all the information now tracked by the AstroImage struct.

Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
WCS = "15f3aee2-9e10-537f-b834-a6fb8bdb944d"
MappedArrays = "dbb5928d-eab1-5f90-85c2-b9b0edb7c900"

[compat]
julia = "^1.0.0"
Reproject = "^0.3.0"
AbstractFFTs = "1.1"
AstroAngles = "0.1"
ColorSchemes = "3.18"
DimensionalData = "^0.20"
FITSIO = "0.16"
FileIO = "1.14"
ImageAxes = "0.6"
ImageBase = "^0.1.5"
ImageShow = "0.3"
MappedArrays = "0.4"
PlotUtils = "1.2"
RecipesBase = "1.2"
Tables = "1.7"
WCS = "0.6"
julia = "^1.6.0"

[extras]
FITSIO = "525bcba6-941b-5504-bd06-fd0dc1a4d2eb"
ImageBase = "c817782e-172a-44cc-b673-b171935fbb9e"
Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
Widgets = "cc8bc4a8-27d6-5769-a93b-9d913e69aa62"
JLD = "4138dd39-2aa7-5051-a626-17a0bb65d9c8"
SHA = "ea8e919c-243c-51af-8825-aaa63cd721ce"
WCS = "15f3aee2-9e10-537f-b834-a6fb8bdb944d"

[targets]
test = ["Test", "Random", "Widgets", "JLD", "SHA"]
test = ["Test", "WCS", "FITSIO", "Random", "Statistics", "ImageBase"]
96 changes: 66 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,32 @@
# AstroImages.jl

| **Build Status** | **Code Coverage** |
|:-----------------------------------------:|:-------------------------------:|
| [![Build Status][travis-img]][travis-url] | [![][coveral-img]][coveral-url] |
| [![Build Status][appvey-img]][appvey-url] | [![][codecov-img]][codecov-url] |
| **Documentation** | **Build Status** | **Code Coverage** |
|:------------------|:-----------------------------------------:|:-------------------------------:|
| [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaastro.github.io/AstroImages.jl/dev/) | ![Build status](https://github.com/JuliaAstro/AstroImages/actions/workflows/ci.yml/badge.svg) | [![][codecov-img]][codecov-url] |

Introduction
------------

`AstroImage.jl` allows you to plot images from an
astronomical [`FITS`](https://en.wikipedia.org/wiki/FITS) file using the
`AstroImages.jl` allows you load and visualize images from a
astronomical [`FITS`](https://en.wikipedia.org/wiki/FITS) files using the
popular [`Images.jl`](https://github.com/JuliaImages/Images.jl)
and [`Plots.jl`](https://github.com/JuliaPlots/Plots.jl) Julia packages.
`AstroImage.jl` uses [`FITSIO.jl`](https://github.com/JuliaAstro/FITSIO.jl) to
`AstroImages.jl` uses [`FITSIO.jl`](https://github.com/JuliaAstro/FITSIO.jl) to
read FITS files.

Installation
------------

`AstroImage.jl` is available for Julia 1.0 and later versions, and can be
`AstroImages.jl` is available for Julia 1.6 and later versions, and can be
installed with [Julia built-in package
manager](https://docs.julialang.org/en/v1/stdlib/Pkg/).

```julia
pkg> add AstroImages
```

You may also need to install `ImageIO.jl` for images to display in certain environments.

Usage
-----

Expand All @@ -35,6 +36,10 @@ After installing the package, you can start using it with
julia> using AstroImages
```

Images will automatically display in many environments, including VS Code, Jupyter, and Pluto.
If you're using a REPL, you may want to install an external viewer like ImageShow.jl, ElectronDisplay.jl,
or ImageInTerminal.jl.

## Reading extensions from FITS file

You can load and read the the first extension of a FITS file with the `load`
Expand All @@ -55,6 +60,8 @@ julia> load("file.fits", 3)
[...]
```

If unspecified, the first image HDU will be loaded.

## AstroImage type

The package provides a new type, `AstroImage` to integrate FITS images with
Expand All @@ -63,31 +70,52 @@ the same syntax as `load`. This command:

```julia
julia> img = AstroImage("file.fits")
AstroImages.AstroImage{UInt16,ColorTypes.Gray,1,Float64}[...]
```

will read the first valid extension from the `file.fits` file and wrap its content in
a `NTuple{N, Matrix{Gray}}`, that can be easily used with `Images.jl` and related packages.
will read the first valid extension from the `file.fits` file.

If you are working in a Jupyter notebook, an `AstroImage` object is
automatically rendered as a PNG image.

`AstroImage` automatically extracts and store `wcs` information of images in a `NTuple{N, WCSTransform}`.

## Forming RGB image
`AstroImage` can automatically construct a RGB image if 3 different colour band data is given.
## Headers
FITS Headers can be accessed directly from an AstroImage:
```julia
julia> img["HEAD1"] = 1.0
julia> img["HEAD1",Comment] = "A comment describes the meaning of a header keyword"
julia> img["HEAD1"]
1.0

julia> push!(img, History, "We can record the history of processes applied to this image in header HISTORY entries.")
```

## Visualization

Any AbstractArray (including an AstroImage) can be displayed using `imview`. This function renders an
arbitrary array into an array of `RGBA` values using a number of parameters. If the input is an AstroImage{<:Number},
an AstroImage{RGBA} will be returned that retains headers, WCS information, etc.

```julia
julia> img = AstroImage(RGB, ("file1.fits","file2.fits", "file3.fits"))
julia> imview(img; clims=Percent(99.5), cmap=:magma, stretch=identity, contrast=1.0, bias=0.5)
```
Where 1st index of `file1.fits`, `file2.fits`, `file3.fits` contains band data of red, blue and green channels respectively.

Optionally, `ccd2rgb` method can be used to form a coloured image from 3 bands without creating an `AstroImage`.
Very large Images are automatically downscaled to ensure consistent performance using `restrict` from Images.jl. This function filters the data before downscaling to prevent aliasing, so it may take a moment for truly huge images. In these cases, a faster method that doesn't prevent aliasing would be `imview(img[begin:10:end, begin:10:end])` or similar.

`imview` is called automatically on `AstroImage{<:Number}` when using a Julia environment with rich graphical IO capabilities (e.g. VSCode, Jupyter, Pluto, etc.).
The defaults for this case can be modified using `AstroImages.set_clims!(...)`, `AstroImages.set_cmap!(...)`, and `AstroImages.set_stretch!(...)`.

## Forming Color Composite Images

The formed image can be accessed using `img.property.rgb_image`.
`set_brightness!` and `set_contrast!` methods can be used to change brightness and contrast of formed `rgb_image`.
`add_label!` method can be used to add/store Astronomical labels in an `AstroImage`.
`reset!` method resets `brightness`, `contrast` and `label` fields to defaults and construct a fresh `rgb_image` without any brightness, contrast operations.
A color composite image (e.g. RGB) can be constructed using the `composecolors` function.
```julia
julia> rgb = composecolors([img1, img2, img3])
```
Where `img1`, `img2`, `img3` are arrays or AstroImages containing data of red, blue and green channels respectively.

`composecolors` also supports more complex mappings, for example merging two bands according to color schemes from
ColorSchemes.jl.
See the docs for more information.


## Plotting an AstroImage
Expand All @@ -97,25 +125,33 @@ An `AstroImage` object can be plotted with `Plots.jl` package. Just use
```julia
julia> using Plots

julia> plot(img)
julia> implot(img)
```

and the image will be displayed as a heatmap using your favorite backend.
and the image will be displayed as an image series using your favorite backend.
Plotly, PyPlot, and GR backends have been tested.

`implot` supports all the same syntax as `imview` in addition to keyword arguments
for controlling axis tick marks, WCS grid lines, and the colorbar.

## Resolving World Coordinates
If your FITS file contains world coordinate system headers, AstroImages.jl can use WCS.jl to convert between pixel and world coordinates.
This works even if you have sliced or your image to select a region of interest:

```julia
julia> img_slice = img[100:200,100:200]
julia> coords_world = pix_to_world(img_slice, [5,5])
[..., ...]
julia> world_to_pix(img_slice, coords_world)
[5.0,5.0] # approximately
```

License
-------

The `AstroImages.jl` package is licensed under the MIT "Expat" License. The
original author is Mosè Giordano.

[travis-img]: https://travis-ci.org/JuliaAstro/AstroImages.jl.svg?branch=master
[travis-url]: https://travis-ci.org/JuliaAstro/AstroImages.jl

[appvey-img]: https://ci.appveyor.com/api/projects/status/7gaxwe0c8hjx3d1s?svg=true
[appvey-url]: https://ci.appveyor.com/project/giordano/astroimages-jl

[coveral-img]: https://coveralls.io/repos/JuliaAstro/AstroImages.jl/badge.svg?branch=master&service=github
[coveral-url]: https://coveralls.io/github/JuliaAstro/AstroImages.jl?branch=master

[codecov-img]: http://codecov.io/github/JuliaAstro/AstroImages.jl/coverage.svg?branch=master
[codecov-url]: http://codecov.io/github/JuliaAstro/AstroImages.jl?branch=master
15 changes: 15 additions & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
[deps]
AstroImages = "fe3fc30c-9b16-11e9-1c73-17dabf39f4ad"
DemoCards = "311a05b2-6137-4a5a-b473-18580a3d38b5"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
ImageFiltering = "6a3955dd-da59-5b1f-98d4-e7296123deb5"
ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
ImageTransformations = "02fcd773-0e25-5acc-982a-7f6622650795"
Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
Photometry = "af68cb61-81ac-52ed-8703-edc140936be4"
Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
Reproject = "d1dcc2e6-806e-11e9-2897-3f99785db2ae"
WCS = "15f3aee2-9e10-537f-b834-a6fb8bdb944d"

[compat]
Documenter = "0.27"
60 changes: 60 additions & 0 deletions docs/examples/basics/displaying.jl
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# ---
# title: Displaying Images
# author: "[William Thompson](https://github.com/sefffal)"
# cover: assets/displaying-images.png
# ---

# We'll start by downloading a sample image. If you have an image stored locally,
# you would skip this step.
using AstroImages

AstroImages.set_clims!(Percent(99.5)) #src
AstroImages.set_cmap!(:magma) #src
AstroImages.set_stretch!(identity) #src


# Any AbstractArray can be visualized with the `imview` function.
arr = randn(10,10)
imview(arr)

# Let's load an astronomical image to see how we can tweak its display
fname = download(
"http://www.astro.uvic.ca/~wthompson/astroimages/fits/656nmos.fits",
"eagle-656nmos.fits"
);
img = AstroImage("eagle-656nmos.fits");
imview(img)

# We can adjust the color limits manually
imview(img, clims=(0,100))

# Or provide a function to calculate them for us
imview(img, clims=extrema)

# AstroImages includes some handy callables, like Percent and Zscale.flags
# `Percent` sets the limits to include some central percentage of the data range
# For example, 95% sets the color limits to clip the top and bottom 2.5% of pixels.
# Percent(99.5) is the default value of clims.
imview(img, clims=Percent(95))




# Arrays wrapped by `AstroImage` are displayed automatically using `imview`
AstroImage(randn(10,10))

# The settings for automatic imview are controlled using package defaults that can
# be adjusted to suit your tastes
AstroImages.set_clims!(Zscale()) # Display the full range automatically
AstroImages.set_cmap!(:viridis)
AstroImages.set_stretch!(asinhstretch)
AstroImage(randn(10,10))

# --- restore defaults --- #src
AstroImages.set_clims!(Percent(99.5)) #src
AstroImages.set_cmap!(:magma) #src
AstroImages.set_stretch!(identity) #src

# --- save covers --- #src
mkpath("assets") #src
save("assets/loading-images.png", imview(img)) #src
Loading