Cratermatic Session Tutorial

First Commands

• Go to the directory containing the Cratermatic executable, probably named 'craters'.
• Start Cratermatic in interactive mode with the command './craters'. Note the empty stack and the 'command>' prompt.
• Let's add a number to the stack: type '3.14159' (or whatever your favorite number is) at the prompt and press [ENTER]. The number will appear as the only stack item, and Cratermatic will await further input.
• Add a few more numbers to the stack in the same way.
• Notice how the stack items are numbered. The leftmost number indicates position in the stack, with '1' being the most recently added item. Whenever a new item is added, the items already in the stack are shifted up by one position. The second number, in parentheses, indicates the order in which the objects were added to the stack. The first object that you add will always be '(1)', the second '(2)', etc., no matter where they are in the stack.
• You don't need to enter the commands one-at-a-time; you can chain together as many commands as you want to type all on one line. For example, the command sequence '1 2 3 4' will add those four numbers to the stack.

Stack Operations

• You can use the 'drop' command to delete stack item 1.
• Try using the 'swap' command to swap the order of stack items 1 and 2.
• You can use the 'dup' (short for 'duplicate') command to make a copy of stack item 1.
• You will often need to bring a certain stack item to position 1 in order to apply commands to it. To bring the item at position 3 down to position 1, use the command '3 rot' ('rot' is meant to be short for 'rotate', not 'decompose'). The item previously at position 3 will now be at position 1, and the two items previously below it have been pushed up to fill the gap. Note that '2 rot' is the same as 'swap'.
• To delete multiple items from the stack, you can use the 'dropn' command. For example, '3 dropn' will drop the lowest 3 items on the stack (not including the number '3' used for the command).
• To remove all the items from the stack, use the command 'clear'.

File IO

• You probably wanted to use Cratermatic to do more than shuffle around a list of numbers. Let's learn how to get some actual image data on the stack. In order to load files, you need to put the filename on the stack. There are a few ways to put a string (the filename) on the stack. If, as in most cases, the string contains no whitespace characters, you can simply enter the string prefixed by a '.' as the command; e.g. '.Hello' will put the string 'Hello' on the stack (you may have already accidentally discovered this feature if you tried to enter a number like '.53').
• For the few cases where you need a string containing whitespace, enclose the string in double quotes ('"') or percent signs ('%') (the percent sign syntax was chosen since quotes may get intercepted by the command shell when using Cratermatic in command line mode). For example, the commands '"Hello World!"' and '%Hello World!%' both put the string 'Hello World!' on the stack.
• Suppose you have a sample ArcGIS format dataset named 'sample.txt' in the same directory as the Cratermatic executable (if you don't, you should arrange for such to be the case). To load the dataset onto the stack, first put the filename on the stack as a string with the command '.sample.txt', then load the specified file with the command 'load'. Alternatively, you could have put both commands on the same line, i.e. '.sample.txt load'. Congratulations! You should now have an Image dataset on the stack.
• Note that you can 'dup', 'swap', 'drop', etc. the Image just like any other stack object.
• Like many commands, 'load' has both a long and short command name form. Type '.load help' for a description of the 'load' command, from which you can tell that 'l' is an alternate short form for 'load'. Thus the command sequence '.sample.txt l' is the least-typing-required way to load the 'sample.txt' file.
• Let's make a viewable graphic out of the Image. Make sure that the Image is at position 1 in the stack, then use the command '.sample.bmp draw'. This produces a grayscale '.BMP' format graphics file from the Image, named '.sample.bmp' and located in the directory where you are running Cratermatic from. Go look at it, NOW!
• OK, now that you're back (I hope you were impressed), type '.draw help' to see that 'd' is the short form for the 'draw' command.
• So, grayscale is actually a little boring? With an Image at position 1, try the 'colorview' command. This turns the Image into an RGBImage, a colored graphic that you can '.sampleColor.bmp d' to save to the graphics file 'sampleColor.bmp'. If you look at this one, you should see a color image of the 'sample.txt' dataset, with blue for the low data values grading up through the spectrum to red for the high values.
• With the 'sample.txt' Image at position 1 in the stack, use the command '.sample_copy.txt save' to save an ArcGIS text format copy of the Image data. Unsurprisingly, 's' is the short form for the 'save' command.

Image Manipulation

• You probably wanted to actually do something with the image datasets. OK, that's what Cratermatic is (mainly) for. Bring an Image to position 1, and try '20 blur' to apply a Gaussian blur with a standard deviation of 20 pixels to the Image. Save the image to a graphics file and look at it. It should be rather blurry.
• Cratermatic has lots of image manipulation commands. Type '.ImageMath rhelp' to get a nice long listing of them. By now, you should have figured out how the 'help' and 'rhelp' (short for 'recursive help') commands work. Go explore for a while; just make sure to be back by suppertime.