User Manual
User Manual
1
User Manual
Document Change History
Date: 5-1-01
Name: Brian D. Boyd
Section: All
Description: Original Version
Date: 5-2-01
Name: Brian D. Boyd
Description: Combined title page, change history, TOC, and text into single document, update TOC to
reflect changes
2
User Manual
Table of Contents
Section
Page #
1. Introduction ……………………………………………….………4
1.a Purpose of Document
1.b Target Audience
1.c Document Conventions
1.d Reader Starting Points
2. Running the Program ……………………………………………..5
2.a Execution Commands
2.b Options
3. Output ……………………………………………………………....8
3.a Standard Out
3.b Files and Directories
4. Browsing the Index ………………………………………….……..9
5. System Requirements ……………………………………….…….10
5.a Domain Requirements
5.b Software Requirments
6. Installation …………………………………………………….……11
6.a Files Required
6.b Compiling the Program:
7. Maintenance Procedures and Issues ………………….…………..12
7.a Editing the source code
7.b Updating Manuals
8. Troubleshooting ………………………………………….…………13
9. Additional Information ………………………………….…………14
9.a Further Documentation
9.b Contact Information
10. Appendices …….....………………………………………………..15
10-A. Standard Out Sample
10-B. NI.html Sample
3
User Manual
4
1. Introduction
NanoIndex is a program created for the nanoManipulator team to make it easier for them
to locate and recognize their vrpn files. The program takes as input a directory to index
and any options. The directory is searched for a ReadMe file and any vrpn files. The
vrpn files found are run in nano, the nanoManipulator viewing software, using the
-index option. With the –index option, nano will play through the vrpn file and
periodically generate tiffs. These tiffs are then converted to jpegs and deleted. After all
vrpn files in a directory have been run in nano, an HTML file is created for the directory.
The HTML file contains the contents of the ReadMe file, links to any subdirectories, and
thumbnails of the jpegs for each vrpn file.
(For information about the implementation of NanoIndex, refer to the NanoIndex
Implementation Manual.)
1.a Purpose of Document
This manual is to serve both as a user level understanding of how to run NanoIndex as
well as how to compile, test, and edit the program.
1.b Target Audience
The target audience of this document is the individual(s) who will be running and
maintaining NanoIndex for the nanoManipulator group. This document assumes that the
reader is familiar with running commandline programs in a UNIX environment. The
reader should also have knowledge of the nano viewing software.
1.c Document Conventions
Section titiles - Times New Roman 16, bold
Subsection titles - Times New Roman 14, bold
Sub-Subsection titles - Times New Roman 12, bold
Code – Courier New 11
All other – Times New Roman 12
1.d Reader Starting Points
1.d-1 Running the Program
If the NanoIndex program has already been properly installed and you simply want to run
an indexing session, go to Running the Program (section 2).
1.d-2 Installation
If you are installing NanoIndex, first determine that you can meet all System
Requirements, (section 5), then refer to Installation (section 6).
1.d-3 Maintenance
If you want to make changes to NanoIndex and have already studied the NanoIndex
Implementation Manual that accompanies this document, go to Maintenance
Procedures and Issues (section 7).
1.d-4 Problems
If you experience any problems while running NanoIndex or are unsure why you are
receiving a particular error, refer to TroubleShooting (section 8).
User Manual
5
2. Running the Program
2.a Execution Commands
To Execute the NanoIndex.class file type:
java <java options> NanoIndex <directory name> <options>
(To see a list of available options for java, type java at the command prompt.)
Examples:
If you wanted to run NanoIndex on the directory foo with no options, you would type:
java NanoIndex foo
If you wanted to run NanoIndex on foo and recursively index all subdirectories of foo,
you would type:
java NanoIndex foo –rc
NOTE: Please see TroubleShooting 8.1 before using the recurse option.
If you wanted to index the directory samson and set the vrpncookie to “vrpn: ver. 6”, you
would type:
java NanoIndex samson -vrpncookie “vrpn: ver. 6”
See the Options section (section 2.b) that follows for a complete description of all options
available and how to use them.
User Manual
6
2.b Options
Options can be typed in any order and any combination but they must follow the starting
directory name. Each option must be typed individually and should be separated by a
space. To use an option that requires an argument, type the option invoker followed by a
space followed by the option argument. If an argument contains whitespace, then you
must enclose the argument with double quotes.
2.b-1 Options Table
Option Invoker
-rc
Option Name
RECURSE
Argument
Default Value
none
False
-ri
REINDEX
none
False
-nanocmd
NANO_CMD
<command string>
“nano –i”
-nanoopts
NANO_OPTS
<option string>
<empty string>
-nanospeed
NANO_SPEED
<integer string>
“30”
-convopts
CONV_OPTS
<option string>
<empty string>
-vrpncookie
VRPN_COOKIE
<string>
“vrpn: ver”
-jpegw
JPEG_W
<integer string>
“200”
-jpegh
JPEG_H
<integer string>
“160”
-bgpath
BG_PATH
<path string>
“/afs/unc/proj/stm/public_h
tml/nanobkg.jpg”
2.b-2 Option Descriptions
RECURSE: Causes NanoIndex to recurse through and index all subdirectories of the
starting directory after indexing the starting directory.
Warning: Please refer to TroubleShooting 8.1 before using the RECURSE option.
REINDEX: Reindexes any previously indexed vrpn files by deleting any existing jpeg’s
and indexing the vrpn again by running the vrpn file in nano again to create new tiff
snapshots.
NANO_CMD: The command used to execute the nano viewing software.
User Manual
7
NANO_OPTS: Any options other than –index and speed to be appended to the command
that executes nano.
Note: NanoIndex provides no error checking to ensure that the argument of this option
contain valid options for nano. The argument string is simply appended to the nano
command and relies on nano to react appropriately.
(To see a list of options available for nano, type nano <jargon> at the command
prompt).
NANO_SPEED: A nonnegative integer to append to the command that executes nano
CONV_OPTS: Any options to append to the command that executes convert
Note: NanoIndex provides no error checking to ensure that the argument of this option
contain valid options for convert. The argument string is simply appended to the convert
command and relies on convert to react appropriately.
(To see a list of options available for convert, type convert with no arguments at the
command prompt).
JPEG_W: width in pixels of thumbnail images in html page
JPEG_H: height in pixels of thumbnail images in html page
BG_PATH: Path to image file used as background of html pages
User Manual
8
3. Output
The output of a NanoIndex session includes messages output to standard out as well the
files and directories created by the program.
3.a Standard Out
3.a-1. Initialization Message
The program will first output to standard out a list of program variables and their values
followed by the message “NanoIndex initialized and Starting.”
3.a-2. Indexing Messages
As the program executes, it will output to standard out simple messages each time it
enters a new stage of indexing. These messages can be used to follow the process flow of
an indexing session.
The messages are:
“Indexing Dir” : This message will be output each time the program begins indexing a
directory. Each output of this message is preceded by a printout of the current date and
time. The message will contain the number of directories already indexed and the name
of the directory currently being indexed.
“Indexing Vrpn” : This will be output each time the program begins indexing a vrpn. The
message will contain the number of vrpn files already indexed and the name of the vrpn
file currently being indexed.
“Running Nano”: This will be output each time the program executes nano. The message
will contain the name of the vrpn file being run in nano and the value of NANO_OPTS.
“Converting” : This will be output each time the program executes convert, i.e. each time
it converts a tiff to a jpeg.
“Creating Html” : This will be output each time the program creates a new html file (or
overwrites an existing html file).
“Is Indexed” : This will be output when a vrpn file is about to be indexed and is already
indexed. The message will contain the name of the vrpn that is already indexed.
If REINDEX is off, the vrpn will be skipped. If REINDEX is on, the vrpn will be
unindexed and then an “Indexing Vrpn” message will appear.
See Appendix A (section 10-A) for a sample output of the initialization and indexing
messages.
User Manual
9
3.b Files and Directories
NanoIndex creates an HTML file for each directory indexed along with a directory of
jpeg’s for each vrpn file indexed.
3.b-1 HTML File
A file named NI.html is created for each directory indexed. This file will be created inplace in the directory and will contain the name of the directory, the contents of the
directory’s readme file (if one exists), links to any subdirectories, and sequentially
arranged thumbnail images created for each vrpn file in the directory.
To see the layout of an NI.html page refer to Appendix B (section 10-B).
3.b-2 Jpeg Directory
A directory will be created for each vrpn file indexed that contains the jpeg’s associated
with that vrpn file. The directory will be in the same directory as the vrpn file and will be
named “<vrpn file name>_NI”.
4. Browsing the Index
The program will create an HTML file called NI.html for each directory indexed. An
NI.html file can be viewed by opening it in a browser such as Netscape or Internet
Explorer. The user can enter the index through any NI.html file and browse through the
tree of NI.html files by clicking on the Parent Directory and subdirectory links. The
thumbnail images may be clicked on to view the image in its full original size.
See Appendix B. for a sample NI.html file that displays the layout of the ReadMe file,
subdirectory links and vrpn images on the HTML page.
User Manual 10
5. System Requirements
The only domain requirement for NanoIndex is that in run in a UNIX-based environment.
The NanoIndex program has three software dependencies. The machine that runs
NanoIndex should have proper installations of a Java Virtual Machine, nano (the
nanoManipulator stream file viewing software), and convert (an image converter utility).
The user should have his PATH environment variable set such that he has access to java,
nano, and convert.
5.a Domain Requirements
5.a-1. UNIX-based environment
The NanoIndex program must be run in a UNIX-based environment.
5.b Software Requirements
5.b.-1 Java
NanoIndex is written in the Java language so it requires the java compiler utility javac
and a java virtual machine java. The NanoIndex program requires Java version 1.2 or
later.
5.b.-2 nano
NanoIndex uses the –index option of nano to create tiff images, therefore, NanoIndex
should have access to a version of nano that provides the –index option.
5.b.-3 convert
To convert the tiff images generated by nano to jpeg images viewable in a browser,
NanoIndex uses a utility called convert. The convert utility is part if the ImageMagick
suite and is packaged with SGI machines. It can be found in the directory
/usr/freeware/bin.
(Refer to Further Documentation (section 9) for more info on convert.)
User Manual 11
6. Installation
Only after you are sure you can meet the above System Requirements (section 5) should
you install the program.
6.a Files Required
All source code required is in:
NanoIndex.java
To run the program you will need the compiled source code:
NanoIndex.class
NanoIndex is also accompanied by a set of test directories and an expected output file.
NI_test_in_dir
NI_test_out_dir
NI_test_output
See Testing Files (section 7.a-3.a) for a description of these files.
6.b Compiling the Program
To compile the source file (a .java file) into java bytecodes (.class file) type:
javac <javac options> NanoIndex.java
The only output of compilation should be the file NanoIndex.class.
Normal compilation should not require the use of any options for javac.
(To see a list of available options for javac, type javac at the commandline.)
User Manual 12
7. Maintenance Procedures and Issues
7.a Editing the source code
7.a-1 Revision Control
Any and all revisions made in the source code should be well documented. This
documentation should include the date of revision, the reviser’s name, and a functionlevel description of the revisions made. The owner of the NanoIndex should determine if
a particular revision control software will be used to meet these requirements.
7.a-2 Rebuilding the system
Refer to compiling the program (section 6).
Note that in order for javac to compile NanoIndex correctly, the source file must maintain
the same name “NanoIndex.java”.
7.a-3 Testing the System
7.a-3.a Test Files
The NanoIndex program is accompanied by a set of test directories along with a test
output file. The directories are NI_test_in_dir and NI_test_out_dir. The test output file is
NI_test_output.
7.a-3.b Test Procedure
To test the system, you should first make a copy of NI_test_in_dir, so that it can be used
again. Then, run NanoIndex on the directory with the recurse flag on and redirect the
output to a file. If the program terminates appropriately, you should then compare the
contents of the directory to that of NI_test_out_dir and compare the contents of the output
to that of NI_test_output.
If the program does not terminate correctly, then you may want to refer back to the
NanoIndex Implementation Manual.
7.a-3.c Updating Test Files
If you make changes in the source code such that the contents of NI_test_out_dir and/or
NI_test_ouput are no longer valid output of the test procedure, then you should update
these files so as to maintain their validity for any future tests of revisions.
7.b Updating Manuals
Updates to this User Manual or the NanoIndex Implementation Manual should be
documented in the manual’s document change history. The documentation should
include the date, author, section number, and description of the revision.
User Manual 13
8. Troubleshooting
8.1 What if the program terminates with an OutOfMemoryError?
The default value for the java heap size is only 16 megabytes. If NanoIndex is run with
Recurse on a directory with several levels of subdirectories it will be necessary to use the
–mx java option to set the maximum heap size. Otherwise, NanoIndex will terminate
prematurely with an OutOfMemoryError. A good value to use is 256 megabytes if it is
available, though this may not be enough if the directory has a large number of levels.
For example, if you wanted to index the directory delilah with Recurse on with a heap
size of 256 megabytes, you would type:
java -mx256m NanoIndex delilah -rc
8.2 What if all the vrpn files on the html pages have the line “No Images Created for
this File,” instead of the expected thumbnail images?
This could mean several things:
1) There was not enough disk space for nano to create the tiffs
2) nano created tiffs, but there was not enough space to convert the tiffs to jpegs
3) nano did not create any tiffs, hence there were no tiffs to be converted
To correct the problem, first, try to create some space and then run NanoIndex again.
There should be enough space to create the tiffs for one vrpn file plus one jpeg, since
each tiff is deleted as it is converted.
If there is ample space and still no images appear on the html page, then there is a
problem with nano. Try testing the –index option of nano separately.
8.3 What if NanoIndex fails to index a known-to-be vrpn file?
Make sure the –vrpncookie is set appropriately. The default is to index all files that start
with the line “vrpn: ver”, but if you set the –vrpncookie to a different string, then only
those files that start with the set cookie will be indexed.
8.4 What if the last message output by NanoIndex is “Running nano:...” and nothing
else is output for a long time (hours)?
(Depending on the length of a stream file, it should not take more than a few minutes for
nano to play a file and create tiff snapshots.)
If no other statements are output after several minutes, then there is a problem with nano.
NanoIndex provides no recovery from nano hanging. When nano is called, NanoIndex
waits forever for it to return. The only thing to do is to terminate NanoIndex with CTRL
C and run NanoIndex again. Any vrpn files indexed in the session that was aborted will
remain indexed and will be skipped over (unless the reindex flag is set).
User Manual 14
9. Additional Information
9.a Further Documentation
For details on the java API’s used by NanoIndex, go to:
http://java.sun.com/j2se/1.3/docs/api/index.html
For details on convert, go to:
http://www.imagemagick.org/www/convert.html
For information on the developmental history of NanoIndex, contact the instructor of the
Comp 145 team that created the product:
Greg Welch welch@cs.unc.edu
9.b Contact Information
This product was created by the Comp 145 Team consisting of:
Director
Jeff Adams
adams@email.unc.edu
QA
Brian Boyd
bdboyd@email.unc.edu
Lib/Admin
Glenn Jessup
jessup@email.unc.edu
Producer
Jeff Townsend
jefftownsend@nc.rr.com
This product was created in collaboration with:
Russell Taylor, member of nanoManipulator team, Client of Comp 145 Team
taylorr@cs.unc.edu
David Marshburn, member of nanoManipulator team, created the -index option for nano
marsbur@cs.unc.edu
User Manual 15
10. Appendices
10-A. Standard Out Sample
User Manual 16
10-B. NI.html Sample