Narcissistic Piano Mover

    famous-map

    0.3.2 • Public • Published

    famous-map

    Map component for Famo.us, supporting the following map-providers:

    Famous-map makes it possible for adding a map-component to the famo.us render-tree. Additionally, famous transitions can be used to pan the map and modifiers can be used to sync the position of renderables with a geographical position.

    Demos

    note: Hit refresh if the demo doesn't load properly. GitHub sometimes rejects loading famous-map.min.js the first time, but it always loads the next time :?

    Getting started

    Install using bower or npm:

    bower install famous-map
    
    npm install famous-map
    

    Google Maps

    Include google-maps in the html file:

    <head>
        <script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=false"></script> 
    </head>

    Create a google-maps view:

    var MapView = require('famous-map/MapView');
     
    var mapView = new MapView({
        type: MapView.MapType.GOOGLEMAPS,
        mapOptions: {
            zoom: 3,
            center: {lat: 51.4484855, lng: 5.451478},
            mapTypeId: google.maps.MapTypeId.TERRAIN
        }
    });
    this.add(mapView);
     
    // Wait for the map to load and initialize
    mapView.on('load', function () {
     
        // Move across the globe and zoom-in when done
        mapView.setPosition(
            {lat: 51.4484855, lng: 5.451478},
            { duration: 5000 },
            function () {
                mapView.getMap().setZoom(7);
            }
        );
    }.bind(this));

    IMPORTANT: Don't forget to read this instruction on google maps running on mobile devices.

    Leaflet

    Include leaflet in the html file:

    <head>
        <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.css" />
        <script src="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.js"></script> 
    </head>

    Create a leaflet map:

    var MapView = require('famous-map/MapView');
     
    var mapView = new MapView({
        type: MapView.MapType.LEAFLET,
        mapOptions: {
            zoom: 3,
            center: {lat: 51.4484855, lng: 5.451478}
        }
    });
    this.add(mapView);
     
    // Wait for the map to load and initialize
    mapView.on('load', function () {
     
        // Add tile-layer (you can also get your own at mapbox.com)
        L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
            attribution: 'Map data &copy; <a href="http://openstreetmap.org">OpenStreetMap</a>'
        }).addTo(mapView.getMap());
    }.bind(this));

    OpenLayers 3

    Include OpenLayers in the html file:

    <head>
      <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/ol3/3.4.0/ol.min.css" />
      <script src="https://cdnjs.cloudflare.com/ajax/libs/ol3/3.4.0/ol.js"></script> 
    </head>

    Create an open-layers map (uses canvas):

    var MapView = require('famous-map/MapView');
     
    var mapView = new MapView({
        type: MapView.MapType.OPENLAYERS3,
        mapOptions: {
            zoom: 3,
            center: {lat: 51.4484855, lng: 5.451478}
        }
    });
    this.add(mapView);
     
    // Wait for the map to load and initialize
    mapView.on('load', function () {
     
        // Add tile-layer (OSM is just one of many options)
        mapView.getMap().addLayer(new ol.layer.Tile({
            source: new ol.source.OSM()
        }));
    }.bind(this));

    Mapbox GL

    Include Mapbox GL in the html file:

    <head>
      <link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.7.0/mapbox-gl.css' rel='stylesheet' />
      <script src='https://api.tiles.mapbox.com/mapbox-gl-js/v0.7.0/mapbox-gl.js'></script> 
    </head>

    Create an mapbox GL map:

    var MapView = require('famous-map/MapView');
     
    var mapView = new MapView({
        type: MapView.MapType.MAPBOXGL,
        mapOptions: {
            zoom: 3,
            center: {lat: 51.4484855, lng: 5.451478}
        }
    });
    this.add(mapView);

    IMPORTANT: Touch events are not yet supported by mapbox-gl-js on mobile, so swiping, pinching, etc.. does not work on your phone or tablet: https://github.com/mapbox/mapbox-gl-js/pull/949

    Documentation

    To access the underlying map object, use MapView.getMap(). The Map-object is only safely accessible after the 'load' event, because the DOM-object must first be created and the map needs to load.

    mapView.on('load', function () {
        var map = mapView.getMap();
        ...
    });
    LatLng notation

    Multiple LatLng formats are supported by the famous-map functions:

    var pos = { lat: 57.876, lng: -13.242 }; // object literal
    var pos = [57.876, -13.242]; // array: [lat, lng]
    var pos = new google.maps.LatLng(57.876, -13.242); // object with .lat() and .lng() functions
    Panning the map using transitions

    To pan the map using famo.us transitions, use MapView.setPosition(). Transitions are chained, so you can create paths that the map will follow.

    mapView.setPosition(
        {lat: 51.4484855, lng: 5.451478},
        {duration: 5000, curve: Easing.outBack},
        function () {
            mapView.getMap().setZoom(7)
        }
    );
    Linking a renderable to a geographical coordinate on the map

    To place a renderable on the map like a marker, use MapModifier or MapStateModifier:

    var MapModifier = require('famous-map/MapModifier');
     
    var surface = new Surface({
        size: [50, 50],
        properties: {
            backgroundColor: 'white'
        }
    });
    var modifier = new Modifier({
        align: [0, 0],
        origin: [0.5, 0.5]
    });
    var mapModifier = new MapModifier({
        mapView: mapView,
        position: {lat: 51.4484855, lng: 5.451478}
    });
    this.add(mapModifier).add(modifier).add(surface);
    Moving a renderable across the map

    MapStateModifier relates to MapModifier in the same way StateModifier relates to Modifier. MapStateModifier makes it possible to change the position from one place to another, using a transitionable. Transitions are chained, so you can create paths that the renderable will follow:

    MapStateModifier = require('famous-map/MapStateModifier');
     
    var surface = new Surface({
        size: [50, 50],
        properties: {
            backgroundColor: 'white'
        }
    });
    var modifier = new Modifier({
        align: [0, 0],
        origin: [0.5, 0.5]
    });
    var mapStateModifier = new MapStateModifier({
        mapView: mapView,
        position: {lat: 51.4484855, lng: 5.451478}
    });
    this.add(mapStateModifier).add(modifier).add(surface);
     
    // Animate the renderable across the map
    mapStateModifier.setPosition(
        {lat: 52.4484855, lng: 6.451478},
        {method: 'map-speed', speed: 200} // 200 km/h
    );
    mapStateModifier.setPosition(
        {lat: 50.4484855, lng: 3.451478},
        {duration: 4000}
    );
    Enable auto-scaling when the map is zoomed in or out

    To enable auto-scaling set zoomBase to the zoom-level you wish the renderables to be displayed in its true size. In this example where zoomBase is set to 5, this would mean that at zoom-level 4 its size will 1/4 of its original size:

    var mapModifier = new MapModifier({
        mapView: mapView,
        position: {lat: 51.4484855, lng: 5.451478},
        zoomBase: 5
    });

    To use a different zooming strategy, use zoomScale. ZoomScale can be set to either a number or a getter function:

    var mapModifier = new MapModifier({
        mapView: mapView,
        position: {lat: 51.4484855, lng: 5.451478},
        zoomBase: 5,
        zoomScale: 0.5
    });
     
    var mapModifier = new MapModifier({
        mapView: mapView,
        position: {lat: 51.4484855, lng: 5.451478},
        zoomBase: 5,
        zoomScale: function (baseZoom, currentZoom) {
            var zoom = currentZoom - baseZoom;
            if (zoom < 0) {
                return 1 / (2 * (Math.abs(zoom) + 1));
            } else {
                return 1 + (2 * zoom);
            }
        }
    });
    API reference
    Class Description
    MapView View class which encapsulates a maps object.
    MapModifier Stateless modifier which positions a renderable based on a geographical position {LatLng}.
    MapStateModifier Modifier which positions a renderable based on a geographical position {LatLng}, using transitions.
    MapUtility General purpose utility functions.
    MapTransition Transition for moving at a certain speed over the map (km/h).
    MapPositionTransitionable Transitionable for geographical coordinates {LatLng}.

    Known issues & performance

    Google-Maps and Drag/Pinch on mobile devices

    Famo.us prevents 'touchmove' events on mobile devices, which causes drag-to-move and pinch-to-zoom to break in Google Maps. To workaround this problem, disable 'app-mode' on mobile devices and instead install the custom MapView touch-handler before the main-context is created:

    var Engine = require('famous/core/Engine');
    var MapView = require('famous-map/MapView');
    var isMobile = require('ismobilejs'); // https://github.com/kaimallea/isMobile
     
    // On mobile, disable app-mode and install the custom MapView
    // touch-handler so that Google Maps works.
    if (isMobile.any) {
        Engine.setOptions({appMode: false});
        MapView.installSelectiveTouchMoveHandler();
    }
     
    var mainContext = Engine.createContext();
    ...

    Resources:

    Panning the map & smoothness

    Panning the map using MapView.setPosition() and a transition works great, but is not as smooth in all scenarios and on all devices. Panning is smoothest for smaller tile-distances. To see map panning in action at different speeds, view the nyat-cat demo.

    Google-Maps and Zoom-levels < 3

    At the lower zoom-levels, renderables may not be positioned correctly using Google Maps. This happens when the entire world fits more than once on the surface. In this case, the bounding east and west longitude cannot be determined through the google-maps API, which are required for calculating the x position. To workaround this issue, set mapOptions.minZoom to 3.

    Renderables lag and Leaflet

    The leaflet-API returns the position and zoom-level after animations have occured. This causes a small lag in the position of renderables when panning the map. When zooming the map, the renderables are re-positioned after the zoom and smooth zooming is therefore not possible and disabled.

    Contribute

    Feel free to contribute to this project in any way. The easiest way to support this project is by giving it a star.

    Contact

    © 2014 / 2015 - Hein Rutjes

    Install

    npm i famous-map

    DownloadsWeekly Downloads

    40

    Version

    0.3.2

    License

    none

    Last publish

    Collaborators

    • ijzerenhein