An overview of Popcorn.js Streetview

Back in Feb. of 2011 I wrote a blog post about my experience with fixing a bug in Popcorn.js, which had to do with Google Maps streetview integration with Popcorn.  It was a post briefly outlining what I had done and the trials and tribulations that came with it.  When I wrote this I figured what I said would be enough to explain what needed to be done in order to get a map running, but I was ignorant to the fact that there may be people reading my blog ( or trying to use Popcorn ) who have no experience in using Popcorn.js.

Earlier today a gentlemen left a comment on that old post that he was having issues getting streetview to work in popcorn, and was wondering if I could elaborate on the code, and possibly throw up a working example.  I figured why not, so here it is!

First off, the Google Maps plugin provides numerous options available to the user, as per the following:

Adds a map to the target div centered on the location specified by the user
Options parameter will need a start, end, target, type, zoom, lat and lng, and location
-Start is the time that you want this plug-in to execute
-End is the time that you want this plug-in to stop executing
-Target is the id of the DOM element that you want the map to appear in. This element must be in the DOM
-Type [optional] either: HYBRID (default), ROADMAP, SATELLITE, TERRAIN, STREETVIEW
-Zoom [optional] defaults to 0
-Heading [optional] STREETVIEW orientation of camera in degrees relative to true north (0 north, 90 true east, ect)
-Pitch [optional] STREETVIEW vertical orientation of the camera (between 1 and 3 is recommended)
-Lat and Lng: the coordinates of the map must be present if location is not specified.
-Location: the adress you want the map to display, must be present if lat and lng are not specified.
Note: using location requires extra loading time, also not specifying both lat/lng and location will
cause and error.

Tweening works using the following specifications:
-location is the start point when using an auto generated route
-tween when used in this context is a string which specifies the end location for your route
Note that both location and tween must be present when using an auto generated route, or the map will not tween
-interval is the speed in which the tween will be executed, a reasonable time is 1000 ( time in milliseconds )
Heading, Zoom, and Pitch streetview values are also used in tweening with the autogenerated route

-tween is an array of objects, each containing data for one frame of a tween
-position is an object with has two paramaters, lat and lng, both which are mandatory for a tween to work
-pov is an object which houses heading, pitch, and zoom paramters, which are all optional, if undefined, these values default to 0
-interval is the speed in which the tween will be executed, a reasonable time is 1000 ( time in milliseconds )

This description itself can be a lot to take in for someone who is unfamiliar with either popcorn or the google maps API.  In order to get a basic Map to work we are going to need the following:

  • An in and out time (in seconds)
  • A target, which is simply a DoM element that houses the map.  In most cases this is a div, so simply creating a div, such as <div id="googlemaps"></div> will serve us just fine
  • Either a location or lat/lng values, which i will explain a bit more about below

First off, we need to create an html page to in order to view what we want in the browser, I'm assuming if your trying to get something like popcorn working, you already have a working knowledge of making a simple webpage and so on.  After this we are going to include the popcorn-complete script that we are going to need to do everything popcorn within our page ( if you don't have this yet, you can download it here ).  This will be included within the <head> portion of your page, like so:

<script src="popcorn-complete.js"><script>

We have now included the entire Popcorn.js library and can do everything we need to do with this.  We now need to write our unique Popcorn code in order to create our very own Popcorn.js experience.  This will be done in a new script tag as follows ( add this below the previous script tag we added ):

<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function () {
}, false);

The block of code above adds some code that will be run when our HTML page is opened.  We added a document event Listener which will wait until all of DoM content has loaded before executing what is within function() { }.  This allows us to ensure that everything is loaded before we try to add something to a DoM element (like our target ) and so forth.  Next we need to add a video tag in order to use a video within our webpage, this can be done as follows (which is within the body of your webpage):

    <video height="180" width="300" id="ourvideo" controls>
      <source src=""></source>
      <source src=""></source>
      <source src=""></source>

and while were at it we will add our div for the map as well:

<div id="googleMap"></div>

We are now finally ready to write some popcorn code!  Within our DomContentLoaded function, we will write our Popcorn code which will be executed once all of the DoM content is loaded.  For a simple Streetview Map this will looks like:

document.addEventListener('DOMContentLoaded', function () {
  //  Create a popcorn instance with a reference to our video
  var p = Popcorn("#ourvideo");
  //  Add a map at 2 seconds
    start: 2, // Our start time in seconds
    end: 6 // Our end time in seconds
    type: "STREETVIEW" // The type of map that we want
    target: "googlemap",  // The id of our target DoM elemnt
    location: "New York" //  The location we want our map to display at
    zoom: 1 // Setting the zoom that we would like
}, false);

And thats about it!  you can now save your page and view it and we should have a function google maps streetview!  Here is a working example of the code that I have written.

There are some awesome starter guides currently up on the website, which I highly recommend taking a look at (they can be found here).  Hope this helps anyone having issues with it!