# Visualization functions

Healpix.jl uses RecipesBase to display maps. You need to import `Plots`

in order to display maps, using the `plot`

functions. Maps are internally treated as heatmaps, so your backend should support this kind of visualization: at the moment, this is true for GR, PlotLy and PyPlot.

```
using Healpix
using Plots
pyplot() # hide
nside = 8
m = HealpixMap{Float64, RingOrder}(nside)
m.pixels[:] = 1:length(m.pixels)
plot(m)
savefig(joinpath("images", "mollweide.png")) # hide
```

A call to `plot`

can provide two additional arguments:

- A carthographic projection (see below).
- A dictionary containing parameters to be used by the carthographic projection.

The following example displays the same map in orthographic coordinates:

```
plot(m, orthographic)
savefig(joinpath("images", "orthographic.png")) # hide
```

# Cartographic projections

Plotting is based on `project`

, which takes a map as input and produces a 2-D bitmap containing a representation of the map suitable to be shown using Plots.

Although the easiest way to plot a map is to use `plot`

, `project`

might be suitable in those cases where you are just interested in a 2D bitmap. It requires a *inverse* projection function (mapping the 2D plane to a point on the sphere) and the size of the bitmap, and it returns three values:

A 2-D bitmap containing the color level of each pixel. Unseen pixels (e.g., those falling outside the ellipse in a Mollweide projection) are marked as

`NaN`

, as well as unseen pixels;A 2-D bitmap of

`Bool`

values, telling which pixels in the map are masked, i.e., they are marked as`UNSEEN`

,`NaN`

or`missing`

in the Healpix map;A

`Bool`

flag telling if there is any masked value in the mask (2nd return value, see above). This parameter is returned to optimize calls to`plot`

, but it is obviously redundant.

Consider this example:

```
using Healpix
m = HealpixMap{Float64, RingOrder}(1)
# Plot the map on a 20×20 bitmap using an
# equirectangular projection
image, mask, maskflag = project(equiprojinv, m, 20, 20)
```

`(Float32[0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0], Bool[0 0 … 0 0; 0 0 … 0 0; … ; 0 0 … 0 0; 0 0 … 0 0], false)`

A number of parameters can be passed to `project`

, in order to taylor the representation. They must **not** be passed as keyword arguments, because this would clash with the way plot recipes work; instead, you must use a dictionary:

```
# Return a 2-D bitmap of 16-bit floating-point values
image, _, _ = project(equiprojinv, m, 20, 20,
Dict(:desttype => Float16))
```

`(Float16[0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0], Bool[0 0 … 0 0; 0 0 … 0 0; … ; 0 0 … 0 0; 0 0 … 0 0], false)`

The following dictionary keys are available:

`:desttype`

: type used for the pixels in the 2-D bitmap returned by`project`

. Default is`Float32`

;`:unseen`

: the value marking pixels as unseen, i.e., masked. The default is`-1.6375e+30`

, to preserve compatibility with other Healpix libraries.`:center`

: currently this is used only with orthographic projections. It specifies the coordinates of the center of the image (colatitude and longitude, both in radians).

`Healpix.project`

— Function`project(invprojfn, m::HealpixMap{T, O, AA}, bmpwidth, bmpheight; kwargs...)`

Return a 2D bitmap (array) containing a cartographic projection of the map and a 2D bitmap containing a boolean mask. The size of the bitmap is `bmpwidth`

×`bmpheight`

pixels. The function `projfn`

must be a function which accepts as input two parameters `x`

and `y`

(numbers between -1 and 1).

The following keywords can be used in the call:

`center`

: 2-tuple specifying the location (colatitude, longitude) of the sky point that is to be placed in the middle of the image (in radians)`unseen`

: by default, Healpix maps use the value -1.6375e+30 to mark unseen pixels. You can specify a different value using this keyword. This should not be used in common applications.

Return a `Array{Union{Missing, Float32}}`

containing the intensity of each pixel. Pixels falling outside the projection are marked as NaN, and unseen pixels are marked as `missing`

.

## Projection functions

Functions `mollweide`

, `equirectangular`

, and `orthographic`

can be passed as parameters to `plot`

.

`Healpix.mollweide`

— Function`mollweide(m::HealpixMap{T, O, AA}, projparams = Dict()) where {T <: Number, O, AA}`

High-level wrapper around `project`

for Mollweide projections.

The following parameters can be set in the `projparams`

dictionary:

`width`

: width of the image, in pixels (default: 720 pixels)`height`

: height of the image, in pixels; if not specified, it will be assumed to be equal to`width`

`Healpix.equirectangular`

— Function`equirectangular(m::HealpixMap{T,O,AA}; kwargs...) where {T <: Number, O, AA}`

High-level wrapper around `project`

for equirectangular projections.

`Healpix.orthographic`

— Function`orthographic(m::HealpixMap{T,O}, projparams = Dict()) where {T <: Number,O <: Order}`

High-level wrapper around `project`

for orthographic projections.

The following parameters can be set in the `projparams`

dictionary:

`width`

: width of the image, in pixels (default: 720 pixels)`height`

: height of the image, in pixels; if not specified, it will be assumed to be equal to`width`

`center`

: position of the pixel in the middle of the left globe (*latitude*and longitude).

`Healpix.orthographic2`

— Function`orthographic2(m::HealpixMap{T, O, AA}, projparams = Dict()) where {T <: Number, O, AA}`

High-level wrapper around `project`

for stereo orthographic projections.

The following parameters can be set in the `projparams`

dictionary:

`width`

: width of the image, in pixels (default: 720 pixels)`height`

: height of the image, in pixels; if not specified, it will be assumed to be equal to`width`

`center`

: position of the pixel in the middle of the left globe (*latitude*and longitude). Default is (0, 0).

`Healpix.gnomonic`

— Function`gnomonic(m::HealpixMap{T, O, AA}, projparams = Dict()) where {T <: Number, O, AA}`

High-level wrapper around `project`

for gnomonic projections.

The following parameters can be set in the `projparams`

dictionary:

`width`

: width of the image, in pixels (default: 720 pixels)`height`

: height of the image, in pixels; if not specified, it will be assumed to be equal to`width`

`center`

: position and orientation of the pixel in the middle. It is a 3-element tuple containing:- The
*latitude*of the pixel, in radians - The longitude of the pixel, in radians
- The rotation to be applied to the image, in radians

- The
`fov_rad`

: size of the image along the x and y axes, in radians (default: 15°)

**Example**

`plot(m, gnomonic, Dict(:fov_rad = deg2rad(1.5), :center = (0, 0, deg2rad(45))))`

They are based on *inverse* projection functions, i.e., functions that take a point in the plane $[-1, 1] \times [-1, 1]$ and return a tuple `(Bool, Number, Number)`

, where the first Boolean is `true`

if the point falls within the projection, and the other two numbers are the latitude and longitude in radians.

`Healpix.mollweideprojinv`

— Function`mollweideprojinv(x, y)`

Inverse Mollweide projection. Given a point (x, y) on the plane, with x ∈ [-1, 1], y ∈ [-1, 1], return a 3-tuple of type (Bool, Number, Number). The boolean specifies if (x, y) falls within the map (true) or not (false), the second and third arguments are the latitude and longitude in radians.

`Healpix.equiprojinv`

— Function`equiprojinv(x, y)`

Inverse equirectangular projection. Given a point (x, y) on the plane [-1, 1] × [-1, 1], return a tuple (Bool, Number, Number) where the first Boolean is a flag telling if the point falls within the projection (true) or not (false), and the two numbers are the latitude and longitude in radians.

`Healpix.orthoinv`

— Function`orthoinv(x, y, ϕ1, λ0)`

Inverse orthographic projection centered on (ϕ1, λ0). Given a point (x, y) on the plane, with x ∈ [-1, 1], y ∈ [-1, 1], return a 3-tuple of type (Bool, Number, Number). The boolean specifies if (x, y) falls within the map (true) or not (false), the second and third arguments are the latitude and longitude in radians.

`Healpix.ortho2inv`

— Function`function ortho2inv(x, y, ϕ1, λ0)`

Inverse stereo orthographic projection centered on (ϕ1, λ0). Given a point (x, y) on the plane, with x ∈ [-1, 1], y ∈ [-1, 1], return a 3-tuple of type (Bool, Number, Number). The boolean specifies if (x, y) falls within the map (true) or not (false), the second and third arguments are the latitude and longitude in radians.

`Healpix.gnominv`

— Function`function gnominv(x, y, ϕ1, λ0, fov_rad)`

Gnomonic projection centered on (ϕ1, λ0), with a field of view equal to `fov_rad`

(in radians). Given a point (x, y) on the plane, with x ∈ [-1, 1], y ∈ [-1, 1], return a 3-tuple of type (Bool, Number, Number). The boolean specifies if (x, y) falls within the map (true) or not (false), the second and third arguments are the latitude and longitude in radians.

The direct project functions are available too.

`Healpix.equiproj`

— Function`equiproj(lat, lon)`

Equirectangular projection. Given the latitude `lat`

(in radians) and the longitude (in radians), return a tuple (Bool, Number, Number) where the first Boolean is a flag telling if the point falls within the projection (true) or not (false), and the two numbers are the x and y coordinates of the point on the projection plane (both are in the range [−1, 1]).

`Healpix.mollweideproj`

— Function`mollweideproj(lat, lon)`

Mollweide projection. Given the latitude `lat`

(in radians) and the longitude (in radians), return a tuple (Bool, Number, Number) where the first Boolean is a flag telling if the point falls within the projection (true) or not (false), and the two numbers are the x and y coordinates of the point on the projection plane (both are in the range [−1, 1]).