Instructions to download and process the 2-MASS star catalog to generate the
full version of Figure 7 in the "THEORETICAL LIMITS OF STAR SENSOR ACCURACY"
journal article.


System requirements:
 Recommended at least 8 GB of RAM;
 At least 100 GB of free disk space (40 GB to store the source star catalog
 in gzip format, 20 GB to store the the preprocessed star catalog and 40 GB to
 store the sorted star catalog). This disk space can be provided by an external
 hard-disk. Set the locations where to find the source catalog and where to
 store processed data in "load_2mass_settings.m".

Sleep mode in Windows and Power Management:
 If you are an MS-Windows user, depending on the energy settings of your
 machine, your computer may go to sleep after some minutes of user not touching
 the mouse and keyboard. To prevent this from happening and interrupting the
 computations, you can disable this by changing Energy Saving configurations
 in the Control Panel. Alternatively, you can play a media file in the
 background, or use a program to prevent Windows from entering sleep mode.
 One such a program is available at: https://dlaa.me/blog/post/9901642.
 For the convenience of the user, I also bundled another program that prevents
 Windows from putting the computer into sleep mode. It is inside the "winutil"
 folder. Source code is also included.

Downloading the source catalog:
 To use the 2MASS star catalog, download psc_aaa.gz to psc_bbi.gz (total of 92
 sections) from https://irsa.ipac.caltech.edu/2MASS/download/allsky/ (total
 download size of about 40 GB).

Catalog preparation:
 Warning: Catalog preparation usually takes many hours to complete!

 The easiest way to prepare the 2-MASS catalog is to run the file
 "prepare_all_2mass.m" in Matlab, GNU Octave or equivalent program,
 after the following prerequisites are fulfilled:

 Prerequisites to run the catalog preparation "prepare_all_2mass.m" file:
 * Matlab, GNU Octave or any other compatible system.
    GNU Octave is a free open source software which can be
    downloaded from https://www.gnu.org/software/octave/
 * The program "read_2mass_mat.exe" or "read_2mass_mat", built from
   "read_2mass_mat.c". It should be placed at the current folder (exact location
   where it should be placed defined in "load_2mass_settings.m"). A prebuilt
   version of read_2mass_mat.exe is found in the prebuilt/win folder.
 * The 7-Zip zip/unzip utility (https://www.7-zip.org/).
   (If the user does not wish to install 7-Zip, he/she can modify the
    Matlab/Octave scripts/functions to use another unzip utility or to read
    manually unzipped 2-MASS catalog sections).
 * Set correct paths by editing the file "load_2mass_settings.m".

 "prepare_all_2mass.m" calls "convert_all_psc.m", "sort_2mass_JHK.m" and
 "sort_2mass_HKJ.m". "prepare_all_2mass.m" takes many hours to complete.

 "convert_all_psc.m" pre-process the 2MASS star catalog, saving its 92 sections
 as 92 .mat files for further processing. This function needs the program
 read_2mass_mat.exe, which can be built from read_2mass_mat.c. For Windows
 users that do not whish to install a C compiler, there is a prebuilt version
 of read_2mass_mat.exe which is found in the "prebuilt/win" folder.

 "sort_2mass_JHK.m" sorts the 2MASS star catalog by J, H, Ks magnitudes (in
 that order of priority), placing the brightest stars at the beginning. The
 sorted catalog is saved in 20 sections. In fact, due to memory limitations
 of most computer systems, this function does not load the whole catalog into
 memory, but works only with stars that will be saved in each of these 20
 sections. This had to be done due to the huge size of the 2MASS star catalog.
 In total, "sort_2mass_JHK.m" process 470,991,651 point sources (mostly stars).

 "sort_2mass_HKJ.m" is similar to "sort_2mass_JHK.m", but sorts the 2MASS
 star catalog by H, Ks and J magnitudes. It processes 470991651 point sources.

 Once the catalog preparation process is completed, run the "calc_2MASS.m"
 script in the parent folder to compute the Fisher information matrix for
 the 2MASS star catalog, needed by "plotFig7.m" in the parent folder.
 Please be advised that the "calc_2MASS.m" script may take many hours to
 complete, for example, it took more than 11 hours to complete in an i7 CPU
 running at 3.4 GHz with Octave 5.1.0.

Notice: When preprocessing the star catalog, "read_2mass_mat.exe" will give a
warning in some catalog sections about the existence of catalog entries with
null fields. This is normal. These few entries with null fields (about 10
per catalog section) are rejected.

Notice for GNU-Octave users: The scripts and functions described here change
the default format used by Octave to save .mat files. To restore the default
behavior, close and reopen your Octave session or read "setup_octave_savemat.m"
for help.

For licensing information, see file License.txt.

For more instructions about the 2MASS star catalog, visit
https://old.ipac.caltech.edu/2mass/


Description of files:

 01readme.txt            => This file.

 check_2mass_paths.m     => Helper function for "sort_2mass_JHK.m" and
                            "sort_2mass_HKJ.m" used to check paths in
                            "load_2mass_settings.m".

 check_2mass_settings.m  => Helper function for "convert_all_psc.m" and
                            "prepare_all_2mass.m" used to check paths in
                            "load_2mass_settings.m".

 convert_all_psc.m       => Converts 2MASS PSC catalog sections into .mat files.
                            Used by prepare_all_2mass.m.
                            Uses the program read_2mass_mat.exe, as specified in
                            the conf.convProg field at the end of
                            load_2mass_settings.m, to do the conversion.

 isoctave.m              => Returns true if it is running in Octave.
                            Used by setup_octave_savemat.m.

 LICENSE.txt             => Terms and conditions for modifying and
                            redistributing the files in this package.

 load_2mass_settings.m   => User configurable file, where the user should
                            define folders to be used during the conversion
                            process.

 num2alfcount.m          => Converts an integer between 0 and 675 to a two
                            letter code. Used by: check_2mass_paths.m,
                            check_2mass_settings.m, convert_all_psc.m,
                            sort_2mass_HKJ_sub.m and sort_2mass_JHK_sub.m.

 prepare_all_2mass.m     => Main function/script used to automate all the
                            2MASS catalog preparation. Calls all other *.m
                            (Matlab/Octave) functions in this folder.

 prepare_fname.m         => Helper function used by convert_all_psc.m.

 read_2mass_mat.c        => Source code of read_2mass_mat.exe.

 read_2mass_txt.c        => Old version of read_2mass_mat.c that converts
                            2MASS star catalogs to text files (no longer used).

 setup_octave_savemat.m  => Changes default mode used in GNU-Octave for saving
                            .mat files. It has no effect in Matlab.
                            Used by sort_2mass_HKJ.m and sort_2mass_JHK.m.

 sort_2mass_HKJ.m        => Creates a copy of the 2MASS PSC catalog sorted
                            by H, Ks and J magnitudes with 20 sections.
                            Used by prepare_all_2mass.m.

 sort_2mass_HKJ_sub.m    => Helper function for sort_2mass_HKJ.m.

 sort_2mass_JHK.m        => Creates a copy of the 2MASS PSC catalog sorted
                            by J, H and Ks magnitudes with 20 sections.
                            Used by prepare_all_2mass.m.

 sort_2mass_JHK_sub.m    => Helper function for sort_2mass_JHK.m.


 prebuilt/win/read_2mass_mat.exe => Prebuilt executable version of the program
                                    read_2mass_mat, built from read_2mass_mat.c.


 winutil/LICENSE.txt => Terms and conditions for using, modifying and
                        redistributing the program nosleep (see files below).

 winutil/nosleep.c =>   Source code of a small utility used to prevent
                        MS-Windows from putting the machine into sleep mode,
                        useful to prevent interruptions during long
                        computations.

 winutil/nosleep.exe => Small open source utility to prevent MS-Windows from
                        putting the computer into sleep mode.

 winutil/readme.txt  => Instructions for nosleep.exe.



By Marcio A. A. Fialho
Sao Jose dos Campos, 17 of September 2019.