JptView class readme

You can contact the author, Alexander Patterson IV, at xandey@gmail.com for bug
reports/questions about the software.

You can download the latest version of this program from:
http://www.seas.upenn.edu/~aiv/jptview/

Required packages (Installaction):
	JOGL: download machine specific binarys from http://jogl.dev.java.net/ 
		go to current release, and download the zip for your platform. 
		You will need to add some libraries to your system path,
		and ADD THE CLASSES jogl.jar and glugen jar files TO YOUR
		CLASSPATH.
		
	jptview: add jptview.jar to your classpath
	
Running jptview:
	from the command prompt execute (case sensitive)
		java jptview.JptView [arguments]
		
	on windows, you can add jptview.bat to your path and "jptview [arguments]" 
	should work.
	
	on linux, the script jptview should do the same thing, add it to your path
	and make sure it is executable. 
	
	On a mac should be able to create the same type of files. Please 
	let me know if you do this and I will add your description to this readme.
		
Arguments:
	jptview can load two types of files at the moment. bpt and lst files.
	they are described more below.

Movement:
	Left Mouse button -- rotate
	Right Mouse button -- zoom
	Center Mouse button -- translate
	Shift-Left Mouse button -- translate
	

Selection:
	To select a region: (you can use the hotkey SPACE to switch between selection
	mode and movement mode)
	
	- First go into selection mode
	- Hold down control and click while holding the control key. Each click will
	  add a vertex to the polygon being created (it is drawn on the screen).
	- Release control to select (deselect or toggle) all points within the 
	  polygon.
	  
	You can then save selection by clicking the button on the toolbar which 
	will prompt you to enter a ply file (the format is described below).
	
	NOTE: selection is only supported when viewing an .lst file.
	
File Formats:
	the files are a special ".bpt" file. This is essentially just the rgbxyz 
	data in the format opengl uses dumped to file. There are some utilities
	to write to these files which I will package in here soon for matlab.
	If you are writing these files from anything else, you will need to write
	a writer. Very straightforward. 
	
	foreach point
		write 1 unsigned byte r (0-255)
		write 1 unsigned byte g (0-255)
		write 1 unsigned byte b (0-255)
		write 1 unsigned byte a (0-255)
		write 1 4 byte float x
		write 1 4 byte float y
		write 1 4 byte float z
	end foreach
	
	You will probably want to translate your model by its center so that you don't
	truncate your floats. This could be fixed in the program by reading doubles, but
	openGL only uses single precision, so it should be accomodated in the writer.

	NOTE: The byte ordering is always little endian. The writebpt.m matlab function
	should always write little endian even on big endian architectures.
	
JptView will also open files of the type ".lst", the format is as follows:
	the file is broken up in lines. each line consists of 3 semicolon separated values.
	- First is a character where v means that the viewer should display this file, any 
	  other character means it should not be loaded.
	- Second is the path to the .bpt file (as described above) A relative path may work,
	  but absolute is recommended as one can assicate this type of file with jptview
	  bat file and open the files by double clicking in windows.
	- Third is a string containing a name to be associated with this file. (this will
	  appear in segment files generated and described below)
	  
The program will output in ".ply" files which can be thought of as segments.
	Ply files are described in many places on the internet. One website is:
	http://local.wasp.uwa.edu.au/~pbourke/dataformats/ply/ The header for the 
	segment files are as follows (without the comments on the right side):
	
	ply                                              ; ply magic number
	format binary_little_endian 1.0                  ; Java is always little endian
	comment JptView segment ply file version 1.0     ; Comment identifying JptView segment files
	element element segment_list 1                   ; File specification allows more than 1 segment per file, but jptview only supports single segment files now.
	property list ushort uchar segment_name          ; A string containing the name given to the segment
	property list uint ushort segment_file_index     ; A list of indices into the second element of this file. Should simply be 1:n where n is the number of files containing selected points.
	element file_list 10                             ; A list of files and the points included in the segment.
	property list uchar uchar file_name              ; For each file containing points in the segment, this is the name field of the .lst file
	property list ushort ushort point_list           ; This is a list of points in the file named on the previous line. Indexing starts at 0.	
	end_header										 ; there is a newline character at the end of this line before the data starts. You can find out which type by looking at the previous lines.
	{this is where the binary data begins}

Matlab:
	there is a matlab interface for the functions located in matlab_interface folder. This
	requires that your matlab version includes a jvm at least as good as 1.5. (I think 1.5 
	is required)
	
	writebpt will write the files given matrices of points (with color). jptview.m accepts
	matrices of points (with or without color).