Installing GREYCstoration on Mac OS X
GREYCstoration is a denoising program based on nonlinear multi-valued diffusion partial differential equations, both provided by Dr. David Tschumperle. The Chandra EPO imaging group has recently begun testing the program on their X-ray data, with positive results. The program is open source and is given in C++ source code format, which allows the program to be used on Windows, Mac, Unix, and Linux.
In light of people having difficulty compiling the code Dr. Tschumperle has begun to post the code in pre-compiled binaries for most of the popular operating systems. This has bypassed the complicated step of compiling the code itself, but leaves one important component untouched, ImageMagick. ImageMagick is needed for some basic routines in GREYCstoration and can be a challenge to install. This web-page has been posted as an installation guide for both GREYCstoration and ImageMagick. While this page is aimed for the astronomical community, anyone can follow the guide. In addition, the guide only covers the OS X system at the moment. Other operating systems will be covered if requested or wish to contribute their experiences on other operating systems.
Step One: ImageMagick
The easiest way to installing ImageMagick is through Fink, an open source program that ports many Unix programs for Mac OS X. For a quick binary install (click and say 'yes' installation) you can visit Fink download site. Fink needs two programs installed, to run without any issues, that are freely available from Apple: X11 and Xcode Tools. Click on the following link for a good visual guide for installing X11.
http://www.simplehelp.net/2006/10/22/how-to-install-x11-in-os-x/
Xcode Tools is a little bit more complicated. There are two sources where you can access Xcode Tools. The first is on your Mac OS X installation disc (disc 1) and the other is from the Apple Developer's website. To download the Xcode Tools program you have to sign in with an Apple account or create one, which is free. Be warned, the file is nearly one Gigabyte in size, so the download will take some time. It is highly suggested to install Xcode Tools from the Apple Developer site since it is most up to date and you will run into less problems when programs want to access the Xcode Tools application. If you decide to install from the disc, make sure you are installing at least version 2.2.1. You can refer to the graphics below to finding the file you need for installation and the pdf file to check which version you have on the disc.
After getting X11 and Xcode tools installed we can start working with Fink. Assuming that you have downloaded Fink from the website we can open up the dmg file and click on Fink***Installer.pkg file. After Fink has been installed you can install an application that provides a visual interface when using Fink. You can find this file in the FinkCommander folder and drop it into your Applications folder.
Believe it or not, you have now passed the most complicated part of the installation process to get ImageMagick working. Now, open up FinkCommander and in the search box on the upper right hand area, type in 'imagemagick'. This will bring up a list of files that you can install. Click on the file name 'imagemagick' and install it by clicking left-most button that has a blue cross on it.
That's it, your done with all the basic files and programs needed for GREYCstoration to run.
Step Two: GREYCstoration
If you have not already downloaded the pre-compiled code from Dr. Tschumperle's site, then go grab the file. Once the zip file from Dr. Tschumperle has been downloaded open it and go into the unzipped folder. In the unzipped folder you will see multiple "GREYCstoration_***" files. Choose one of the mac files that correlates to the processor version you have on your Mac (PPC or Intel) to work with.
From this point forth we will have to work in the terminal. You can either use the X11 terminal or the Terminal.app in the /Applications/Utilities/ folder. When you installed Fink, the Terminal.app application was configured to read the ImageMagick commands (necessary for GREYCstoration to run). To test whether the ImageMagick installation worked type (the dollar sign is normally used to inform the reader that they are looking at a terminal command line example)
$ convert logo: logo.gif
$ identify logo.gif
$ display logo.gif
When the commands above work successfully, you will see an image with a bearded wizard pop up. If you choose to use the X11 terminal instead, you will have to edit the '.bashrc' or '.tcshrc' file in your home folder. If there's no .bashrc file you can create one in the home directory. This is best done through the vi or emacs editor in terminal. If you're using bash you can edit your .bashrc file in the home folder and add
source . /sw/bin/init.sh
If you're using tcsh you should edit the '.tcshrc' file and add
source /sw/bin/init.csh && . /sw/bin/init.csh
Now, you need to move the "GREYCstoration_***" file to the /usr/bin/ folder. This is an administrated folder, so when you type the command in the terminal to move the "GREYCstoration_***" file you need to use sudo command. Refer to the graphic below to see how to do it via the terminal. Note: typing the whole name of the file in terminal to call up GREYCstoration is very long, so in the graphic example you will see that I first rename the file and then move it to /usr/bin/. Just make sure that there is no application in the /usr/bin/ folder with the same name as what you decide to rename it to.
Since the file has been moved to /usr/bin/ you can access the GREYCstoration program easily from the terminal. Refer to the box below of how you can call up the program to filter an image.
$ gru -restore image.tif
There are numerous parameters that you can append to the program in the command line. For example, if you are working with a 16 bit TIFF image, then you would do the following:
$ gru -restore image.tif -bits 16
To learn more about the GREYCstoration parameters type in the terminal
$ gru -help
and read the output in the terminal in detail.
Enjoy the program! You can find a nice tutorial on Dr. Tschumperle's website for further examples. If you have any questions, comments, or corrections send Eli Bressert an email.