% This is the ADASS_template.tex LaTeX file, 24 Oct 2025.
% It is based on the ASP general author template file, but modified to reflect the specific
% requirements of the ADASS proceedings.

% This is the aspauthor.tex LaTeX file
% Copyright 2021, Astronomical Society of the Pacific Conference Series
% Revision:  29 November 2021

% To compile, at the command line positioned at this folder, type:
% pdflatex ADASS_template
% pdflatex ADASS_template
% This will create a file called ADASS_template.pdf

\documentclass[11pt,twoside]{article}

% Do NOT use ANY packages other than asp2021. 
\usepackage{asp2021}

\aspSuppressVolSlug
\resetcounters

% References must all use BibTeX entries in a .bibfile.
% References must be cited in the text using \citet{} or \citep{}.
% Do not use \cite{}.
% See ManuscriptInstructions.pdf for more details
\bibliographystyle{asp2021}

% The ``markboth'' line sets up the running heads for the paper.
% 1 author: "Surname"
% 2 authors: "Surname1 and Surname2"
% 3 authors: "Surname1, Surname2, and Surname3"
% >3 authors: "Surname1 et al."
% Replace ``Short Title'' with the actual paper title, shortened if necessary.
% Use mixed case type for the shortened title
% Ensure shortened title does not cause an overfull hbox LaTeX error
% See ASPmanual2010.pdf 2.1.4  and ManuscriptInstructions.pdf for more details
\markboth{Jeschke}{Porting a Multi-Object Spectrograph Mask Design App
  from IDL to Python}

\begin{document}

\title{Porting a Multi-Object Spectrograph Mask Design App from IDL to Python}

% Note the position of the comma between the author name and the 
% affiliation number.
% Authors surnames should come after first names or initials, eg John Smith, or J. Smith.
% Author names should be separated by commas.
% The final author should be preceded by "and".
% Affiliations should not be repeated across multiple \affil commands. If several
% authors share an affiliation this should be in a single \affil which can then
% be referenced for several author names. If only one affiliation, no footnotes are needed.
% See ManuscriptInstructions.pdf and ASP's manual2010.pdf 3.1.4 for more details
\author{Eric~Jeschke,$^1$ Russell~Kackley,$^1$ Makoto~Tanaka,$^1$ and Minkyeong~Kim}
\affil{$^1$Subaru~Telescope,~National~Astronomical~Observatory~of~Japan}

% This section is for ADS Processing.  There must be one line per author. paperauthor has 9 arguments.
\paperauthor{Eric~Jeschke}{eric@naoj.org}{0000-0001-9586-4482}{Subaru~Telescope,~National~Astronomical~Observatory~of~Japan}{Software Division}{Hilo}{Hawaii}{96720}{USA}
\paperauthor{Russell~Kackley}{rkackley@naoj.org}{}{Subaru~Telescope,~National~Astronomical~Observatory~of~Japan}{Software Division}{Hilo}{Hawaii}{96720}{USA}
\paperauthor{Makoto~Tanaka}{ichi@naoj.org}{}{Subaru~Telescope,~National~Astronomical~Observatory~of~Japan}{Science Operations Division}{Hilo}{Hawaii}{96720}{USA}
\paperauthor{Minkyeong~Kim}{}{}{}{}{}{}{}{}

% There should be one \aindex line (commented out) for each author. These are used to
% build up the author index for the Proceedings. The surname must come first, followed by
% initials. Note the use of ~ before each initial to control spacing.
% The \author entries (see above) have surname last. These \aindex entries have
% surname first.
% The Aindex.py command willl create them for you after you have constructed the \author
% The first entry should be the first author, for bold-facing the author index page-reference

%\aindex{Jeschke,~E.}
%\aindex{Kackley,~R.}
%\aindex{Tanaka,~M.}
%\aindex{Kim,~M.}

\begin{abstract}
We present a case-study in migrating a mask design software application for a
Multi-Object Spectrograph (MOIRCS, operating at Subaru Telescope) from
an IDL (Interactive Data Language) implementation to a pure Python one.
The port accomplished several goals, including:
(1) freeing users from onerous licensing restrictions, and
(2) improving the overall stability and responsiveness of the program, and
(3) improving the prospects for future upgrades and maintenance.
We explain the purpose and use of the program, describe the practical
procedures used in the port, and finally show and describe the user interfaces
of both the old and the new versions.
\end{abstract}

\section{Introduction}
MOIRCS (Multi-Object Infrared Camera and Spectrograph) provides imaging and
low-resolution spectroscopy from 0.9-2.5 microns over a 4x7 arcmin field of
view, operating on the Subaru Telescope at the summit of Maunakea, Hawaii.
A popular feature of this instrument is the MOS mode, in which a custom-cut
mask can be used to obtain spectra for multiple objects within the same field.
MOIRCS slit masks consist of a number of slits and alignment holes cut into
a thin, flexible mask.  Several masks can be loaded into the instrument prior
to observation and then inserted into the optical path during observation.
The alignment holes are used to line up with stars of sufficient
magnitude and an alignment procedure during observation shifts and rotates
the focal plane so that stars appear in the holes and the slits are aligned
precisely with the objects for which they are configured. After that, a series
of exposures can be taken to obtain the necessary spectra.

When the instrument was commissioned in 2006\citep{Ichikawa06} an IDL-based
program was developed to allow potential users to create the mask design
files necessary for the observatory to cut the needed masks prior to
observation.
The output of the mask design program is a simple, tabular file with
coordinates and lengths measured in millimeters for the mask cutting process.

\articlefigure{184_f1.png}{fig1}{Screenshot showing the IDL version on the left, and the new MOIRCS Mask Builder plugin running in Ginga on the right.}

\section{How the IDL version works}
The IDL program works by loading a FITS image large enough to cover the MOIRCS
field of view.  The image needs to have a valid world coordinate system and
should be rescaled to 0.117 arc seconds per pixel.  The program provides a
graphical overlay showing the MOIRCS detector outline and overall field of view,
as shown in Figure \ref{fig1} (left).
The user then chooses a grism (and optionally can change some of the grism
parameters).  Following this, the user places slits and holes within the frame
and can configure the slit lengths and widths as needed.  These objects can
be placed by clicking on the image or by measuring the center of an object
in the image.  This configuration can be saved in a ``.mdp'' (MOIRCS Design
Program) file, which is a simple ASCII CSV-formatted file containing the
types, positions and attributes of the slits and holes in pixel units.
An MDP file can be loaded to initialize the program if the user needs to make
subsequent adjustments.

The spectral dispersion of the slits and holes on the
detectors can be visualized with an option, allowing one to see if there are
overlaps or other issues that could cause contamination of the spectra.
The user adds as many holes and slits as necessary and adjusts their locations
and parameters till they are satisfied that the design is reasonable.
Finally, the user concludes the process by a final save of the the MDP
file and also exporting an output SBR file (with the ``.sbr'' extension) that
contains the physical coordinates and measurements used by the mask
cutting machine.

\section{Issues with the IDL Version}
The IDL version of the mask builder program has several issues that were
problematic for our use case:
\begin{itemize}
\item IDL itself has licensing restrictions, which makes it
difficult to configure which computers can run the software.  The license
server is inside the observatory firewall, so the user either has to be
logged into the IDL host, or run a special ``virtual machine'' that includes
an IDL run-time with the application code and access to the license.
However, due to export control policies, a registration and verification
process is necessary on the vendor's website\citep{IDL25} to download the
virtual machine software.  Between the license fee, licensing restrictions
and the virtual machine registration issues the whole process is onerous
compared to open-source solutions.
\item The virtual machine running the IDL program was notoriously unstable
and would crash very easily without any clear idea of the cause.
%% It is not clear how much of this is due to the program design, the IDL
%% virtual machine implementation, the host installation, etc.
%% Users were cautioned in the documentation about this, and to save their work
%% often.
Needless to say, this did not impart a sense of confidence in the software.
\item Fewer and fewer staff are knowledgeable in IDL application development
and the original author of the software has largely moved on to other
responsibilities.
\end{itemize}

\section{Porting from IDL to Python}
Given the issues described above, we were interested in porting the
application from IDL to Python.
Python has good support for astronomical applications with
good base frameworks like  \emph{astropy} or \emph{skyfield}, and a number
of GUI frameworks to choose from.

We acertained that the Python version of the application would need to
(1) Load and display a FITS file, and adjust contrast or set cut levels
on the image for good visibility of the overlays;
(2) Draw overlays on the image to show the field of view, detector positions,
slit and hole positions with labels, spectral dispersion, and
(3) provide a UI with controls for loading and saving MDP files,
adjusting parameters for slit position, width, etc. and exporting the mask
cutting SBR file.

Subaru Telescope uses the \emph{Ginga} package\citep{Jeschke12A},
%\citep{Jeschke13A},\citep{Jeschke15A}
an open-source toolkit for building
astronomical viewers in Python, in a number of different applications.
%% Ginga provides a ``reference viewer'' that has a plugin architecture,
%% where new features can be easily added via writing simple Python modules.
%% Plugins feel more like self-contained individual programs and are relatively
%% small (generally a few dozen to a few hundred lines of code) so they are
%% easier to understand, code and maintain than starting a large application
%% from scratch that needs to recreate various FITS manipulation and graphics
%% overplotting routines.
This viewer already provides many of the basic features needed for
this program including good support for viewing FITS files and drawing
graphical overlays.
%% With this in mind, we thought that it might make a great
%% project for an intern to take on, writing the mask design program as a
%% Ginga plugin.
During the summer of 2025, our intern Minkyeong Kim
%\footnote{See \url{https://www.akamaihawaii.org/interning/}}
took on the task of turning this IDL program into a Ginga plugin within
an approximate 7 week time span.
It is worth noting that Kim had no knowledge of astronomy or
spectroscopy before starting the project, but did have a good understanding
of Python programming.

The basic procedure for guiding Minkyeong toward the goal was as follows.
First, we explained in general terms what the IDL program should be doing and
provided a copy of the IDL code. Second, We gave her a few different example
sets of FITS files with input (mask design) and output (mask cutting) files.
Third, we gave her time to experiment with the IDL program and understand
the basic UI and how that worked. After this initial introduction, we
introduced Ginga, showing the features that covered much of the needed
functionality and explaining how the plugin architecture works (and showing
a few examples of plugins). We guided her to get a skeleton of a new plugin
working with a very simple UI and then answered questions as needed as she
iterated toward a solution.

After the seven week internship, the MOIRCS Mask Builder plugin was fully
functional.  Our staff continued to polish and do mild refactoring on the
program for an additional few weeks to make the operation a bit more
intuitive and maintainable, as well as adding some additional features.

\section{Using the MOIRCS Mask Builder Plugin}

Using the MOIRCS Mask Builder is fairly straightforward coming from the old
workflow.  After starting the plugin, all files can be loaded from the plugin
UI, shown in the right side of Figure \ref{fig1}.
The ``File'' menu at the top of the UI allows loading and saving of various
kinds of files, while the panels below that allow the user to select which
overlays are shown, add and edit holes and slits, select a grism, or adjust
the default parameters for the grism.

An object (slit or hole) can be added by clicking precisely within the image,
outlining a box around an object to find the center of it, or typing directly
in the position in either pixels or celestial coordinates.
%% Figure \ref{fig2} (right) shows the display with the spectra dispersion
%% overlay enabled.
%% These dispersion overlays are based on the grism attributes
%% and can be fully customized by the user.
%% Tick marks within the dispersion overlays can be turned on in different
%% increments of angstroms to get a better understanding of the dispersion
%% effect.


\section{Advantages of the MOIRCS Mask Builder Plugin}
The new plugin offers a number of desirable features over the older IDL
program:
\begin{itemize}
\item Ginga is open-source and licensed under the generous and unrestrictive
BSD license that the rest of the Python ecosystem is based on, so there are no
restrictions on where it can be installed and used.
\item The instability of the old program is eliminated; Ginga is an extremely
stable program that has been in continuous nightly use at the observatory
since 2012.
\item The plugin allows performant zooming and panning, and allows us to
provide a position angle feature so the user can type in a position angle to
see the spectral dispersion with various rotations vs. the focal plane.
\item The plugin correctly handles overplotting on different pixel scales,
so the user should no longer have to provide an image pixel-scaled to an
exact value (although we still need to verify that the mask cutting file is
generated correctly with alternate scales).
%% \item The plugin adds some useful features, such as the ability to not show
%% either of the detectors, to choose the tick marking increment of the
%% spectral dispersion plots, an undo feature, and an enhanced ECSV format for
%% saving the mask design that uses \emph{Astropy} tables to store various
%% metadata, saving a lot of UI configuration for the user (FITS files
%% automatically reloaded, cut levels restored, grism selection and modified
%% attributes restored, etc).
\end{itemize}

\section{Getting and Installing the MOIRCS Mask Builder Plugin}
To use the MOIRCS Mask Builder Plugin you need to first install Ginga and then
one additional package.  We recommend using a virtual python environment such
as \emph{virtualenv}, \emph{conda} or similar to install and run this plugin.
An example installation is shown below assuming a conda-type system:
{\small
\begin{verbatim}
$ conda env create -n moircs_mdp python=3.13
$ conda activate moircs_mdp
$ pip install ginga[qt6]
$ pip install git+https://github.com/naojsoft/naojutils
\end{verbatim}}

After installing this way you can run the MOIRCS MBP by simply typing
``ginga'' on the command line inside your conda environment, and then
opening the plugin from the ``Plugins => Subaru => Planning => MOIRCS Mask Builder''.

%% \section{Future Plans}
%% Some users have requested the ability to provide a list of celestial
%% coordinates for the slits and holes (from GAIA, for example) and have the
%% initial layout auto-generated.  In such a case, if the coordinates are
%% precise enough it should not even be necessary to double check their position
%% with a visual image loaded.  We are thinking about this possibility.

\bibliography{184}  % For BibTex

\end{document}
