API Documentation

AstroImage

Provides access to a FITS image along with its accompanying header and WCS information, if applicable.

imview(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)),
)

implot(
    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 (default 1) select which WCS transform in the headers to use for ticks & grid
• wcsticks (default true if WCS headers present) display ticks and labels, and title using world coordinates
• wcstitle (default true if WCS headers present and length(refdims(img))>0). When slicing a cube, display the location along unseen axes in world coordinates instead of pixel coordinates.
• grid (default true) show a grid over the plot. Uses WCS coordinates if wcsticks is true, otherwise pixel coordinates multiplied by platescale.
• platescale (default 1). Scales the underlying pixel coordinates to ease overplotting, etc. If wcsticks 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!.

Index 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"]

Allows 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."]

header(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.

wcs(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.

WCSGrid(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.

composecolors(
    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()])

Zscale(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

Percent(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.

logstretch(num,a=1000)

A log-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

powstretch(num, a=1000)

A power-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

sqrtstretch(num)

A square root stretch (simply defined as Base.sqrt)

squarestretch(num)

A squarestretch-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

asinhstretch(num)

A hyperbolic arcsin stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

sinhstretch(num)

A hyperbolic sin stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

powerdiststretch(num, a=1000)

A power distance stretch as defined by astropy.

copyheader(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.

shareheader(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.

recenter(img::AstroImage)
recenter(img::AstroImage, newcentx, newcenty, ...)

Adjust the dimensions of an AstroImage so that they are centered on the pixel locations given by newcentx, .. etc. This does not affect the underlying array, it just updates the dimensions associated with it by the AstroImage. If no newcent arguments are provided, center the image in all dimensions to the middle pixel (or fractional pixel).

Example:

a = AstroImage(randn(11,11))
a[1,1] # Bottom left
a[At(1),At(1)] # Bottom left
r = recenter(a, 6, 6)
r[1,1] # Still bottom left
r[At(1),At(1)] # Center pixel