
READ ME - Version 1.0                                                                              Revised March 31, 1999 

Welcome to mapsaVR, the wired sprite QTVR editing tool that embeds directional indicators and
clickable node markers and maps into single or multinode panoramic movies. 

To use the on-line mapsaVR Manual  visit:
http://www.smgVR.com/msvrManual/
______________________________________________________________________________________________________

System Requirements 

       mapsaVR requires a Macintosh PowerPC or compatible system with a base requirement of 5
       MB of RAM and 5 MB of hard disk space for installation. The maps and VR movies used will
       require additional hard disk space and memory.  A recommended system configuration for
       adding maps to VR movies is 16 MB RAM and 50 MB of hard disk space. mapsaVR requires
       QuickTime 3.0 to be installed, and requires System 8 or higher.
______________________________________________________________________________________________________


Program Features 

       mapsaVR creates a sprite track of a specified size and adds it to single or multinode panorama
       movies. 
       This sprite track can contain: 
           1 Background Image.  (Your movie dimensions will adopt the dimensions of the image) 
           1 Background Color. (Not visible if a background image is used) 
           1 Map Transparency Color to be used for all maps. 
           1 Directional Indicator for each node in a Panorama Movie. 
           1 map image per node (The same map can be used on several nodes). 
           As many clickable node jump markers as required to get from one node to all other nodes. 

       The program has two modes, Edit and Preview, which can be changed by selecting the desired
       mode from the popup menu in the editing panel.. 

       Since each node can have a different orientation, the Directional Indicator marker can be
       aligned separately for each node. 

       mapsaVR has an automated marker placement system that logically determines which node
       markers should be placed on each map and where, based on marker positions on other nodes. 
       Additionally, marker re-positioning on any node will be replicated on every other node that
       shares the same map. 

       Node markers to nodes that don't share the same map as the current node, can be manually
       added.  Also, nodes can be manually removed, if the user does not want them to be visible on
       a particular node. 

       mapsaVR preserves embedded media such as custom graphics or wired sprites. This is
       designed to provide further compatibility with custom authored panoramas. Note that object
       movies and multinode movies that contain object movies are not officially supported.  
       However, in some cases it is possible to use mapsaVR successfully with such movies.  Please
       see the Tips and Tricks section for more details.       
______________________________________________________________________________________________________


Using mapsaVR 

       To use mapsaVR a finished QTVR single or multinode panorama movie is needed, plus one or
       more images to use as overhead maps of the area(s) where the nodes are located. 

       Maps can be created using a variety of graphics or rendering packages that save out any
       graphic format supported by QuickTime (jpg, GIF, Pict, BMP, etc.). 

       If you wish to use custom node markers of your own design, you will need a resource editing
       tools such as ResEdit.  Please see the tutorial on Marker Sets for more details. 

       mapsaVR works on most multinodes panorama movies, but there are certain tile requirements
       that need to be observed for mapsaVR to work properly on some movies. 

       Object movies can be used with mapsaVR in some cases, and using mapsaVR with them is
       considered an advanced activity.  Object movies are covered in the Tips and Tricks section.
______________________________________________________________________________________________________


Quick Start 

      Launch mapsaVR. 
      Select a QTVR Panorama movie to open. 
      Set the dimensions that you want your finished movie to have from the options window that opens. 
      An editing window with the editing canvas will open displaying your pano. 
      Drag the panorama movie to where you want it. 

    Add Maps and Set Markers 

       Import required map files 
              Click the "Add..." button. 
              Choose an image file from the dialog. 
              Repeat until all required maps have been imported.
       Set the Maps for each Node 

              Select one or more nodes in the movie. 
              Select the appropriate map in the "Maps" list box. 
              Position the maps by dragging them to the desired location. 
              Repeat until all nodes have the desired maps in the correct locations.

       Set the correct direction for Indicator Markers 

              Select a node from the "Nodes" list box. 
              Use the "Panorama Angle" slider control to pan the movie to view an identifiable
              object. 
              Use the "Indicator Angle" slider control to point the indicator at the object in the
              panorama. 
              Repeat for each node until the node's directional indicator has been set correctly.

    Preview the movie 

            Switch to the Preview Mode and interact with the panorama to see if everything works as it should. 
            If necessary go back to Edit mode and make adjustments. 

    Save the output movie 

       Select "Save A Copy As...." menu item from the "File" menu. 
       Choose the destination of the file from the dialog.
______________________________________________________________________________________________________



The Menu Bar 

There are four active menu bar items in mapsaVR: Apple, File, Edit and Display. 

From the Apple menu the "About mapsaVR..." menu item can be accessed. 

       The "About mapsaVR ..." menu item will open a window that displays the application
       version number, user registration information, and a scrolling text field for quick access to the
       ReadMe documentation.  


The File menu has four active items: "Open...", "Close",  "Save A Copy As...",  and "Quit" 

       The "Open..." menu item will open a dialog to select a movie file.  Importing a file that has
       no panorama track or QTVR track, will cancel the process and the user will be notified that the
       file was not a panorama.  A warning dialog will open if the user opens an object movie or a
       multinode movie that contains an object.  The warning will tell the user to refer to the Tips and
       Tricks section of this manual.  The user can continue to work with this movie, or they can
       close the editing window and open a different movie. 

       When a valid QTVR panorama movie (with no previously embedded maps) has been selected,
       the "Movie Options"  dialog window will open to allow output settings to be set.   If there
       are maps already present in the movie, the Movie Options dialog will be bypassed and the
       editing window will open. 

       The "Close" menu item will close the active editing window.  If the movie has been edited,
       and the changes have not been saved, a dialog will prompt the user to save before closing the
       movie, close the movie without saving, or cancel closing the window. 

       The "Save A Copy As..." menu item will open a dialog asking the user to save the current
       movie.  It is recommended that users do not try to overwrite already existing files. 

       The "Quit" menu item will close the editing window and Quit the application.  As with the
       "Close" menu item, the user will be prompted to save any changes.  


The Edit menu has one active item,  "Movie Options..." 

       The "Movie Options..." menu item will open a window that allows a number of options to
       be set that affect the entire movie.   This window is initially displayed only when opening a
       QTVR Panorama movie that was not previously saved out by mapsaVR.  Once a movie is
       open, this window can be opened again when the Editor Window is in "Edit Mode" .  When in
       "Preview Mode" the menu will be grayed out.  


The Display menu has nine active items: 

       The first two, "Degrees" and "Cross Hairs", toggle on and off the info displays for the
       panorama.  The next six menu items set the color of the information displays to specific color
       selections.  The last item, "Choose..." allows a custom display color to be selected.
______________________________________________________________________________________________________



Movie Options Window 

Map Options: 

       Markers:

              Marker Set Field 

                    This field displays the name of the marker set that will be
                    used by mapsaVR.  If no marker set has been selected then a
                    default set will be used and the field will display "Default".

              Import... Button 

                    Clicking this button will open a get file dialog that allows
                    you to import mapsaVR marker sets.  Clicking the "Show
                    Preview" check box in this window will display a visual
                    representation of the selected marker set.  Changes will not
                    be seen until the "Movie Options..." window is closed.

              Disable Node Jumping Check Box 

                    If this box is checked, clickable node markers will no longer
                    become active in preview mode, or in the the saved out
                    movie.  Node markers will still be visible and show node
                    locations, but they just won't jump to the corresponding
                    node when the user clicks on them.

       Background: 

              Background Color Button 

                    Clicking this button will open the Apple Color Picker
                    window to select a new background color.  The background
                    color can be used to create a border around the panorama
                    movie and the maps or to simply separate the map from the
                    panorama.  White is the default background color.

              Use Image Field 

                    If a background image has been selected or embedded, the
                    file name will be displayed here.  QTVR movies and maps
                    are always placed on top of the background image and only
                    one background image can be used for the movie.  When a
                    background image is being used, the editing canvas will
                    adopt the image dimensions and the movie dimensions panel
                    will be grayed out.

              Import... Button 

                    Clicking this button will open a get file dialog that allows
                    you to import an image file in any format supported by
                    QuickTime 3.0.  The original file format of the image will be
                    retained when added to the movie.  Clicking the "Preview"
                    check box in this window can display a visual representation
                    of the selected file.  Changes will not be seen until the
                    "Movie Options..." window is closed. 
                    Before importing a background image, please read the
                    Windows Compatibility section, to learn how to ensure that
                    MS Windows users will have no problems viewing movies
                    that contain a background image.

              Remove Button 

                    Clicking this button will remove and delete an embedded
                    background image.  The size of the editing canvas will
                    remain the same size as the last imported image, but the
                    dimension panel will now be enabled, allowing the user to
                    modify the dimensions. 
                    If there is no background image this button will be grayed
                    out.  Changes will not be seen until the "Movie Options..."
                    window is closed.

       Transparency: 

              Transparency Check Box 

                    If this check box is "on" then a transparency color will be
                    applied to any and all embedded maps that are imported into
                    the movie.  This works best with lossless image codecs like
                    ".gif" since compression artifacts can interfere with the
                    transparent effect.

              Transparent Color Button 

                    If the Transparency check box is checked, clicking this
                    button will open the Apple Color Picker window to select a
                    new transparency color.  The background color can be used
                    to create a border around the panorama movie and the maps
                    or to separate the map from the panorama.  If the
                    Transparency check box is not checked, this button will be
                    grayed out.

Movie Dimensions (pixels): 

       Select Dimension Menu 

              This popup menu has four items to help with the selection of common editing
              canvas dimensions.  Selecting a menu item will immediately enter the selected
              dimensions into the horizontal and vertical dimension fields.  The menu items
              will adjust themselves based on the size of the QTVR panorama movie.

       Horizontal field 

              This edit field displays and sets the width of the editing canvas.  This field
              will accept numerical values only.

       Vertical field 

              This edit field displays and sets the height of the editing canvas.  This field
              will accept numerical values only.

       Please read the Windows Compatibility section, to learn how to ensure that MS Windows
       users will have no problems viewing movies created by mapsaVR. 

       Click OK to keep changes. 
       Click Cancel to abort.
______________________________________________________________________________________________________



Editor Window 

       Only one mapsaVR editing window can be opened at a time,.  Clicking the windows "zoom
       box" will reset the window to its original size if it has been changed. The Editing Window has
       two components, the Editing Canvas, and the Editing Panel. 

       This window can be resized smaller or larger than the editing canvas.  If some of the canvas is
       obscured, then the scroll bars can be used to bring hidden areas of the canvas into view.



Editing Canvas 

       The dimensions of the panorama movie must be smaller than the dimensions of the editing
       canvas, but map dimensions can be larger than the canvas. 

       The saved out movie will have the same dimensions as the entire editing canvas (even if the
       window has been resized).  Resizing the window with the Grow Box does not resize the
       canvas, it just adjusts how much of the canvas is in view.  If the whole canvas is not visible in
       the window, the scroll bars will be enabled and can be used to adjust which part of the canvas
       is in view.  The canvas can be resized in the Movie Options window.



Editing Panel 

       On the left side of the editor window there is an editing panel.  The editing panel has a
       "Nodes" list, a "Maps" list and "Markers" list,  as well as buttons to add or remove maps and
       markers, and sliders that control the alignment of the directional indicator in each node.


Nodes List 

       There will be only one item in this list if a single node pano is open.  When a multinode pano
       is open, the name of each node contained in the movie will be displayed in the list box. 
       Clicking on a node list item will select it as the current editing node, and update the editing
       canvas as well as the alignment setting controls for that node. 

       Multiple nodes can be selected by holding down the shift key for continuous selection or the
       command key for discontinuous line selection.  Operations that can be performed across
       multiple nodes are:  Map Selection and Map Positioning.  Note that map positioning is
       performed on multiple nodes, that only maps that are the same will be affected.  This way, a
       smaller map than the one currently being dragged, won't "disappear" off the canvas. 

       Performing an operation that can not be performed on multiple nodes will deselect all nodes
       except the current node.  Multiple node selection has no effect on marker positioning.  The
       only reason why multiple nodes are not deselected in this case, is just in case the user
       accidentally clicked on a marker instead of a map, when trying to position multiple maps.

Maps List 

       The "Maps" list box is used to associate imported maps to specific nodes in the movie being
       edited. 

        Clicking on a "Maps" list item will select it as the map for all currently selected nodes. 

       "Add..." Button 
       Clicking on this button will open a dialog box so that an appropriate graphic file can be
       selected for use as a map.  Clicking on "Open" will import the selected graphic into the movie
       and add it's name to the 'Maps' list box. 

       "Remove" Button 
       Clicking this button will remove the currently selected map from the 'Maps' list and delete its
       image from the movie.  This button will be grayed out if the currently selected node has no
       map selected.  The user will be prompted to confirm removal of a map that is being used on
       more than one node.


Markers List 

       This list box will be grayed out until at least one marker is visible in the current node being
       edited. Markers will automatically be added to all nodes that use the same map.  Clicking on a
       "Markers" list item will select the corresponding marker as the current marker.  The marker
       that corresponds to the current node is a directional indicator.  All other markers are considered
       to be node jumpers.  No Markers will be visible until a map has been selected for the current
       node. 

       "Add..." Button 
       Clicking on this button will open a dialog box with a list of all markers for nodes that do not
       use the current map (or markers that have been previously removed). Multiple items can be
       selected from the list.  Clicking the "OK" button will close the dialog and add the selected node
       markers to the current map.  These markers will not be positioned automatically by mapsaVR
       and must be positioned by the user. 

       "Remove" Button 
       Clicking this button will remove the currently selected marker from the 'Markers' list and the
       current map.  This button will be grayed out if the currently selected node has no markers
       specified.

Navigation Alignment Panel 

       Each node's direction indicator must be aligned to the panoramic image.  This is required
       because it is possible that at the time the panorama nodes were photographed, the first picture
       of every node may not have been pointing in the same direction, and therefore each node may
       not be oriented the same way.  Aligning in mapsaVR is a much simpler than requiring every
       node's sourcepict to be altered with a graphics editor and requiring that the multinode be
       re-authored. 

       Use the Panorama Angle slider to rotate the view of the current node so that an identifiable
       object (such as the corner of a room or building,  a mountain,  stream or statue) is in view in
       both the panorama and the map image. 

       Next, use the Indicator Angle slider to rotate the directional indicator so that it points at the
       object on the map.  The directional indicator should now be aligned to the panorama.  If the
       indicator does not seem to maintain synchronization for all 360 of the panorama, then it may
       be possible that the node marker is not correctly positioned, or that the map itself may not be
       completely accurate.   If the map is not proportionally correct, perfect angle alignment for all
       360 will not be possible. 

       If all nodes were photographed with the first picture facing North, and the maps being used
       were oriented with North at the top of the image, then no alignment adjustments will be
       necessary.  If, however, all maps were oriented with East at the top, then all indicator
       alignment adjustments could be set arbitrarily to a 90 offset without adjusting the panorama
       angle. 
        

Edit and Preview Modes 
  

       To switch between the Edit and Preview mode, just click on the popup menu and chose the desired
       mode.  All editing of maps and markers in the movie takes place in the Edit mode.  When the user
       switches to Preview mode, the panorama movie becomes interactive, and the user can check that the
       maps and markers look and work like they should.  When the user saves out the final movie, it will
       look exactly the same as it does in Preview mode.
______________________________________________________________________________________________________



Positioning Maps 

       To position a map, click on the map's image and use the mouse to drag it to the desired
       location.  Maps can not be completely dragged off the editing canvas.   At least two pixels
       must always be visible so that the map will not "disappear" off the editing canvas. 

       Positioning a map when multiple nodes are selected will align the top-left corner of all selected
       maps to the top-left corner of the map currently being dragged.  Nodes that do not share the
       same map as the current node will not be affected, so that their maps will not "disappear" off
       the editing canvas.



Positioning Markers 

       To re-position a marker, click (and hold the mouse button down) on the marker and use the
       mouse to drag it to the desired location.  Cross hairs will appear to help with the alignment to
       other node markers.  If the marker is currently an indicator, an extra line will be displayed
       showing the current direction.  The marker's new position on the map will be updated on any
       other node that uses the same map, even if the maps are located in different places on the
       editing canvas. 

       Markers can not be dragged off the map. 

       Note that markers will become obscured by the panorama if they are dragged underneath it. 
       All markers are initially positioned at the top-left corner of the currently selected map.
______________________________________________________________________________________________________



Known Issues 

Interface Quirks 

       Sprite information displays do not stay "on" when the mouse button is released.  This issue
       will not be addressed in the release version. 

       The indicator angle line does not stay "on" while adjustments are made with the slider control. 
       The indicator angle line updates once only when the current angle changes during the control
       dragging process (i.e.: It blinks).   This issue will not be addressed in the release version. 

       List boxes that have been disabled in Preview Mode will have clickable list items if a Finder
       window or a window from another application becomes active.  Although the list items can
       then be selected, no actions will occur, and proper settings will be restored once Edit Mode is
       selected.  This issue will not be addressed in the release version. 


        

Tile Requirements 

       All nodes in a multinode movie MUST have equal durations. 
       Movies containing nodes with different durations will NOT play properly. 

       When authoring a multinode movie you  must use the same number of tiles for every node. If
       you are using sourcepicts of different dimensions for any reason, you can use the QTVR Tile
       Calculator (free HyperCard stack included with mapsaVR v1.0) to help find suitable valid tile
       values for a set of sourcepict dimensions.  This stack also stores calculated values for later
       reference and allows set naming and searching. 

       Different horizontal and vertical tile dimensions can be used as long as each node still uses the
       same number of tiles.  The following is a compatible movie file because each node uses six
       tiles and will be of equal duration: 

              Node 1:      1 horizontal tiles            6 vertical tiles 
              Node 2:      3 horizontal tiles            2 vertical tiles 
              Node 3:      2 horizontal tiles            3 vertical tiles

       If you have problems with a particular movie file, then please send it (or one like it) to us for
       testing at "dev@smgVR.com".  You should send the original movie before it is edited with
       mapsaVR.  


Windows Compatibility 

       There is a bug in the Windows version of QuickTime 3.0 that affects the way a sprite track
       (the editing canvas in mapsaVR is a sprite track) in a movie is displayed.  If the color depth of
       the monitor is greater than 16 bit, strange skewing of the sprite images will occur if the
       horizontal dimension of the sprite track (editing canvas) is not evenly divisible by 16.  This
       problem occurs in all wired sprite movies. 

       Additionally, if the horizontal dimension of the sprite track is greater than 512, the horizontal
       dimension of the sprite track must be also be evenly divisible by 32. 

       mapsaVR has two warning icons which indicate that the movie may not play correctly on
       Windows machines.  It is up to the user to decide if the movie should be authored so that the
       movie plays back correctly.  A warning icon will become enabled anytime the dimension of the
       sprite is changed in such a way that it will cause incompatibility problems.  Clicking on the
       enabled warning icon will display a warning message, and instruct the user on what can be
       done. 

       The warning icons are located in the Background Image panel, and in the Dimensions panel. 
       Clicking on the warning icon corresponding to the background image will warn the user that
       the background image is not the right size, and that the image will have to be resized before it
       is imported into mapsaVR.  The suggested compatible size will be given. 

       Clicking on the warning icon beside the horizontal dimension field will warn the user that the
       dimension of the editing canvas is not compatible, and will suggest the correct size.  It will
       also give the user an option of automatically setting the horizontal dimension to the correct
       value. 

       Other than this issue, output movies should behave the same as on the Macintosh OS. 


        

Streaming Multinodes 

       If you plan to deliver large multinode movies over the internet, movies should be optimized
       with preview graphics and deliVRator, so that users can navigate the environment as soon as
       possible.  This holds true whether mapsaVR has been used or not, and there are excellent tools
       for this at http://vrtools.com/. 

       Clickable wired sprite node jump markers can NOT function properly until the corresponding
       hi-res image has been entirely downloaded.  Clicking on a node jump marker before the hi-res
       image for that node has downloaded will result in odd panorama behavior. 

       This is a bug in QuickTime 3.0, and this problem is prevalent in any application that uses
       wired sprites to navigate streaming multinode movies. 

       For this reason you may wish to use deliVRator to place the mapsaVR sprite track at the end of
       the movie file so that it can not be interacted with until all the hi-res images have been
       completely downloaded. 

       If you want the map and markers to be visible as soon as possible, you may want to disable
       node jumping so that that the end user will encounter no weird panorama behavior.
______________________________________________________________________________________________________


Reporting problems 

       mapsaVR is a new application that utilizes many components introduced in QuickTime 3.0. 
       As a result of the wide variety of different types of image compressors, VR creation programs
       and system configurations, it is expected that some conflicts and bugs may be found. 

       Please consult this manual for information on current mapsaVR issues.   If you believe that
       you have found a different problem, please ensure that you can reproduce it, and check if it
       still occurs when starting up with only the required standard Apple extensions.  Please also
       make sure that all source movies and maps play correctly in MoviePlayer before they are
       brought into mapsaVR. 

       If problems persist, please e-mail a detailed description of the problem, how it is triggered,
       and if possible, an example source movie, as well as what program the movie was authored
       with, to <dev@smgVR.com> 
______________________________________________________________________________________________________
        
mapsaVR - Copyright 1998, 1999 SQUAMISH Media Group, Inc. All rights reserved. 
mapsaVR and associated logos are registered trademarks of SQUAMISH Media Group, Inc. 
  
  
  
