Build a Clickable Location Tour for a Factual-Series Pitch
Build a Clickable Location Tour for a Factual-Series Pitch
A single panorama answers one question: what does this room look like from here. A pitch usually needs a different answer — how these places sit next to each other. Whether the storeroom opens off the workshop, whether the yard is visible from the upstairs window, whether the two buildings share a wall. No single photograph, however wide, will say that on its own.
Two photographs and a doorway can carry it, if you give the reader a way to move between them and enough context to know where they have landed. That is what a clickable location tour does. The build is small. The judgment is what separates a tour that informs a producer from one that quietly overstates what you have.
The short version: give each captured view one stable identity and its real angular coverage. Put the transition at a landmark the reader can actually see. Decide which way the camera faces on arrival, and make the way back obvious. Say plainly where the coverage stops. Write a version that works without clicking at all. Then walk the whole thing yourself, in both directions, on the route your recipient will really use. Everything below is that list, with reasons.
Start with the connection, not the pictures
Before you open a configuration file, write down what you have. For each space: is the capture a full turn or a partial arc, and roughly how many degrees does the arc cover? For each pair of spaces: is the connection documented, or is it your assumption?
Documented means something in the material supports it — your recce notes record that the storeroom door opens off the workshop's north wall, and both captures show the same door frame. Assumed means you believe the two rooms adjoin. Those two cases get different treatment in the tour, and mixing them is where a pitch starts making claims its images cannot support.
The same inventory covers authority. In this scenario a producer has authorized the use of the panoramic images. That authorizes the images. It does not authorize filming on the site, it does not authorize publishing pictures of anything a location owner would object to, and it does not turn the tour into evidence of access. If a storeroom shelf holds someone's private paperwork, decide now whether it appears, not after the link has gone out.
One view, one identity, honest edges
Give each capture a scene identifier that describes the space rather than the shoot: workshop and storeroom, not IMG_4471 or scene-1. You will type that identifier in the configuration, in every later correction, and in your own notes to the producer. A name that means something survives that process.
Then record what the image actually covers. Pannellum's reference separates two things that are easy to confuse: the angular coverage of the photograph — haov, vaov, vOffset — and hfov, the width of the window the reader looks through. They are not the same quantity and they do not substitute for one another. Widening the viewing field does not add image. Stretching a partial capture until the edges look plausible does not make the room complete; it just moves the lie from the background to the horizon.
A workshop captured the whole way round carries no coverage limits, because there are none to record. A storeroom captured across about 200 degrees of the room carries exactly that. Readers do not need the number in the interface, but your configuration needs it to be true.
Two kinds of hotspot, two jobs
There are markers that move you and markers that tell you something. Pannellum treats them as different hotspot types, and the distinction is worth keeping strict in your head as well as your file.
A scene link is a navigational claim: pass through here and you are in the other space. It should sit on the doorway, and it should exist only where the connection is documented. If two captures show rooms you merely believe are adjacent, publish them as two scenes and say in the caption that the connection is proposed. A link drawn through a wall you have not verified is the most expensive kind of error in a pitch, because it is the kind a producer will repeat to someone else.
An information marker is a description: this is the bench, the worktop runs along this wall, this is where the filmed sequence would begin. Keep information markers away from measurements you did not take. "The worktop runs the length of this wall" is something the photograph supports. "2.4 metres of continuous worktop" is a survey claim wearing a caption's clothes, and no amount of careful clicking will make it true.
The two should also look different and read differently before anyone clicks. "Go to the storeroom" versus "Bench A". A reader who has to hover to find out whether a dot will move them somewhere has been given a puzzle instead of a route.
Where the reader lands
Here is the part most first attempts get wrong, and it is easiest to show with a worked example.
Suppose — and this is the stipulated situation for the example, not a description of anything photographed for this article — you have two authorized captures. The workshop is a full turn. The storeroom is a partial capture covering about 200 degrees, with roughly 160 degrees of the room never photographed. Under the convention the snippet below assumes, that capture is centred on yaw 0, so the arc runs from about −100° to +100°. The doorway between them appears in the workshop's capture, and again in the storeroom's, close to one end of that 200-degree arc — at yaw 88, twelve degrees in from the +100° edge. Your recce notes record the connection, and both images show the same door.
The tour names workshop as the first scene. From the workshop, a scene hotspot on the doorway sends the reader to storeroom. From the storeroom, a return hotspot sits on the door and sends them back.
Now the arrival. The storeroom scene sets no starting view, so it opens at yaw 0 — the centre of the partial image, where the capture happens to begin, facing the shelving. The reader lands looking at shelves. The doorway they just walked through sits at yaw 88, near the end of the arc where the image stops: nearly 90 degrees round to the side, outside the 90-degree window they arrive in. They can turn and find it. They will probably turn and find it. But for a second they are somewhere new with no visible relationship to where they were, and the return route is the thing at risk of never being noticed.
The correction is a target view on the transition: targetYaw and targetPitch set so the arrival faces the door. The neatest way to choose those numbers is to borrow them. The storeroom's return hotspot sits on the doorway, so its own yaw and pitch — 88 and −2 here — are, by definition, the direction of the door. Aim the arrival at those same coordinates and the reader lands looking at the threshold and at the way back.
A sketch of the shape, using the options the reference documents for scene coverage, destinations and target views:
{
"default": {
"firstScene": "workshop"
},
"scenes": {
"workshop": {
"title": "Workshop",
"type": "equirectangular",
"panorama": "workshop.jpg",
"hotSpots": [
{
"type": "scene",
"text": "Go to the storeroom",
"yaw": 118,
"pitch": -4,
"sceneId": "storeroom",
"targetYaw": 88,
"targetPitch": -2
},
{
"type": "info",
"text": "Bench A: the worktop runs along this wall.",
"yaw": 205,
"pitch": -12
}
]
},
"storeroom": {
"title": "Storeroom (partial capture)",
"type": "equirectangular",
"panorama": "storeroom.jpg",
"haov": 200,
"hfov": 90,
"hotSpots": [
{
"type": "scene",
"text": "Back through the doorway to the workshop",
"yaw": 88,
"pitch": -2,
"sceneId": "workshop",
"targetYaw": 118,
"targetPitch": -4
}
]
}
}
}
A few notes on that snippet. The 200 is the stipulated coverage of the example capture, and yaw 0 is the centre of that partial image — the view the storeroom scene opens on — which is why the doorway at yaw 88 sits near the arc's +100° end and well outside the 90-degree field the reader would arrive with. Every other number would come from your own images, read off the doorway's position in each, and there is no formula for any of them. And the arrangement is a sketch of the shape rather than a result: nothing here was built, loaded, or opened in a browser. Reading Pannellum's tour example and reference is where the option names and the separation of coverage from viewing field come from — the tour example and the reference — and reading documentation is not the same as using the library. Check the current reference for exact option names before you paste anything.
Notice that the return arrival also faces the doorway, because it borrows the workshop hotspot's coordinates the same way. That consistency is a choice with a reason: the reader learns that arriving means facing a threshold, and every transition in the tour behaves the same. If the workshop had three or four branches off it, the choice would change — you would want the return to face into the room instead, so the reader can pick the next branch rather than look at the door again. Same tool, different decision, different condition.
What the tour does not contain
The 160 uncaptured degrees of the storeroom cannot be marked. A hotspot has to sit on image, and there is no image there; whether or not a viewer lets you pan past the edge of a partial capture, there is nothing underneath the marker to point at. The gap has to be explained in words, in the tour's opening text and in the companion described below.
Say it plainly: this view covers about 200 degrees of the storeroom; the doorway appears near one end of that arc, at about yaw 88; the remaining part of the room was not photographed. An unphotographed arc does not read to a stranger as unknown. It reads as nothing, and readers fill nothing with whatever they already assume.
The same discipline applies to the walk itself. The tour jumps between viewpoints; it does not walk the threshold. A reader who clicks from the workshop into the storeroom has crossed a doorway that the tour never shows them crossing. Say so. One line is enough, and it protects you from the much larger claim a silent jump implies — that the two spaces are continuous, measured, and understood.
The version that works without a click
Every tour needs a companion that does not require anyone to drag a panorama. Not as a courtesy, and not as an accessibility checkbox bolted on at the end, but because the person reading your pitch may be in a meeting on a laptop trackpad, reading a PDF, or scrolling a phone on a train.
Two stills, one per space, each with a caption that carries the same three facts the panorama carries. What this view covers, and what it does not: "Storeroom, with the doorway near one end of the arc. Approximately 200 degrees of the room; the rest of it was not photographed." Where the connection is: "The doorway leads back into the workshop." And the honest limit: "The tour moves directly between the two views; the intervening step is not shown."
The stills should be the same images the tour uses, not prettier substitutes. A caption that shows a wide, generous frame of a room and then needs three sentences of explanation about what it leaves out is worse than a narrower frame that tells the truth.
Put a route sentence above the images — one paragraph, in the order a person would move: from the workshop, through the doorway on the north wall, into the storeroom. If someone reads only that paragraph, they should still understand the connection you are pitching.
Follow every route before you send it
A configuration file that loads is not a tour. The checks below are yours to run, because this example was never built; when you do run them, run them in the browsers your recipients actually use, on the route they will actually receive — a hosted link if you are sending a hosted link, a local folder if you are sending a local folder.
Follow each transition in both directions. Workshop to storeroom, then storeroom back to workshop, then forward again. Does each arrival face something that explains where you are?
Look at the edges of the partial capture and imagine arriving at them by accident. Does a reader hit the end of the image and conclude the tour has broken?
Read every label at the default field of view, not zoomed in. Names that only resolve when you lean into the panorama are names most readers will never read.
Check that navigation does not depend on noticing a marker. A scene list outside the panorama image — two titles and a click — costs almost nothing and guarantees that a reader who arrives facing the wrong way can still find the storeroom, and still find the way back. It also gives you a route that works from a keyboard, which is worth testing with the tab key rather than assuming.
Finally, check that the companion is reachable from the tour and the tour from the companion, and that both carry the same coverage statement. If they disagree about what was photographed, the more confident one is the one people will believe.
What the tour can claim at the end
A good location tour ends with a route a reader can follow, the coverage it actually contains, and the gaps named out loud. That is a modest thing to hand a producer, and it is more persuasive than a slicker version that implies a survey. It says: here are the two spaces, here is the connection between them as recorded, here is how far the images reach, and here is what nobody has photographed yet.
The tour demonstrates supplied images and their asserted connections. It is not permission to film, it is not a set of dimensions, and it is not a promise that the production can go there. Those are separate conversations, and the tour is stronger for not pretending to settle them.
Frequently asked questions
What should be inventoried before building a clickable location tour?
For each space, record whether the capture is a full turn or a partial arc and roughly how many degrees it covers. For each pair of spaces, mark the connection as documented or assumed, because those cases get different treatment in the tour.
What is the difference between haov and hfov in a panorama?
haov is the angular coverage of the photograph, while hfov is the width of the viewing window. Widening hfov does not add image, and stretching a partial capture does not make the room complete.
How should arrival views be set at a scene transition?
Use targetYaw and targetPitch so the reader lands facing the doorway, not the centre of the partial image. In the example, the storeroom doorway at yaw 88 sits outside the initial 90-degree window, so without a target view the return route can be missed.
How should unphotographed areas and direct jumps be handled?
A hotspot cannot sit on image that does not exist, so explain the uncaptured arc in words. Also say that the tour jumps between viewpoints and does not show the threshold crossing, rather than implying the spaces are continuous and measured.
What claims can a location tour support?
It demonstrates supplied images and their asserted connections. It is not permission to film, not a set of dimensions, and not a promise that production can go there; those are separate conversations.