API Documentation
FileIO.load
— Functionload(filename)
loads the contents of a formatted file, trying to infer the format fromfilename
and/or magic bytes in the file (seequery
).load(strm)
loads from anIOStream
or similar object. In this case, there is no filename extension, so we rely on the magic bytes for format identification.load(File{format"PNG"}(filename))
specifies the format directly, and bypasses the formatquery
.load(Stream{format"PNG"}(io))
specifies the format directly, and bypasses the formatquery
.load(f; options...)
passes keyword arguments on to the loader.
FileIO.save
— Functionsave(filename, data...)
saves the contents of a formatted file, trying to infer the format fromfilename
.save(Stream{format"PNG"}(io), data...)
specifies the format directly, and bypasses the formatquery
.save(File{format"PNG"}(filename), data...)
specifies the format directly, and bypasses the formatquery
.save(f, data...; options...)
passes keyword arguments on to the saver.
AstroImages.AstroImage
— TypeProvides access to a FITS image along with its accompanying header and WCS information, if applicable.
AstroImages.imview
— Functionimview(img; clims=Percent(99.5), stretch=identity, cmap=:magma, contrast=1.0, bias=0.5)
Create a read only view of an array or AstroImageMat mapping its data values to Colors according to clims
, stretch
, and cmap
.
The data is first clamped to clims
, which can either be a tuple of (min, max) values or a function accepting an iterator of pixel values that returns (min, max). By default, clims=Percent(99.5)
which sets the display min and max to the central 99.5 percentile range of pixel values. Convenient functions to use for clims
are: extrema
, Zscale
, and Percent(p)
Next, the data is rescaled to [0,1] and remapped according to the function stretch
. Stretch can be any monotonic fuction mapping values in the range [0,1] to some range [a,b]. Note that log(0)
is not defined so is not directly supported. For a list of convenient stretch functions, see: logstretch
, powstretch
, squarestretch
, asinhstretch
, sinhstretch
, powerdiststretch
Finally the data is mapped to RGB values according to cmap
. If cmap is nothing
, grayscale is used. ColorSchemes.jl defines hundreds of colormaps. A few nice ones for images include: :viridis
, :magma
, :plasma
, :thermal
, and :turbo
.
Crucially, this function returns a view over the underlying data. If img
is updated then those changes will be reflected by this view with the exception of clims
which is not recalculated.
Note: if clims or stretch is a function, the pixel values passed in are first filtered to remove non-finite or missing values.
Defaults
The default values of clims
, stretch
, and cmap
are extrema
, identity
, and nothing
respectively. You may alter these defaults using AstroImages.set_clims!
, AstroImages.set_stretch!
, and AstroImages.set_cmap!
.
Automatic Display
Arrays wrapped by AstroImageMat()
get displayed as images automatically by calling imview
on them with the default settings when using displays that support showing PNG images.
Missing data
Pixels that are NaN
or missing
will be displayed as transparent when cmap
is set or black if. +/- Inf will be displayed as black or white respectively.
Exporting Images
The view returned by imview
can be saved using general FileIO.save
methods. Example:
v = imview(data, cmap=:magma, stretch=asinhstretch, clims=Percent(95))
save("output.png", v)
imview(img::AbstractArray{<:Complex}; ...)
When applied to an image with complex values, display the magnitude of the pixels using imview
and display the phase angle as a panel below using a cyclical color map. For more customatization, you can create a view like this yourself:
vcat(
imview(abs.(img)),
imview(angle.(img)),
)
AstroImages.implot
— Functionimplot(
img::AbstractArray;
clims=Percent(99.5),
stretch=identity,
cmap=:magma,
bias=0.5,
contrast=1,
wcsticks=true,
grid=true,
platescale=1
)
Create a read only view of an array or AstroImageMat mapping its data values to an array of Colors. Equivalent to:
implot(
imview(
img::AbstractArray;
clims=Percent(99.5),
stretch=identity,
cmap=:magma,
bias=0.5,
contrast=1,
),
wcsn=1,
wcsticks=true,
wcstitle=true,
grid=true,
platescale=1
)
Image Rendering
See imview
for how data is mapped to RGBA pixel values.
WCS & Image Coordinates
If provided with an AstroImage that has WCS headers set, the tick marks and plot grid are calculated using WCS.jl. By default, use the first WCS coordinate system. The underlying pixel coordinates are those returned by dims(img)
multiplied by platescale
. This allows you to overplot lines, regions, etc. using pixel coordinates. If you wish to compute the pixel coordinate of a point in world coordinates, see world_to_pix
.
wcsn
(default1
) select which WCS transform in the headers to use for ticks & gridwcsticks
(defaulttrue
if WCS headers present) display ticks and labels, and title using world coordinateswcstitle
(defaulttrue
if WCS headers present andlength(refdims(img))>0
). When slicing a cube, display the location along unseen axes in world coordinates instead of pixel coordinates.grid
(defaulttrue
) show a grid over the plot. Uses WCS coordinates ifwcsticks
is true, otherwise pixel coordinates multiplied byplatescale
.platescale
(default1
). Scales the underlying pixel coordinates to ease overplotting, etc. Ifwcsticks
is false, the displayed pixel coordinates are also scaled.
Defaults
The default values of clims
, stretch
, and cmap
are extrema
, identity
, and nothing
respectively. You may alter these defaults using AstroImages.set_clims!
, AstroImages.set_stretch!
, and AstroImages.set_cmap!
.
DimensionalData.Dimensions.dims
— Functiondims(x, [dims::Tuple]) => Tuple{Vararg{Dimension}}
dims(x, dim) => Dimension
Return a tuple of Dimension
s for an object, in the order that matches the axes or columns of the underlying data.
dims
can be Dimension
, Dimension
types, or Symbols
for Dim{Symbol}
.
The default is to return nothing
.
DimensionalData.Dimensions.refdims
— Functionrefdims(x, [dims::Tuple]) => Tuple{Vararg{Dimension}}
refdims(x, dim) => Dimension
Reference dimensions for an array that is a slice or view of another array with more dimensions.
slicedims(a, dims)
returns a tuple containing the current new dimensions and the new reference dimensions. Refdims can be stored in a field or disgarded, as it is mostly to give context to plots. Ignoring refdims will simply leave some captions empty.
The default is to return an empty Tuple
()
.
AstroImages.Comment
— TypeIndex for accessing a comment associated with a header keyword or COMMENT entry.
Example:
img = AstroImage(randn(10,10))
img["ABC"] = 1
img["ABC", Comment] = "A comment describing this key"
push!(img, Comment, "The purpose of this file is to demonstrate comments")
img[Comment] # ["The purpose of this file is to demonstrate comments")]
AstroImages.History
— TypeAllows accessing and setting HISTORY header entries
img = AstroImage(randn(10,10)) push!(img, History, "2023-04-19: Added history entry.") img[History] # ["2023-04-19: Added history entry."]
WCS.pix_to_world
— Functionpix_to_world(wcs, pixcoords)
Convert the array of pixel coordinates pixcoords
to world coordinates according to the WCSTransform wcs
. pixcoords
should be a 2-d array where "pixcoords[:, i]" is the i-th set of coordinates, or a 1-d array representing a single set of coordinates.
The return value is the same shape as pixcoords
.
pix_to_world(img::AstroImage, pixcoords; all=false)
Given an astro image, look up the world coordinates of the pixels given by pixcoords
. World coordinates are resolved using WCS.jl and a WCSTransform calculated from any FITS header present in img
. If no WCS information is in the header, or the axes are all linear, this will just return pixel coordinates.
pixcoords
should be the coordinates in your current selection of the image. For example, if you select a slice like this:
julia> cube = load("some-3d-cube.fits")
julia> slice = cube[10:20, 30:40, 5]
Then to look up the coordinates of the pixel in the bottom left corner of slice
, run:
julia> world_coords = pix_to_world(img, [1, 1])
[10, 30]
If WCS information was present in the header of cube
, then those coordinates would be resolved using axis 1, 2, and 3 respectively.
To include world coordinates in all axes, pass all=true
julia> world_coords = pix_to_world(img, [1, 1], all=true)
[10, 30, 5]
!! Coordinates must be provided in the order of dims(img)
. If you transpose an image, the order you pass the coordinates should not change.
WCS.world_to_pix
— Functionworld_to_pix(wcs, worldcoords)
Convert the array of world coordinates worldcoords
to pixel coordinates according to the WCSTransform wcs
. worldcoords
is a 2-d array where "worldcoords[:, i]" is the i-th set of coordinates, or a 1-d array representing a single set of coordinates.
The return value is the same size as worldcoords
.
DimensionalData.Dimensions.X
— TypeX <: XDim
X(val=:)
X Dimension
. X <: XDim <: IndependentDim
Example:
xdim = X(2:2:10)
# Or
val = A[X(1)]
# Or
mean(A; dims=X)
DimensionalData.Dimensions.Y
— TypeY <: YDim
Y(val=:)
Y Dimension
. Y <: YDim <: DependentDim
Example:
ydim = Y(['a', 'b', 'c'])
# Or
val = A[Y(1)]
# Or
mean(A; dims=Y)
DimensionalData.Dimensions.Z
— TypeZ <: ZDim
Z(val=:)
Z Dimension
. Z <: ZDim <: Dimension
Example:
zdim = Z(10:10:100)
# Or
val = A[Z(1)]
# Or
mean(A; dims=Z)
DimensionalData.Dimensions.Dim
— TypeDim{S}(val=:)
A generic dimension. For use when custom dims are required when loading data from a file. Can be used as keyword arguments for indexing.
Dimension types take precedence over same named Dim
types when indexing with symbols, or e.g. creating Tables.jl keys.
using DimensionalData
dim = Dim{:custom}(['a', 'b', 'c'])
# output
Dim{:custom} Char['a', 'b', 'c']
DimensionalData.Dimensions.LookupArrays.At
— TypeAt <: IntSelector
At(x, atol, rtol)
At(x; atol=nothing, rtol=nothing)
Selector that exactly matches the value on the passed-in dimensions, or throws an error. For ranges and arrays, every intermediate value must match an existing value - not just the end points.
x
can be any value or Vector
of values.
atol
and rtol
are passed to isapprox
. For Number
rtol
will be set to Base.rtoldefault
, otherwise nothing
, and wont be used.
Example
using DimensionalData
A = DimArray([1 2 3; 4 5 6], (X(10:10:20), Y(5:7)))
A[X(At(20)), Y(At(6))]
# output
5
DimensionalData.Dimensions.LookupArrays.Near
— TypeNear <: IntSelector
Near(x)
Selector that selects the nearest index to x
.
With Points
this is simply the index values nearest to the x
, however with Intervals
it is the interval center nearest to x
. This will be offset from the index value for Start
and End
loci.
Example
using DimensionalData
A = DimArray([1 2 3; 4 5 6], (X(10:10:20), Y(5:7)))
A[X(Near(23)), Y(Near(5.1))]
# output
4
AstroImages.header
— Functionheader(img::AstroImage)
Return the underlying FITSIO.FITSHeader object wrapped by an AstroImage. Note that this object has less flexible getindex and setindex methods. Indexing by symbol, Comment, History, etc are not supported.
header(array::AbstractArray)
Returns an empty FITSIO.FITSHeader object when called with a non-AstroImage abstract array.
AstroImages.wcs
— Functionwcs(img)
Computes and returns a list of World Coordinate System WCSTransform objects from WCS.jl. The resultss are cached after the first call, so subsequent calls are fast. Modifying a WCS header invalidates this cache automatically, so users should call wcs(...)
each time rather than keeping the WCSTransform object around.
wcs(img, index)
Computes and returns a World Coordinate System WCSTransform objects from WCS.jl by index. This is to support files with multiple WCS transforms specified. wcs(img,1)
is useful for selecting selecting the first WCSTranform object. The resultss are cached after the first call, so subsequent calls are fast. Modifying a WCS header invalidates this cache automatically, so users should call wcs(...)
each time rather than keeping the WCSTransform object around.
wcs(array)
Returns a list with a single basic WCSTransform object when called with a non-AstroImage abstract array.
AstroImages.WCSGrid
— TypeWCSGrid(img::AstroImageMat, ax=(1,2), coords=(first(axes(img,ax[1])),first(axes(img,ax[2]))))
Given an AstroImageMat, return information necessary to plot WCS gridlines in physical coordinates against the image's pixel coordinates. This function has to work on both plotted axes at once to handle rotation and general curvature of the WCS grid projected on the image coordinates.
AstroImages.composecolors
— Functioncomposecolors(
images,
cmap=["#F00", "#0F0", "#00F"];
clims,
stretch,
contrast,
bias,
multiplier
)
Create a color composite of multiple images by applying imview
and blending the results. This function can be used to create RGB composites using any number of channels (e.g. red, green, blue, and hydrogen alpha) as well as more exotic images like blending radio and optical data using two different colormaps.
cmap
should be a list of colorants, named colors (see Colors.jl), or colorschemes (see ColorSchemes.jl). clims
, stretch
, contrast
, and bias
are passed on to imview
. They can be a single value or a list of different values for each image.
The headers of the returned image are copied from the first image.
Examples:
# Basic RGB
composecolors([redimage, greenimage, blueimage])
# Non-linear stretch before blending
composecolors([redimage, greenimage, blueimage], stretch=asinhstretch)
# More than three channels are allowed (H alpha in pink)
composecolors(
[antred, antgreen, antblue, anthalp],
["red", "green", "blue", "maroon1"],
multiplier=[1,2,1,1]
)
# Can mix
composecolors([radioimage, xrayimage], [:ice, :magma], clims=extrema)
composecolors([radioimage, xrayimage], [:magma, :viridis], clims=[Percent(99), Zscale()])
AstroImages.Zscale
— TypeZscale(options)(data)
Wraps PlotUtils.zscale in a callable with default parameters. This is a common algorithm for agressively stretching astronomical data to see faint structure that originated in IRAF: https://iraf.net/forum/viewtopic.php?showtopic=134139 but is now seen in many other applications/libraries (DS9, Astropy, etc.)
Usage:
imview(img, clims=Zscale())
implot(img, clims=Zscale(contrast=0.1))
Default parameters:
nsamples::Int=1000
contrast::Float64=0.25
max_reject::Float64=0.5
min_npixels::Float64=5
k_rej::Float64=2.5
max_iterations::Int=5
AstroImages.Percent
— TypePercent(99.5)
Returns a callable that calculates display limits that include the given percent of the image data. Reproduces the behaviour of the SAO DS9 scale menu.
Example:
julia> imview(img, clims=Percent(90))
This will set the limits to be the 5th percentile to the 95th percentile.
AstroImages.logstretch
— Functionlogstretch(num,a=1000)
A log-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html
AstroImages.powstretch
— Functionpowstretch(num, a=1000)
A power-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html
AstroImages.sqrtstretch
— Functionsqrtstretch(num)
A square root stretch (simply defined as Base.sqrt)
AstroImages.squarestretch
— Functionsquarestretch(num)
A squarestretch-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html
AstroImages.asinhstretch
— Functionasinhstretch(num)
A hyperbolic arcsin stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html.
AstroImages.sinhstretch
— Functionsinhstretch(num)
A hyperbolic sin stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html
AstroImages.powerdiststretch
— Functionlogstretch(num,a=1000)
A power distance stretch as defined by astropy.
AstroImages.copyheader
— Functioncopyheader(img::AstroImage, data) -> imgnew
Create a new image copying the header of img
but using the data of the AbstractArray data
. Note that changing the header of imgnew
does not affect the header of img
. See also: shareheader
.
AstroImages.shareheader
— Functionshareheader(img::AstroImage, data) -> imgnew
Create a new image reusing the header dictionary of img
but using the data of the AbstractArray data
. The two images have synchronized header; modifying one also affects the other. See also: copyheader
.