VisiLibity:  A Floating-Point Visibility Algorithms Library
Copyright (C) 2008  Karl J. Obermeyer (karl.obermeyer@gmail.com)

This file is part of VisiLibity.

VisiLibity is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

VisiLibity is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
License for more details.

You should have received a copy of the GNU Lesser General Public
License along with VisiLibity.  If not, see
<http://www.gnu.org/licenses/>.


======================
 INSTRUCTIONS FOR USE
======================


To use VisiLibity in your C++ program, you simply need to place an
#include "visilibity.hpp" directive at the beginning of your program and
link with visilibity.cpp when compiling.  For details on particular
classes and methods, refer to the source code documentation page to
which there is a link on the project page VisiLibity.org.


The files main.cpp and makefile (listed below) provide an elementary
example of a C++ program which uses VisiLibity.  Once compiled (make
main), this program provides a text interface which will

(1) read an environment and guard locations from files given as
command line arguments,

(2) check the geometric validity of these inputs (edges of the
environment do not cross each other, guards are contained in the
environment, etc.),

(3) display environment and guards' data and statistics, and

(4) compute and display the coordinates of a visibility polygon of a
 guard chosen by the user.

The environment representation and the guard locations can be read
from any file in the (also human readable) format demonstrated in
example1.environment, 
example2.environment, and
example1.guards.


A Matlab interface using MEX-files is provided by the files
visibility_polygon_demo.m,
shortest_path_demo.m, 
visibility_graph_demo.m,
in_environment.cpp, 
visibility_polygon.cpp,
shortest_path.cpp,
and visibility_graph.cpp.
First the files in_environment.cpp, visibility_polygon.cpp,
shortest_path.cpp, and visibility_graph.cpp should be compiled into
MEX-files (see instructions at the heads of the files themselves).
The scripts visibility_polygon_demo.m and shortest_path_demo.m can be
used to display a graphical representation of the supplied environment
files while the user selects points with the mouse so that the
visibility polygon of, resp. shortest path between, points are
displayed.  The script visibility_graph_demo.m can be used to display
a graphical representation of an environment together with the
visibility graph of a set of points specified within the script.


For more details on the examples, see the file descriptions below
and the comments in the files themselves.


=========================================
  INDEX OF FILES with brief descriptions
=========================================


File: ./COPYING
Description:  a copy of the GNU General Public License 


File: ./COPYING.LESSER
Description:  a copy of the GNU Lesser General Public License


File: ./source_code/visilibity.hpp
Description: the VisiLibity header/interface file


File: ./source_code/visilibity.cpp
Description: the VisiLibity implementation file


File: ./source_code/main.cpp 
Description: an example program using VisiLibity.  After compiling
with the provided makefile (just type make in the ./source_code/
directory), run the program with the command line
./main example1.environment example.guards


File: ./source_code/makefile
Description: a makefile for compiling main.cpp using g++


File: ./source_code/example1.environment
       ./source_code/example2.environment
Description: an example of the human readable files that VisiLibity
uses to store polygonal environments with holes.  You can use this as
a template to create your own *.environment files.  To read and write
Environment files, use the Environment::read_from_file() and
Environment::write_to_file() methods


File: ./source_code/example1.guards
Description: an example of the human readable files that VisiLibity
uses to store guard positions.  You can use this as a template to
create your own *.guards files. To read and write Guards files, use the
Guards::read_from_file() and Guards::write_to_file() methods


File: ./source_code/visibility_polygon.cpp
Description: MEX- file source code to interface VisiLibity's
visibility polygon calculation with Matlab


File: ./source_code/in_environment.cpp
Description: MEX-file source code to interface VisiLibity's
Point-in-Environment calculation with Matlab.


File: ./source_code/shortest_path.cpp
Description: MEX-file source code to interface VisiLibity's
shortest path through a polygon with holes calculation with Matlab.


File: ./source_code/visibility_graph.cpp 
Description: MEX-file source code to interface VisiLibity's visibility
graph calculation, for a set of points in a polygonal environment with
holes, with Matlab.


File: ./source_code/visibility_polygon_demo.m
Description: an example Matlab script which uses the the MEX-files
generated from visibility_polygon.cpp an in_environment.cpp (these must be
compiled before running visibility_polygon_demo.m)


File: ./source_code/shortest_path_demo.m
Description: an example Matlab script which uses the MEX-files
generated from shortest_path.cpp and in_environment.cpp (these must be
compiled before running shortest_path_demo.m)


File: ./source_code/visibility_graph_demo.m
Description: an example Matlab script which uses the MEX-file
generated from visibility_graph.cpp (must be compiled before running
visibility_graph_demo.m)


File: ./source_code/read_vertices_from_file.m
Description: a subroutine of visibiity_polygon_demonstration.m and
shortest_path_demo.m used to read a VisiLibity style
Environment file into a Matlab cell array
