---------------------------------------------------------------------------
                                TOPO

                        Version 2.05, August 2000
				 
                            David L. Windt

                        windt@astro.columbia.edu
               <http://cletus.phys.columbia.edu/windt/idl>

                 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, <http://www.rsinc.com>

        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
        <http://www.esrf.fr/computing/scientific/xop/>.
        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 <windt@astro.columbia.edu>.

---------------------------------------------------------------------------

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:
<http://www.esrf.fr/computing/scientific/xop/>.

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.

---------------------------------------------------------------------------
---------------------------------------------------------------------------
