Develop2

This tutorial will walk users through the process of creating a basic DAY IR mosaic of Pavonis Mons.

Step #1: Create a Working Directory

Whenever you're working on a mosaic, you'll want to have a working directory to put all the necessary files in. The mosaicing process can create a VERY LARGE number of files, so it's best to have them contained all in one place. For now, we will create working directories under /themis/mosaic/jhill.

1. On a Moeur Bldg Linux machine, open a terminal window and change directories to /themis/mosaic/jhill by typing:

> cd /themis/mosaic/jhill

2. Create a new directory for you to work in based on your user name. For example, I'll create one named "jonrhill" by typing:

> mkdir jonrhill

3. Now change directory into the directory you just created (replacing "jonrhill" with your directory name) by typing:

> cd jonrhill

4. If you want to see what is in your directory, use the list command by typing:

> ls

- Your directory should be empty since you just created it.

5. Now that your working directory is set, you need to get some images to mosaic. Leave the terminal window with your new working directory open, you'll need it in a minute.

Step #2: Locate Images in JMARS

In order to create a mosaic, you need a list of all the images you want to use. If you're doing a large mosaic, you probably need to generate that list youself, which JMARS can help you with. JMARS will also help you figure out whether your mosaic will have any gaps or not before you actually create it.

1. On a Moeur Bldg Linux machine, open a terminal window and open JMARS by typing:

>jmars clean 0 0

- You will need to log in with your JMARS user account.

2. In the Layer Manager, choose "Add New Layer" -> "Nomenclature"

3. In the "Nomenclature" tab of the Layer Manager, under "Selected Landmarks" choose "Mons". Then choose "Pavonis Mons" under "Landmark". Then click the "Goto" button.

- The Viewing Window will now recenter on Pavonis Mons.

4. Using the zoom menu at the top-right corner of the Viewing Window, zoom to 128ppd.

- You should still be centered over Pavonis Mons.

5. In the Layer Manager, choose "Add New Layer" -> "Stamps" -> "THEMIS Stamps".

- Stamps are outlines of previously acquired images.

6. In the Stamp Layer popup window, enter the following restrictions:

a. Under "Image Location Parameters", choose "Image Type" = IR.

b. Under "Image Location Parameters", right click in the lefthand longitude box and choose "Set Lat/Lon to Bounds of Main View".

c. Under "Viewing Conditions Parameters", choose "Incidence Angle" = 0 -> 88

- This will restrict the search to only Day IR images. For night IR, you would search for 92 -> 180.

- Technically the dividing line between "Day" and "Night" is 90, but by using 2 deg of margin you filter out some unusual images. If you need to fill a gap in a mosaic, you can always expand this to the full range to make sure you're including everything possible.

d. Under "Quality Parameters", choose "Image Rating" = 5 - 7

e. Click "Okay" to search for image stamps.

- A large number of THEMIS IR stamps will appear in the Viewing Window. There will probably be so many that it will be hard to tell them apart.

7. Under the "THEMIS Stamps" tab in the Layer Manager, go to the "Settings" tab. Adjust the "Fill Alpha" slider to about the halfway point.

- Now it should be easier to tell the stamps apart. Also, you can check to see if you have full coverage of the area.

8. In the Viewing Window, left-click and drag to highlight the stamps over Pavonis Mons.

- When you let go of the left mouse button, the selected stamps should all be highlighted in yellow.

9. Right-click on any of the selected stamps and choose "Copy Selected THEMIS Stamps to Clipboard".

- A list of all the selected Image IDs has now been copied to the clipboard for you to paste elsewhere.

10. In the terminal window with your working directory, create a new text file called "mosaic_list" by typing:

> emacs mosaic_list

11. In the text popup window, click "Edit" -> "Paste" to insert your Image ID list from JMARS.

- Unfortunately, JMARS outputs lists in a very unhelpful way. You'll need to hand-edit the text file so there is only one Image ID per line. Also, make sure there are no invisible empty spaces after any of the Image IDs, those will break things later on.

12. Save the text file by doing a Control-X, Control-S.

- Control-S does a search, so you need to do the combined Control-X, Control-S to save the file.

13. You now have a list of images that you can mosaic. However, they are in numerical order, which isn't very useful. Instead, we want them in west-east order. To re-order the list automatically, type:

>/themis/lib/mosaic/vsort.sh -f ./mosaic_list

- This will output a file called "file_list" that we will use for the rest of the mosaicing process.

Step #3: Projecting Images

All THEMIS image products (RDRs, etc) are recorded in camera-centered coordinates. However, if we want to mosaic two or more THEMIS images together, they need to all be projected into a common Mars-based coordinate system. (If we don't, the images have no idea where they belong on the surface.)

1. First, copy the projection script into your working directory by typing:

> cp /themis/mosaic/jhill/scripts/project_ir.sh .

- The projection script has a lot of parameters for the user to set. This version of the script is pre-set with the most common set of parameters to make things a little easier on you. FYI, it's using a Simple Cylindrical projection.

For more advanced users, the projection scripts can be changed to suit your particular mosaic.

1) You can change the projection that the script uses by changing the "set projection..." line. (This works for both "project_ir.sh" and "project_vis.sh"

- For a simple-cylindrical projection: set projection="SIMP:0,OCENTRIC"

- For a north-polar projection: set projection="POLA:90,0,OCENTRIC"

- For a south-polar projection: set projection="POLA:90,0,OCENTRIC"

- For a sinusoidal projection: set projection="SINU:###,OCENTRIC" (where ### is the center longitude of your mosaic)

3) You will need to project your images at the correct resolution. (For images that are going to be combined, like colorized mosaics, make sure both mosaics are projected at the higher of the two image resolutions.) You can set this by changing the "set kmres..." line to read: set kmres=### (where ### is the resolution in km/pixel)

-VIS full-resolution: 0.018 km/pixel

-IR full-resoltuion: 0.100 km/pixel

2) You can change the name given to your jobs when they run on the cluster. This helps other people to know who is running what. You can do this by change the "set group .." line to read: set group="XXXXX" (where XXXXX is the name, a max of five characters is allowed)

2. Run the projection script by typing:

> ./project_ir.sh

- By default, it will look in file_list for Image IDs.

3. Monitor the progress of the projection jobs by occassionally re-doing the "qstat" command from above. When none of your jobs are left on the cluster, go back and re-run the projection script. Do a "qstat" one more time and if you don't see any jobs with your name, then you are done projecting images.

It's always good to re-run the projection script to make sure all the jobs completed successfully. Unfortunately, this script doesn't fail very gracefully and doesn't give you much warning if any of the jobs failed.

4. When you are done projecting, list all the files in your working directory by typing:

> ls

You will see two types of files: 1)I*.cub and 2)null_I*.o* (where * is a wild card) The I*.cub files are the projected images you will use in your mosaic. The null_I*o* files are log files. Unless the projection script failed horribly (believe me, you'll know if it does), then you can remove these log files by typing:

> rm null_I*.o*

WARNING: Always be careful when using the "rm" command with the "*" wild card symbol!

You are now done projecting the images and you're ready to start mosaicing!

Step #4: Creating a Mosaic

1. First, copy the mosaicing script into your working directory by typing:

> cp /themis/mosaic/jhill/scripts/mosaic.dv .

- The mosaicing script also has a lot of parameters for the user to set. This version of the script is pre-set with the most common set of parameters to make things a little easier on you.

2. There are two basic ways to run a mosaic.

a. If you just want to mosaic all the images in your file_list together, run the mosaic script by typing:

> ./mosaic.dv makebounds=3

b. If you want to make a mosaic with a specific latitude/longitude bounding box, run the mosaic script by typing:

> ./mosaic.dv makebounds=1 latrange="#:#" lonrange="#:#"

where # are the user-inputed latitude and longitude ranges.

This is the method you will be using for most of the global and polar mosaic work. Since many people will be working on different pieces at the same time, it will be important that everyone knows what latitude/longitude box they are supposed to be working on.

3. As the mosaic is running, it will output an intermediate file named "full###.png" every time it adds a new image to the mosaic.

'4. The final mosaic will be written out in three different file formats:

1) *.PNG (just a pretty picture)

2) *.HDF (included some geometry information with the pretty picture)

3) *.QUB (an ISIS formatted file that contains all the geometry and projection data with the image data).

Usually you'll want to keep all three file formats around. For the global and polar mosaic project, the most important file is the *.QUB file.