MFITPLANE(1)

💖 MFITPLANE 💖

okay so bestie, this is the mFitplane page from the Montage manual, section 1. it fits a plane to your image and honestly it's giving math girlie main character energy. let's get into it 🦋

---

✨ NAME ✨

mFitplane — use least squares to fit a plane to an image. yeah. that's the whole vibe. 🎀

---

🌸 SYNOPSIS 🌸

mFitplane [-b border] [-d level] [-s statusfile] in.fits

like. that's it. one input file, a couple of optional flags, iconic behavior 💅

---

🧚 DESCRIPTION 🧚

so what it does is it uses least squares to fit a plane to an image — and the glow-up here is that it excludes outlier pixels, so the messy pixels don't get to ruin the whole fit. periodt. 💀

where does it get used tho? it's meant for the difference images that you get out of mDiff or mDiffExec. that's the whole point. iykyk ✨

---

💅 OPTIONS 💅

• -b border — the number of border pixels to ignore at the edges of the image. edges stay messy, we don't want that energy 🚫
• -d level — turns on debugging at the level you give it, and that level is 1-3. debug girlies rise 🐛
• -l — level only mode!! don't fit a slope, just get a zero level. sometimes u just want the flat vibe, not the whole gradient situation 🙈
• -s statusfile — output and errors get written to statusfile instead of stdout. quiet mode, mysterious mode 💜

---

🎀 ARGUMENTS 🎀

• in.fits — the input FITS file, and it's a difference file between two other FITS files, the kind you'd generate with mDiff. yes it has to be that kind. no cap 🫶

---

⭐ RESULT ⭐

the plane it fits to the image looks like this, literally:

fit = A*x + B*y + C

and here's the tea on what x and y even are:

• x is the "horizontal" pixel offset from CRPIX1 in the FITS header
• y is the "vertical" pixel offset from CRPIX2

and the reason this is such a slay is that every reprojected image uses the same reference pixel, so x and y mean the exact same thing across your whole image set. uniform definition. consistent. we love to see it 👑

the fitting itself is a simple least squares, with an iterative loop that kicks out any points more than 2 sigma away — where sigma is defined as the rms from the previous loop. so it just keeps refining. little loop, big results 🌀

the rms output is that value we just described. the xmin, ... ymax outputs are the range of x,y values found while fitting. and listen: the rms is for information only, but the xmin, ... ymax are actually used in the background fitting (mBgModel). so they matter. crpix1 and crpix2 are the reference pixels for each axis, as determined from the FITS header. 🌈

---

📬 MESSAGES 📬

when it works you get this absolute masterpiece of a struct:

OK     [struct stat="OK", a=A, b=B, c=C, crpix1=crpix1, crpix2=crpix2,
       xmin=xmin, xmax=xmax, ymin=ymin, ymax=ymax, xcenter=xcenter,
       ycenter=ycenter, npixel=npixel, rms=rms, boxx=boxx, boxy=boxy,
       boxwidth=boxwidth, boxheight=boxheight, boxang=boxang]

and when it doesn't, here's the lineup of errors 💀:

• ERROR Argument to -b (string) cannot be interpreted as an integer
• ERROR Cannot open status file: statusfile
• ERROR Image file filename missing or invalid FITS
• ERROR FITS library error
• ERROR general error

and the warnings, which are more like gentle side-eyes:

• WARNING Too few pixels to fit
• WARNING Too few pixels for bounding box
• WARNING Singular Matrix-1
• WARNING Singular Matrix-2
• WARNING allocation failure in ivector()

---

🌟 EXAMPLES 🌟

okay here's the real one, look at this:

$ mFitplane 2mass-atlas-990322n-j0640266.fits
       [struct stat="OK", a=-8.9198e-11, b=-2.54173e-10, c=5.24277e-05,
       crpix1=808, crpix2=212.5, xmin=-808, xmax=167, ymin=-210.5,
       ymax=638.5, xcenter=-320.871, ycenter=213.014, npixel=314299,
       rms=0.393003, boxx=-320.92, boxy=212.424, boxwidth=835.421,
       boxheight=509.274, boxang=-29.5537]

look at that struct just sitting there. beautiful. no notes 💖

---

🙈 BUGS 🙈

okay so real talk, there are some things you need to know, and i'm telling you because i love you:

• the drizzle algorithm has been implemented but has not been tested in this release. so like. it exists. it is not verified. tread carefully bestie 😭
• if a header template contains carriage returns (aka it was created or modified on a Windows machine), the cfitsio library will not be able to read it properly, and you'll get this error: [struct stat="ERROR", status=207, msg="illegal character in keyword"]. windows strikes again 💀
• and this one's important for the background correction algorithms: it is best 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. the recommendation is to use an expanded header for the reprojection and background modeling steps, then go back to the originally desired header size for the final coaddition. also, the default background matching assumes there are no non-linear background variations in the individual images (and therefore in the overlap differences). if you have any uncertainty about that, it's safer to turn on the "level only" background matching — that's the -l flag in mBgModel. safety first, always 🫶

---

👑 COPYRIGHT 👑

2001-2015 California Institute of Technology, Pasadena, California

and if your research uses Montage, please include this acknowledgement, fr fr:

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

also, the Montage distribution includes an adaptation of the MOPEX algorithm developed at the Spitzer Science Center. 🌌

---

and that's the whole page bestie!! this was Montage 5, dated Dec 2016, and you're reading MFITPLANE(1) 💖✨ go fit a plane, you absolute icon 🎀🦋