This document is a rough guide to how to set up Charabanc on your own web server. It doesn't go into step-by-step detail of how to do it, but instead just gives you an overview of how the system works and what you need to do to set it up. I am assuming that if you want to set up a program like this, you know enough to understand these instructions and work out the rest yourself. Also that you already understand the basics of how to set up a website on a server. You are recommended to read through the whole document at least once before you start trying to set anything up. If you have any questions about Charabanc, contact me through the address on the website.
The images can have hotspots defined, which are active areas that do something when you click on them. There are two kinds of hotspots: path hotspots and info hotspots.
Path hotspots are used for moving from one viewpoint to a neighbouring one. When you click on one it will move you to the viewpoint that the path you have clicked on leads to. While you are moving to the new viewpoint, a slideshow is displayed which makes it look like you are walking along the path.
You can also move to a new viewpoint using a scrollable, zoomable map. Each viewpoint is shown as a small yellow circle on the map, with the one you are currently at shown in red. When you click on a circle, the tour moves to that viewpoint.
Link hotspots bring up a page that tells you more about an object in the picture.
The pictures for the demo, which is from the Middlewood Trust website, were taken on an ordinary digital camera and then stitched together to make panoramas using an open source program called hugin. The charabanc installation files include a few perl scripts which help automate the process of converting the images for the panoramas and slideshows into the right sizes to work with charabanc.
This section describes the layout of the tar.gz package that you can install from the charabanc website.
|docs/||directory containing the documentation.|
|scripts/||directory containing scripts which are useful in setting up charabanc.|
|scripts/cut-map.pl||script to cut a large image of a map into a series of tiles at different zoom levels.|
|scripts/scale-panoramas.pl||script to scale the raw panorama images into various different resolutions.|
|scripts/scale-walks.pl||script to scale the raw slideshow images into various different resolutions.|
|scripts/charabanc-profile.js||used when creating a custom dojo build.|
|tour/||directory containing the code and other files to run the virtual tour. This is the directory you need to copy to your web server.|
|tour/css/||directory containing stylesheets.|
|tour/css/images/||images used by the stylesheets.|
|tour/css/dojoStyles.css||stylesheet used to customise the dojo toolkit's tab widget.|
|tour/css/infopage.css||stylesheet which controls the appearance of information pages.|
|tour/css/tour.css||the main stylesheet for the web page.|
|tour/images/||directory containing images used by the actual tour program.|
|tour/index.html||a very simple index page which displays a short message and a link to open the real tour page.|
|tour/setup.xml||the xml configuration file. You edit this to tell pano.js what viewpoints, slideshows, and info pages you have defined. The version here is an example from the demo site, with comments included.|
|tour/virtual-tour.html||the main web page of the site. This lays out the html structure of the charabanc page and loads all the required stylesheets and script files to make the program run.|
The way I created the panoramas for the demo site was to go to each viewpoint and take photos on a digital camera in a full circle. Having done this for each viewpoint, you can then stitch the photos together into panoramas using a tool like hugin. This involves defining control points between each pair of images in the panorama which show which points coincide. You need to set hugin to do 'cylindrical panoramas' for it to work with charabanc. There are also various Windows tools which stitch panoramas automatically, but I don't know how good they are. The gimp is handy for editing the stitched panoramas - e.g. to remove any curvature in the panorama (use the 'curve bend' filter), or adjust the brightness and contrast.
At this point you should have a set of raw picture files, one for each panorama. However, charabanc expects to find the panorama images in a single directory, with filenames matching 'viewpointname-resolution.jpg', in a series of different resolutions. The reason for the different resolutions is to allow people viewing the site to adjust the image size according to their bandwidth and screen size.
The script scale-panoramas.pl can be used to scale the raw images to the required resolutions and give them the right names. To use this script, and the other scripts in the scripts directory, you will need to have the Imlib2 library and the related perl module installed. This only runs in unix environments as far as I know (linux, BSD and Mac OSX) so if you're using Windows you may have to install cygwin. It expects to find the raw files in a directory which has one raw image per subdirectory, with the filename being the subdirectory name with the extension .tiff. It is easiest if you make the subdirectory names the same as the short reference names which will be used when you define the viewpoints and relations between them in the Charabanc config file - e.g. 'gate' or 'carpark'. You may need to edit the first part of the script file to give it the right paths etc for the way you've set things up. See the comments in the script for how to do this.
The slideshow images were also taken using a digital camera. Here the first job is to separate them into subdirectories, each named something like 'gate-carpark' or 'carpark-yard'. Each subdirectory should contain the images, in alphanumeric order, which make up one of the slideshows which run when you move from one viewpoint to another. Then you can run the script scale-walks.pl to scale the images to the right resolutions and put them in the defined output directory. Again, you may need to edit the script to set the right parameters.
The map was designed in a vector drawing program called inkscape. The image was then exported as a large .png file, and scaled using the script 'cut-map.pl'. As above, you need to edit the script to make sure it is set up right before you run it. The script will generate a chunk of xml which can be pasted into the configuration file under '<map>'. What the script is doing is taking the raw image, cutting it up into tiles whose size is defined at the start of the script (you are recommended to use roughly half the viewport dimensions but any size will work), and outputting the tiles with suitable filenames to a given directory. Then the image is zoomed in by a factor of two and the process is repeated until 'maxZoom' is reached.
Having created the images, the next step is to tell Charabanc what they are and where to find them, and to generally configure the system to suit your site. You do this by editing a series of configuration files.
This is the html page which describes the basic layout of charabanc on the screen. You may want to edit it slightly to suit your own site, but be careful not to change the basic structure of the document.
This is the stylesheet for virtual-tour.html. You can configure it as you wish to change the visual appearance of the page. To use the built in setup tools, which make it easier for you to configure charabanc, make sure that tr.config's visibility property is set to 'visible'. Remember to set this back again when you have finished.
This controls the appearance of the information pages which come up when you click on an info link. For example the colour of the photo border, the margin width and so on.
There is an xml config file called setup.xml which is loaded by the main charabanc script to tell it what viewpoints you have defined, how they are related, and various other things. The documentation for this file is mostly in comments in the example file itself, so read through it now to get an idea of what's in there.
There is a setup tool built into charabanc which you can use to write the xml data describing the location of hotspots in the panoramas, and the position of the panoramas on the map. See later in section for how to configure your web server to run charabanc. See above in section for how to turn on the setup tool. The best way of getting started is to set up the map first using cut-map.pl, and paste the xml data generated by this script into the config file under '<map>'. Once you have the map working, then you can generate the files for one of the panoramas, and write the xml for this under '<views>'. The subsections '<mappoint>' and '<links>' under '<view>' don't need to be filled in yet. Then look at the panorama in charabanc to make sure it's OK. Then make sure the map is zoomed to the area where the viewpoint is, turn on 'record mouse clicks' under the 'Setup' tab, go back to the map, and click on the point where you want the viewpoint symbol to appear. This will generate a line of xml in the 'Setup' tab which you can paste into the xml file.
Now you can start defining regions as hotspots. For each hotspot, you need to start by turning 'record mouse clicks' off, then go to the panorama and make sure it is panned to the right area which shows all of the region you want to define. It may help if you use the highest possible resolution for the panorama image. Then turn 'record mouse clicks' back on, and click on a series of points round in a polygon which define the region you want to be a hotspot. Once you have done this, go back to the 'Setup' tab and copy the series of '<point ... >' xml entries from there into the right place in setup.xml (see the example entries for reference).
Having defined the hotspots, you also need to put in other entries which give more information about each link. These are under '<walks>' and '<infos>' in setup.xml - see the example config file for more help on this.
Charabanc uses a toolkit called dojo to do a lot of the donkey work - e.g. making the code reasonably cross-browser compatible, displaying the tabbed windows, etc. To run charabanc, you will need to download a 0.4.x version of dojo from their website, and install it in an appropriate place on the server. The location of the dojo release is set in virtual-tour.html - currently it is '../dojo/dojo.js'. I would recommend making a compressed build of dojo.js according to the instructions in the dojo 0.4 book - see the dojo website. There is a profile file suitable for this in the scripts directory of the charabanc release. You can also use the dojo compressor to compress pano.js, but leave doing this until you have everything set up the way you want it and are ready to publish the site.
This section describes how to set up charabanc to run with your web server. There are no special requirements for the server, as the whole system works using plain http requests with no server side scripting. You will probably need to set up a local web server to test and configure charabanc before uploading it. Apache is free and works well, but again, any decent web server would do.
Having decided on the directory structure, you can set the relative paths to the various directories in the first section of the config file. You may also need to edit virtual-tour.html to get the right path to dojo.js.
The easiest way to upload the files to your web server is to create an image on your own hard disk of how you want the site laid out, then maybe test this against a local installation of apache before using a tool like lftp to mirror the local installation to the remote server.
If you need any more help with the installation, refer to the documentation for your web server. If you have any charabanc-specific queries, email me at the address on the website.
Good luck, and I hope you enjoy setting up your tour.
This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.71)
Copyright © 1993, 1994, 1995, 1996,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 0 charabanc.tex
The translation was initiated by Andy on 2008-03-10Andy 2008-03-10