--------------------------------------------------------------------------- TOPO Version 2.05, August 2000 David L. Windt windt@astro.columbia.edu Copyright (c) 1997-2000, David L. Windt All rights reserved --------------------------------------------------------------------------- This file contains instructions for downloading, unpacking and installing TOPO. Contents of this file: 1. System requirements 2. Downloading TOPO 3. Unpacking TOPO 4. Installing TOPO 5. Starting TOPO 6. Getting help 7. Using TOPO as a XOP extension --------------------------------------------------------------------------- 1. SYSTEM REQUIREMENTS TOPO is written in the IDL language, and will run on any platform supported by IDL. Little or no IDL expertise is required to use TOPO. You will need a valid, licensed copy of IDL to run TOPO. IDL version 5.1 or higher is required. IDL is available from Research Systems, Inc, NOTE: It is possible to run TOPO as an 'extension' to the XOP program (with limited functionality) which is available for Unix and Windows platforms, free of charge to research institutes and non-profit organizations. information on XOP can be found at . Please see section 7 of this document for further instructions. 2. DOWNLOADING TOPO There is only one TOPO distribution, and it should run on any platform supported by IDL. For your convenience, however, I have created several different download files, making it easier for you to unpack TOPO on your particular platform. Choose whichever one you like. Download files: UNIX: topo.tar.Z Windows: topo.zip MacOS: topo.hqx (Note that you may need to explicitly configure your browser to save the download file directly to disk.) 3. UNPACKING TOPO To unpack the file you downloaded, follow the instructions below for your specific platform. When you're finished, you'll end up with a directory called "topo", which will consume approximately 5 MB of disk space. Unix o Unpack the topo.tar.Z file, using the Unix uncompress and tar commands: $ uncompress -c topo.tar.Z | tar -xvf - Windows o Use the (32-bit) WinZip shareware program to unpack the topo.zip file. MacOS o Use the Stuffit Expander freeware program to unpack the topo.hqx file. 4. INSTALLING TOPO The "topo" directory should nominally be installed in a directory that you must create called "user_contrib", inside the main IDL directory. That is, you should end up with a directory called "~idl/user_contrib/topo" (using Unix "notation".) In any case make sure that the topo directory is included in your IDL path; for help with setting your IDL path please consult the IDL documentation. The main TOPO program is distributed as an IDL SAVE file, and all the required IDL procedures and functions are already loaded, so you will not need to include any other directories in your IDL path. However, the topo library makes use of many of the general-purpose routines in the windt library. Although you do not need the windt library to use the topo library (as the needed routines are already compiled into the IDL SAVE file), you may wish to download the windt library nonetheless, in order to have access to the documentation for these routines. If you choose NOT to install the "topo" directory inside of the "user_contrib" directory in the main IDL directory, then you MUST edit the file "topositeconfig.pro", located in the "topo" directory. The file "topositeconfig.pro" contains executable IDL code (although the program itself will not run if you just type ".run topositeconfig.pro" at the IDL prompt.) You must change the value of the 'topohome' variable in this file so that it refers to the actual TOPO installation directory. You can also specify default widget fonts (in "topositeconfig.pro") to be used by IDL, as per your preference: set the value of the 'font_w' variable to the name of a valid IDL widget font for your site. In addition, you can tell TOPO how to display the angstrom symbol and the greek "mu" symbol for the font you specify. 5. STARTING TOPO To load the TOPO library, at the IDL prompt type: IDL> .run topostart You can then try one of the three widget programs, XANLZ_PROF for 1D profile analysis, XANLZ_PSD for 1D PSD analysis, or XANLZ_SURF 2D surface analysis. For instance, you might make up some 2D data like this: IDL> x=vector(0.,100.,256) IDL> y=x IDL> z=randomn(seed,256,256) and then try: IDL> xanlz_surf,x,y,z I've included in the extras.dir directory some sample data to play around with: Try this: IDL> rd_wyko,x,y,z, $ file='...path to topo.../extras.dir/wyko_example.dat' NOTE: On Windows platforms, use the SWAP_ENDIAN keyword in the call to RD_WYKO when reading the 'wyko_example.dat' file: IDL> rd_wyko,x,y,z, $ file='...path to topo.../extras.dir/wyko_example.dat',/swap_endian and then: IDL> xanlz_surf,x,y,z Or this: IDL> rd_digital_afm,x,y,z, $ file='...path to topo.../extras.dir/digital_afm_example.dat' NOTE: On NON-Windows platforms, use the SWAP_ENDIAN keyword in the call to RD_DIGITAL_AFM when reading the digital_afm_example.dat file: IDL> rd_digital_afm,x,y,z, $ file='...path to topo.../extras.dir/digital_afm_example.dat',/swap_endian and then: IDL> xanlz_surf,x,y,z -------------------------------------------------------------------- 6. GETTING HELP You can read all about the individual TOPO routines if you need to go beyond what XANLZ_PROF, XANLZ_PSD and XANLZ_SURF provide. These routines are documented in the html file "topo.html", contained in the "topo" directory. Please let me know about any problems, at . --------------------------------------------------------------------------- 7. USING TOPO AS A XOP EXTENSION (If you will use TOPO with a licensed copy of IDL, you can skip the following instructions.) It is possible to run TOPO as an extension to the XOP program, but with only very limited functionality. That is, the TOPO routines are intended to be used in your own IDL programs, but it is not possible to use your own IDL programs with XOP (in embedded mode, at least.) Thus, you can run the XANLZ_PROF, XANLZ_PSD, and XANLZ_SURF TOPO applications, but that's pretty much it. A. To install TOPO as a XOP extension, perform the following three steps: i. Download and install the XOP program, as described at the XOP website: . ii. Download and unpack the TOPO distribution, following the instructions given above in section 2 and 3. Install the topo directory in the XOP extensions directory. When you complete this step, you should end up with a directory called .../xop/extensions/topo. iii. Copy and rename the appropriate topo4xop.sav_V file - where V=51 for the version of XOP built from IDL version 5.1, V=52 for the version of XOP built from IDL version 5.2, and V=53 for the version of XOP built from IDL version 5.3 - from the topo directory to the XOP extensions directory. When you complete this step, you should end up with a file called .../xop/extensions/topo4xop.sav. That is: for XOP / IDL V5.1: copy .../extensions/topo/extras.dir/topo4xop.sav_51 to .../extensions/topo4xop.sav for XOP / IDL V5.2: copy .../extensions/topo/extras.dir/topo4xop.sav_52 to .../extensions/topo4xop.sav for XOP / IDL V5.3: copy .../extensions/topo/extras.dir/topo4xop.sav_53 to .../extensions/topo4xop.sav B. Starting TOPO as a XOP extension: There are two (platform-specific) ways to run TOPO as a XOP extension: For Unix platforms: At the unix system prompt, type: xop topo4xop -or- From the main XOP window: a. Select Tools -> IDL Macro b. Clear the window and type topo4xop c. Select File -> Quit and accept changes For Windows platforms: Assuming your XOP installation directory is c:\xop, double-click on the file: c:\xop\extensions\topo\extras.dir\topo4xop.bat Note: If your XOP installation is different from c:\xop, you will need to edit the topo4xop.bat file accordingly. -or- From the main XOP window: a. Select Tools -> IDL Macro b. Clear the window and type topo4xop c. Select File -> Quit and accept changes NOTE: If you have trouble installing IMD as a XOP extension, *PLEASE CONTACT THE XOP DEVELOPERS DIRECTLY.* C. Using topo4xop The topo4xop program is a very simple interface to the TOPO library, consisting of buttons to access the three widget programs mentioned above, and a text entry area where you can type TOPO and IDL commands. --------------------------------------------------------------------------- ---------------------------------------------------------------------------