MPROJECTCUBE(1)

💫 MPROJECTCUBE(1) — the mProjectCube glow-up ✨

okay bestie, welcome to mProjectCube from Montage 🎀 — yes, that's the manual page name up top, we're doing this.

---

🦋 NAME

mProjectCube — reproject a single cube to a user specified scale and coordinate system. that's it, that's the gig 💅

---

✨ SYNOPSIS

mProjectCube [-z factor] [-d level] [-s statusfile] [-h hdu] [-x scale]
[-w weightfile] [-W fixed-weight] [-t threshold] [-X] [-e(nergy-mode)]
[-f] in.fits out.fits hdr.template

three positional args at the end, always, no skipping 👑

---

🌸 DESCRIPTION

so mProjectCube takes one single cube and reprojects it onto the scale that's defined inside a FITS header template file (there's more about header templates in the docs, go peep it 🫶).

it hands you back a pair of files: the reprojected cube, and an "area" image — and the area image is literally the fraction of input pixel sky area that landed in each output pixel. it's giving receipts. 💖

the "drizzle" algorithm is implemented here. the way it works: it maps pixel corners (as adjusted by drizzle, if drizzle got called) from input pixel space → output pixel space, works out the overlap area with every output pixel, and then accumulates the appropriate fraction of the input flux into the output cube pixels. and on top of that, the appropriate fraction of the input pixel area gets accumulated into the area image pixels. two for one, no cap. ✨

projecting points from input pixel space to output pixel space happens in two steps:

1. map from input pixel space to sky coordinates
2. map from sky coordinates to output pixel space

a lil PSA that keeps happening so it earned its own paragraph: you can absolutely define a FITS header with the reference location off the image. people do it all the time with cylindrical projections (like CAR, CEA) referenced to location (0.,0.) — e.g. the Galactic center. that's not wrong in itself!! but it does lead to extremely large pixel offsets (like, in the hundreds of thousands 😭). and related: if you extract a header from an image with large offsets of this type, it is unlikely you can simply change projection types without also adjusting the reference location/offsets. most likely you'll end up with the reprojected data all being off-scale. 💀

---

👑 OPTIONS

• -z factor — processing is done utilizing the drizzle algorithm. factor is a floating point number, and the recommended drizzle factors are from 0.5 to 1. slay range.
• -d level — causes additional debugging information to be printed to stdout. valid levels are 1-5 (for higher debugging levels, it's recommended you redirect the output to a file — trust, you'll want to 🫠).
• -s statusfile — output and errors are written to statusfile instead of being written to stdout.
• -h hdu — use the specified FITS extension (default is to use the first HDU with image data).
• -x scale — apply a correction factor of scale to each pixel.
• -w weightfile — path to a weight map to be used when reading values from the input image.
• -W fixed-weight — use a constant weight value for the whole image.
• -t threshold — pixels with weights below threshold will be treated as blank.
• -X — makes the output region (originally defined in the header template) big enough to include all of the input images. go big, periodt.
• -e — process the data as total energy rather than the default energy density (scale values by relative pixel areas).
• -f — output the full region requested even if there's a border of NULL values (default is to shrinkwrap to just the pixels with values). the default is giving minimalist ✨

---

🧚 ARGUMENTS

• in.fits — input FITS file to be reprojected.
• out.fits — path of output FITS file to be created.
• hdr.template — FITS header template to be used in generation of output image.

---

🌈 RESULT

two files get created as output, bestie, not one:

• the reprojected FITS file (out.fits)
• an "area" image (out_area.fits) which records the amount of coverage (in output pixel space) provided by the input images.

---

💜 MESSAGES

here's the full roster of what it can yell back at you, verbatim so you can grep for it:

OK     [struct stat="OK", time=seconds]

ERROR  Drizzle factor string (string) cannot be interpreted as a real number

ERROR  Weight threshold string (string) cannot be interpreted as a real number

ERROR  Flux scale string (string) cannot be interpreted as a real number

ERROR  Cannot open status file: statusfile

ERROR  HDU value (hdu) must be a non-negative integer

ERROR  No overlap

ERROR  Not enough memory for output data image array

ERROR  Not enough memory for output area image array

ERROR  Output wcsinit() failed.

ERROR  Input wcsinit() failed.

ERROR  FITS library error

ERROR  All pixels are blank

ERROR  Template file not found

ERROR  Image file in.fits missing or invalid FITS

ERROR  Weight file weightfile missing or invalid FITS

---

🍓 EXAMPLES

like this, bestie:

$ mProjectCube rawdir/real_orig.fits projdir/base_unity.fits templates/galactic_orig.txt
[struct stat="OK", time=143]

and yeah, [struct stat="OK", time=143] is the little victory lap at the end 🎀

---

🙈 BUGS

• the drizzle algorithm has been implemented but has not been tested in this release. (yes, for real. it's giving "shipped it, vibes only" 😭)
• if a header template contains carriage returns (i.e., created/modified on a Windows machine), the cfitsio library will be unable to read it properly, resulting in this error:

[struct stat="ERROR", status=207, msg="illegal character in keyword"]

• it is best for the background correction algorithms if the area described in the header template completely encloses all of the input images in their entirety. if parts of input images are "chopped off" by the header template, the background correction will be affected. we recommend you use an expanded header for the reprojection and background modeling steps, returning to the originally desired header size for the final coaddition. the default background matching assumes that there are no non-linear background variations in the individual images (and therefore in the overlap differences). if there is any uncertainty in this regard, it is safer to turn on the "level only" background matching (the -l flag in mBgModel).

---

⭐ COPYRIGHT

2001-2015 California Institute of Technology, Pasadena, California

if your research uses Montage, please include the following acknowledgement:

"This research made use of Montage. It is funded by the National Science Foundation under Grant Number ACI-1440620, and was previously funded by the National Aeronautics and Space Administration's Earth Science Technology Office, Computation Technologies Project, under Cooperative Agreement Number NCC5-626 between NASA and the California Institute of Technology."

the Montage distribution includes an adaptation of the MOPEX algorithm developed at the Spitzer Science Center. iconic behavior, honestly 🫶

---

okay that's the whole page, you're so welcome 💖 this was Montage 5, dated Dec 2016 — mwah, go reproject something, bestie 💅✨🌈