Virtual Tour is a CGI script meant to let webmasters take pictures and assemble them into an interactive tour. I invite you to see it in action in the Virtual Tour ‘Impressions of Cambridge’, whether or not you’re a webmaster. It’s worth a visit!
License: This project is free software, available under your choice of the Artistic, GPL, and MIT licenses. If you like this software, you are invited to consider linking to CJSHayward.com.
Adminisgrator’s Guide: Setting Up a Virtual Tour
A reference Virtual Tour is available in my ‘Impressions of Cambridge’. I would encourage you to play around and see how Virtual Tour ticks, how it looks when it is put together.
You can log in to your script’s administrative pages by adding ‘?mode=edit‘ to the end of the URL: if you have a script at ‘http://example.com/cgi-bin/virtual_tour‘, then ‘http://example.com/cgi-bin/virtual_tour?mode=edit‘ will let you log in and set up the pages.
Views and Places
There are (virtual) places one might stand, and virtual views. One place will normally have more than one view. (You can stand in one place, and look around and see different things while you stay in the same place.) The left and right buttons do not mean “Move left” or “Move right”; they mean, “Staying where you are, turn left” and “Staying where you are, turn right.” The forward and backwards buttons mean, “Move forward/backward while facing the same way.” In other words, the backwards button means “Back up,” not “Turn around.” This is not the most consistent way of handling directions, but it seems to provide more intuitive play.
Grids and Paths
If you want, you can manually connect all of the views, but the script provides two shortcuts. The first shortcut is a grid: if you set a Full View Name of “St. John’s College 0 0 W”, that means, “On the St. John’s College grid, at the coordinate (0, 0), facing West.” Virtual Tour will look for a picture in ‘St_Johns_College_0_0_W.jpg‘, stripping out the period and apostrophe and converting the spaces to underscores, then adding ‘.jpg’ to the end (or any other image suffix you’ve asked it to add). Note that this is case sensitive; don’t leave your computer looking for ‘.jpg‘ files if you have your pictures stored in ‘.JPG‘, or give a room of “St. John’s College 0 0 W” while your image is stored in ‘st_johns_college_0_0_w‘. The title given to the user will be something like “‘Impressions of Cambridge’: St. John’s College: 0 East, Zero North (Facing West).” Note: by paying attention to the view titles when visiting ‘Impressions of Cambridge’, you can tell what the coordinates are. Virtual Tour will automatically link a view with other views at the same place (if the user turns around), and will also link one place to adjacent places on the grid. It should not be necessary to specify too many links manually; normally it should be enough to manually connect e.g. grids with paths, and then let Virtual Tour handle all of the links within a grid or a path.
Note: ‘link’, as I’m using the term, does not mean an HTML link <a href="CJSHayward.com">like this</a>. I am using to denote the setup behind what the user will intuitively understand as, “At the end of this path, I can move around in this grid.” In other words, the nuts and bolts of navigation. Usually this refers to links you specify manually, not the ones that Virtual Tour will automatically create between parts of a path or a grid that are next to each other.
A path is similar to a grid, except that it is one-dimensional. Rather than having two coordinates, it only has one, indicating how far you are along the path, and instead of letting you face ‘N’, ‘S’, ‘E’, and ‘W’, you can face either ‘F’ (for ‘Forward’), or ‘B’ (for ‘Backward’). A sample Full View Name might be “King’s Parade 3 B”, which would load the image Kings_Parade_3_B.jpg.
Normally, I created either all or none of the views for a point on a grid or path. In other words, “St. John’s College 0 0 N”, “St. John’s College 0 0 E”, “St. John’s College 0 0 S”, and “St. John’s College 0 0 W” should all exist if at least one exists, and likewise “King’s Parade 1 F” and “King’s Parade 0 B”.
Coordinates for grid points, and positions along a path, must be integers.
Manually Linking a Grid and a Path
What I did to connect “St. John’s College 0 0” with “King’s Parade 3”, so that “King’s Parade 3” is intuitively south of “St. John’s College 0 0”, is to create four links from four different views:
- Go to the “Room View” screen for “King’s College 0 0 S” and set the “Forward” link to “King’s Parade 3 B”.
- Go to “King’s Parade 3 F” and set the “Forward” link to “St. John’s College 0 0 N”
- Go to “St. John’s College 0 0 N” and set the “Back” link to “King’s Parade 3 F”.
- Go to “King’s Parade 3 B” and set the “Back” link to “St. John’s College 0 0 S”.
The last two steps help make Virtual Tour behave the way a player would expect when he tries to back up. This sets the path’s forward direction to the grid’s North. Various directions need to be adjusted if the path’s forward direction is to the grid’s South (basically, the ‘B’ and ‘F’ portions of the path are swapped), or the path leaves from the grid’s North, East, or West. Basically, if you’re not sure, try to work it out (or take a guess), test it, and expect to get it wrong the first couple of tries, but you’ll be getting the hang of it before too long.
This is most easily done after the views are all created, not as you are adding views.
I know that this is cumbersome and slightly confusing; I’m sorry, but I haven’t taken the time yet to make a simpler and more intuitive way of doing this.
Directories, Files, and Images
The virtual tour will look for images in ‘/var/www/html/virtual_tour/‘ (if you installed from an RPM), or whatever place you told it to store its HTML files in (if you installed manually). If you’re not sure where it is, go to the home page (‘http://example.com/cgi-bin/virtual_tour‘ for an RPM install, or what you specified for a manual install), right-click on one of the images, and select “View Image.” That should let you see the image’s URL in your browser’s URL bar, which will be in the same directory as where you need to put your pictures.
The default image size (640×480 at installation) can configured from the ‘Miscellaneous’ menu, and you can override this for individual images if you want.
That’s what you need to know to set up a Virtual Tour, even if it’s tersely stated. Play around with it, and if you’re a programmer, think about what would be needed to produce something that behaves like ‘Impressions of Cambridge’. And, if you think of something important that should be here but isn’t, please contact me so I know what else to add.