Naval Pilgrim's Mayflower

    cytoscape-mapbox-gl

    1.2.0 • Public • Published

    cytoscape-mapbox-gl

    Mapbox GL plugin for Cytoscape

    Demo

    Screenshot

    Compatible with Mapbox GL v1.13 or earlier. Compatibility with v2 is not guaranteed due to license change. Compatibility with MapLibre fork is under consideration.

    Compatible with Cytoscape plugins:

    Incompatible with Cytoscape plugins:

    • cytoscape-panzoom
      • disable with cy.panzoom('destroy') after enabling cy.mapboxgl(...)
      • add map navigation control
      • enable with cy.panzoom() after calling cyMap.destroy()

    Install

    npm install mapbox-gl-js cytoscape-mapbox-gl
    

    or

    <script src="https://api.mapbox.com/mapbox-gl-js/v1.13.0/mapbox-gl.js"></script>
    <link href="https://api.mapbox.com/mapbox-gl-js/v1.13.0/mapbox-gl.css" rel="stylesheet">
    <script src="https://unpkg.com/cytoscape-mapbox-gl@1.2.0/dist/cytoscape-mapbox-gl.min.js"></script>
    

    Usage

    The plugin exposes a single function, which should be used to register the plugin to Cytoscape.js.

    import cytoscape from 'cytoscape';
    import cytoscapeMapboxgl from 'cytoscape-mapbox-gl';
    
    cytoscape.use(cytoscapeMapboxgl);
    

    Plain HTML/JS has the extension registered for you automatically.

    API

    export interface MapboxglHandlerOptions {
      getPosition: (node: cytoscape.NodeSingular) => mapboxgl.LngLatLike;
      setPosition?: (node: cytoscape.NodeSingular, lngLat: mapboxgl.LngLat) => void;
      animate?: boolean;
      animationDuration?: number;
    }
    
    const cyMap = cy.mapboxgl(mapboxOptions: mapboxgl.MapboxOptions, options: MapboxglHandlerOptions);
    
    • mapboxglOptions - see Mapbox GL JS docs for detailed documentation
    • options
      • getPosition - function, should return node position, required
      • setPosition - function, should save the node position
      • animate - animate the transition between graph and map mode
      • animateDuration - animation duration for the transition between graph and map mode

    If no setPosition option is provided, it's important to disable node dragging with Cytoscape methods, e.g. with cy.autoungrabify(true).

    If node dragging is kept enabled and no setPosition option is provided, or setPosition returns without saving, node position is reverted back to the original position after node dragging is finished. This behavior can be also used for cancelling.

    Basic

    cy.autoungrabify(true); // disable node dragging
    const cyMap = cy.mapboxgl(..., {
      getPosition: (node) => {
        return [node.data('lng'), node.data('lat')];
      }
    });
    

    Node dragging enabled

    const cyMap = cy.mapboxgl(..., {
      getPosition: (node) => {
        return [node.data('lng'), node.data('lat')];
      },
      setPosition: (node, lngLat) => {
        node.data('lng', lngLat.lng);
        node.data('lat', lngLat.lat);
      }
    });
    

    Use raster basemap layer

    const cyMap = cy.mapboxgl({
      style: {
        'version': 8,
        'sources': {
          'raster-tiles': {
            'type': 'raster',
            'tiles': ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],
            'tileSize': 256,
            'attribution': '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
          }
        },
        'layers': [
          {
            'id': 'raster-tiles',
            'type': 'raster',
            'source': 'raster-tiles',
            'minzoom': 0,
            'maxzoom': 19
          }
        ]
      }
    }, ...);
    

    OpenStreetMap tiles are not recommended for heavy use. See OpenStreetMap Tile Usage Policy for details. See Tile servers at OpenStreetMap wiki for possible alternatives, or consider commercial alternatives such as Mapbox, Maptiler, or running your own tile server.

    Use Mapbox vector basemap layer

    const cyMap = cy.mapboxgl({
      accessToken: '...',
      style: 'mapbox://styles/mapbox/streets-v11'
    }, ...);
    

    This requires Mapbox access token.

    Use Maptiler vector basemap layer

    const cyMap = cy.mapboxgl({
      style: 'https://api.maptiler.com/maps/basic/style.json?key=...'
    }, ...);
    

    This requires Maptiler access token.

    Fit map to nodes

    cyMap.fit(nodes = this.cy.nodes(), options)
    
    • nodes - cytoscape.NodeCollection, the collection to fit to (default all nodes)
    • options - mapboxgl.FitBoundsOptions, see Mapbox GL JS docs for detailed documentation

    Access Mapbox GL instance

    cyMap.map
    

    See Mapbox GL JS docs for detailed documentation.

    Add map navigation control

    cyMap.map.addControl(new mapboxgl.NavigationControl(), 'top-left');
    

    Destroy

    cy.autoungrabify(false); // enable node dragging, if node dragging was disabled earlier with `cy.autoungrabify(true)`
    cyMap.destroy();
    

    Sponsors

    Graphlytic

    Graphlytic is a customizable web application for collaborative graph visualization and analysis. There is a free version for Neo4j Desktop available.

    Install

    npm i cytoscape-mapbox-gl

    DownloadsWeekly Downloads

    41

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    1.03 MB

    Total Files

    21

    Last publish

    Collaborators

    • zakjan