The selected types filter the objects to be copied and the selected attributes what to copy when applying a template

×

Content

1. Importing Project
2. Navigation Elements
3. Creating and modifying tours
4. Time Travel Tours
5. Timepoint Tours
6. Map editor
7. Settings Dialog
8. Exporting the project
9. Import Gigapixel and HDR panoramas
10. Copy Vertices

Importing Project

The first thing to do is import the directory containing all the image files and the description file (tour.json). The latter one must be a direct child of the chosen directory. If the chosen directory does not contain such a file (e.g. the software is run for the first time), it asks you to create a tour (see Creating and modifying tours). Once you save the project, the tour.json file will be created.

Navigation Elements

	Location: Top left of the screen. Effect: Save the tour, undo the current action, redo the last undone action, open the pop-up dialog for settings, help or errors.
	Location: Top left of the screen. Effect: Hide or show the sidebar.
2017 2019	Location: Top left and top right of the screen. Effect: Switch between panoramas that were shot at the same spot earlier or later in time.
	Location: Center bottom of the screen. Effect: Shows the timeline.
	Location: Top right on the timeline. Effect: Collapses the timeline.
	Location: Top left on the map. Effect: Maximizes / minimizes the map and panorama view.
	Location: Map. Effect: Shows the panorama at that location.
	Location: Panorama view. Effect: Shows the next panorama in the pointed direction.
2019 2018	Location: Timeline. Effect: Switches to that moment in time and loads the panorama. If there is no panorama available for that point in time, then the item is grayed out. When clicking it, the map is updated and one has to manually choose the panorama (by clicking one of the red points).
2016 - 2019	Location: Timeline. Aggregated stack of timeline items. Zoom closer or click to see individual items.
	Location: Top left on the map. Effect: Store (or delete) the current map view in the browser storage. The map can be viewed offline afterwards (even after restarting the browser or system).
Satellite	Location: Top right on the map. Effect: Shows the control for the map layers. "GPS" turns GPS tracking on and shows your current position as a white circle on the map (center + uncertainty radius). "Connections" shows lines between points on the map (you can navigate between those panoramas).

Creating and modifying tours

Start a new project

1. On the pop-up: Drop the project folder (that contains all the panoramas) on the drop area or choose it via the file dialog.
2. On the left sidebar: Click "Create tour" under the "Time Travel Tour" section.
3. On the pop-up: Enter a name and click "create" (keep the default value in the other fields).
4. Zoom the map to the location of the tour (use the mouse wheel and grabbing functionality)
5. Open the settings dialog (cogwheel left on the top bar).
6. On the pop-up: Click "Set" next to "Initial center" and "Initial zoom level".
7. Close the pop-up.
8. On the top bar: Click the download icon to save the tour as a file. If you test the software in the browser, you have to download the file and manually place it in the project folder selected in step 2. Do this regularly (by overwriting the file)!

Add a panorama

1. On the left sidebar: Click "Add Panoramas" under the "Time Travel Tour" section.
2. Choose a panorama image file located in the project folder (when testing the software in the browser, you have to use the provided directory tree on the "Browser" tab: use the triangles to expand folders, click a file and then select at the bottom)
3. A red point appears on the map, and the panorama is displayed (it may take a few seconds).

Specify coordinates and north of a panorama

On the left sidebar: Click the "Panorama" tab.

The manual way:

• On the map: Drag the blue marker to the correct position where the panorama was shot.
• On the panorama: Drag the blue hotspot such that it points north.

Automatically derive those values:

1. Open the settings dialog (cogwheel left on the top bar).
2. On the pop-up: Tick "Create point when clicking on the map" (also check "Persist landmarks" if you want to save them to the tour.json)
3. Close the pop-up.
4. On the map: Click on one landmark that you can also see on the panorama (e.g. top of the roof, corner of a house, tree).
5. On the panorama: Drag the green hotspot onto the landmark (only the positioning along the horizontal axis matters).
6. Do the procedure for 4 more landmarks (the more precise you can position them on the map and on the panorama, the better).
7. On the left sidebar: Click "optimize".

Connect individual panoramas

1. On the left sidebar: Click the "Groups" tab.
2. On the left sidebar: Select a timepoint tour from the dropdown.
3. On the left sidebar: Select "Draw Line" as "Editing mode" from the dropdown (select "Load Panorama" to get the default behavior when clicking on points on the map).
4. On the map: Click two red points. A blue line appears.

Modify the tour

• On the top bar: The arrow pointing to the left is an undo button.
• On the left sidebar: Select a timepoint tour to add and remove connections between panoramas.
• On the map: Delete lines by clicking on them (only works for blue and green ones).
• On the left sidebar: Select "Delete point" and click on a point on the map to delete it (and the associated panorama; the actual image file remains unaffected). Immediately select "Load Panorama" afterwards to prevent deleting other points by mistake.

Time Travel Tours

A time travel tour consists of several timepoint tours. The time travel tour makes the navigation in time possible. If two panoramas are taken at the same location but at different times, they end up in different timepoint tours. The time travel tour searches all contained timepoint tours and forms a connection between those two panoramas. The result is that one can switch between them using the top bar navigation.

A time travel tour only requires a name. All the other values are optional. The description will be used as a tooltip. The super tour dropdown exists so that one can build a hierarchy of tours. See the tooltips for more information when hovering over the headings.

The connections for navigating in time cannot be created manually. Instead, the time travel tour automatically takes care of it. Two vertices are navigable in time (there are arrows in the top bar) if they are colocated. To be colocated, they must be within the distance determined by the parameter colocated radius (set when creating the time travel tour). By creating a hierarchy of time travel tours and choosing the suitable options, one can avoid that panoramas are colocated (e.g. useful when panoramas are shot on different floors of a building).

"Add Panoramas" automatically creates a timepoint tour derived from the timestamp of the specified image. Create a timepoint tour manually to exploit all customization options.

There is no possibility to modify groups directly. The workaround is to create a new one and copy the timepoint tours, see Timepoint Tours. Alternatively, one can close the editor and modify the tour.json in a text editor.

Timepoint Tours

A timepoint tour consists of several panoramas. All of them are shot roughly at the same time. The purpose is to have a shared timeslot and name that can be displayed on the timeline.

A timepoint tour requires a name, a timeslot, a super tour and a type. The type determines the type of vertices that can be added to the tour (used to distinguish groups for panoramas and groups for landmarks). Path and description are optional. The description will be used as a tooltip. The path is used to specify a parent folder so that the path saved for the vertices only contains the filename.

There is no possibility to modify groups directly. The workaround is to create a new one and copy the vertices. To do so, do the following:

1. In the settings: Go to the "Advanced" tab and check "Enable batch copying of vertices".
2. On the sidebar: Click "Create Tour" under the Timepoint Tour section.
3. On "Timepoint Tour Editor": Enter the modified values and click "create".
4. On the sidebar: The new tour should now be selected in the dropdown.
5. On the sidebar: Click "Copy Vertices".
6. On "Apply Tour Template": Select the old tour as the destination.
7. On "Apply Tour Template": Click "Edit options for copying vertices".
8. On "Vertex Copy Options": Ensure that all options are checked and all types selected. The functionality is explained in the Copy Vertices section.
9. Close the "Vertex Copy Options" pop-up
10. On "Apply Tour Template": Click "Apply Template".

Map Editor

The map editor can be found between the "Groups" and "Panorama" editors. The map editor allows adding custom overlays to the map, called backgrounds. The purpose is to show plans of buildings, paths, etc. To create such a background, one has to click "Create Background" and choose an image file - just like for adding a panorama. Its name is automatically derived from the name of the file.

Use the upper-left marker (the anchor) to bring the background to the correct position. The other two markers change scale (horizontal and vertical separately) and rotate around the anchor. If one selects "Edit Skew", the markers can be moved without interdependencies. This means the other two markers stay at the same position, and the image will be skewed.

Afterwards, the background should be assigned to a timepoint tour. Therefore, create a new timepoint tour and choose "Advanced Settings" → "Background". One background can be assigned to multiple timepoint tours. Whenever one of these groups is selected in the timeline, the background is displayed. One can hide all backgrounds via the layer control in the upper right corner of the map.

Settings Dialog

The settings are subdivided into three tabs.

• Files: The "Import additional tour files" button allows loading tour.json files from outside the source folder. All the groups, vertices and edges specified in the file are merged into the current tour. Elements that already exist remain untouched (they do not get updated). The import is useful when you want to merge tours from several working directories into one. Keep in mind that you manually have to copy the image files to the correct location. Another use case is reusing landmarks. The "Save backup copy of tour file" lets you save the tour.json to a different directory (paths to panoramas might break). The "Export project" lets you create a version of the project ready for web delivery (see Exporting the project). When saving selected items is selected, the currently selected timepoint tour will be saved. This affects which points are shown on the map at startup.
• View: In the lower section, one can limit to which extent the map and timeline can be panned and zoomed. Moreover, one can specify which part of the map, timeline and panorama is shown on startup. All the settings are stored in the tour file of the workspace. They are read and applied when you load a tour file. The current pan and zoom values of the map / panorama view / timeline determine the values when clicking "Set". "Unset" is clickable when there is a value specified. To overwrite the value, click "Set" again. Enabling "Update all initial view parameters when saving " sets the initial view to the current view when saving the workspace.
• Advanced: Here, one can unlock more powerful tools like copying the vertices of timepoint tours (see Copy Vertices) or adding tiled panoramas (see Import Gigapixel and HDR panoramas).

Exporting the project

Open the settings and click "Export Project". The export dialog is not available when run in the browser.

The primary purpose of the export dialog is to tile the panorama image into smaller images. The advantage is that panoramas are loaded much faster and require less bandwidth to be displayed. To speed up the export process, increase the number of threads. But keep in mind that this requires more main memory. The base image is resized (but aspect ratio kept) in memory before tiling when maximum width or maximum height is set. Both parameters are ignored if the panorama was imported as tiled.

Once the export is started, one can abort it at any time. The processed panoramas are then kept, and one can resume by starting a new export to the same destination. If the progress window is closed while the export is running, opening the export dialog will open the progress dialog.

The created files can be uploaded to a webserver. To display the tour, enter 'https://nihoel.github.io/cirspecte/index.html?tour=' followed by the path to the tour file. Alternatively, one can host the main program oneself. Check out the gh-pages branch of https://github.com/NiHoel/cirspecte including all the submodules. Configure 'assets/js/config.js' (e.g. modify the map's default center and zoom level and the startup tour).

Import Gigapixel and HDR panoramas

Go to advanced settings and check "Import panoramas consisting of multiple images". This hides the "Add Panoramas" button under the Time Travel Tour editor. You must create a timepoint tour first and use the "Add panorama" button there. Then, a dialog opens.

The base image can either be an equirectangular or a cube map where each side is a separate file. The lowest level is always a single image which has at most the dimensions specified as tile length. Depending on the base size, height and width can be smaller than tile length. This happens when the dimensions of the base image divided by tile length do not result in a power-of-to number. The tiles at the right and bottom border are then smaller than the specified length.

The accepted file extension changes when checking the option "High dynamic range image". A script to generate tiles from an OpenEXR image is available here: https://github.com/NiHoel/pano-utils. The script can be used for tiling an equirectangular image or each side of a cube map. You only need to adjust the base image dimensions and the levels. Tile path, file extension, and tile length are correct when using the default values. Due to the extensive processing demand, there is no option to import HDR panoramas as a single file.

Copy Vertices

To unlock this option, go to setting, advanced and check "Enable batch copying of vertices".

This section describes the internal procedure for copying vertices. See the end of the Timepoint Tours section on how to apply it.

We iterate over all the vertices of the source tour. We check whether there is a corresponding vertex in the destination tour. If "update colocated" is checked, all vertices within the connection radius are considered "corresponding". The closest one is chosen. If unchecked, the coordinates must be identical.

A new vertex is created if "create" is checked, there is no corresponding vertex, and the type of the vertex is one of the selected types.

An existing vertex is updated if "update" is checked, there is a corresponding vertex, and the type of the vertex is one of the selected types.

Only the selected values (via the checkboxes "coordinates", "image attributes", vertex.data."northOffset", vertex.data."vOffset", etc.) are used for creation or update.

Afterwards, the edges are handled. The procedure is merely the same. Searching for corresponding vertices is also performed for the start and the end of the edge. Based on start and end, the corresponding edge is determined.

The type of the vertex / edge cannot be copied since it is derived (for instance, a vertex of type "panorama" becomes "placeholder" when the image attributes are not copied).