Constructor

MapView
(
  • container
  • venue
  • options
)

Parameters:

  • container Div

    The div to place the MapView in.

  • venue MappedinVenue

    The results from the Mappedin API that powers this MapView.

  • options Object

    Some options the MapView can use.

    • [antialias=true] Boolean optional

      Controls whether antialiasing is on. Defaults to true, as long as devicePixelRatio is 1. This is very expensive on high resolution screens.

    • [onDataLoaded] Function optional

      A callback executed with the 3D files have been downloaded for the first map, and are starting to load into memory. The MapView is fully functional at this point, but some things will still be popping in.

    • [onFirstMapLoaded] Function optional

      A callback executed when the first Map is fully loaded. This means onDataLoaded has already been fired (if specified) and then all the textures and other resources have finished popping in.

    • [firstMap] MappedinMap optional

      If you don't want to load the default Map first, set the Map you want to load first here. Useful for deep linking to a certain floor/location. Since you won't have the Map object/ID until you get the MappedinVenue data, there is a callback you can set on Mappedin.initializeto fill this in.

The base MapView. This will either be 2D or 3D. Make sure you run one of Mappedin.test3D, .forceTest, .force2D or .force3D before you try an instantiate one.

Show:
addInteractivePolygon
(
  • polygon
)

Makes a single Polygon hoverable/clickable. Polygons you haven't called this on will be treated as non-interactive and not respond to any mouse events.

Parameters:

addInteractivePolygonsForAllLocations
(
  • options
)

Makes all polygons attached to a location hoverable/clickable. Polygons you haven't called this on will be treated as non-interactive This is a convenience function for calling addInteractivePolygon on all the polygons attached to all locations. You may also make individual polygons interactive with the addInteractivePolygon method instead of, or in addition to this method.

Parameters:

  • options Object
    • [excludeTypes=[]] [String] optional

      A list of Location types to skip. All locations of this type will be treated as non-iteractive

    • [locations] [MappedinLocation] optional

      An array of Location objects. Overrides the default of making all locations interactive, and instead applies to only the locations specified here.

addMap
(
  • map
)

Adds a Map

Parameters:

addMarker
(
  • marker
)

Adds an already created Marker to the scene. The Marker constructor is more powerful than the createMarker convenience function.

Parameters:

  • marker Marker

    The Marker to add.

clearAllPolygonColors ()

Resets ALL Polygons you have changed with setPolygonColor back to their original color. The hover effect will still be present if the user is currently hovering over a Polygon.

clearPolygonColor
(
  • polygon
)

Resets a Polygon back to it's original color. If the user is hovering over a polygon, it will still have the hover effect.

Parameters:

contractMaps
(
  • options
)

Contract maps and display the current map

Parameters:

  • options Object

    Options object @optional

    • [focus] Boolean optional

      Focus the camera onto current map

    • [debug] Boolean optional

      Display cubes around focus bounding box for debug info

    • [duration=300] Number optional

      Duration of focus animation in ms

convertTo3DMapPosition
(
  • coordinate
)
Object
private

Takes an x/y pair in Mappedin coordinate space and gives you an object suitable to use as a Marker's position. Be careful about using this: The coordinate system could change arbitrarily and without notice. You are better off using a specific Node or Polygon as an anchor. If you need to use this for some reason, talk to your Mappedin representative.

Parameters:

  • coordinate X, y

    } A coordinate in Mappedin 2D space.

Returns:

Object:

The position to anchor a Marker in 3D space.

createFont
(
  • facetypeJson
)
Font
deprecated

Deprecated: Use static method MapView3D.{{#crossLink "MapView3D/createFont:method"}}{{/crossLink}} instead

Create a font for use in 3D by passing in a JSON object generated from https://gero3.github.io/facetype.js/ Ignored in 2D, retuning null

Parameters:

  • facetypeJson Object

    Convert a font into JSON with Facetype.js, and put it in here.

Returns:

Font:

Returns the ThreeJS Font object created with the JSON, or null in 2D

createMarker
(
  • html
  • positing
  • className
  • map=this.currentMap
  • options
)
Marker

This creates a div with whatever HTML you provide, anchors it to position in 3D space, and optionally applies a css class you provide. position should be something you got from getPositionPolygon or getPositionNode. The Marker is added for you, on to the currentMap, (or the one you specify).

Parameters:

  • html String

    The HTML that the Marker will be. Typically just some text or an image, but you can be more creative if you want.

  • positing Object

    The position in 3D space to anchor the Marker to. Do not attempt to create it manually: use getPositionPolygon or getPositionNode.

  • className String

    The name of the CSS class to apply to the Marker.

  • [map=this.currentMap] MappedinMap | String optional

    The map to add the Marker on. Defaults to the current map.

  • options Object

    Passes on options (e.g. rotation, collisions, rotation with camera) to MapView.Marker's options argument.

Returns:

Marker:

The Marker you created, which has already been added to the scene.

drawPath
(
  • path
  • options
)
PathSegment

Draws an entire path. It takes a list of Nodes and will break them into separate pathSegments on every map change, putting the resultant segment on the right Map.

If you have a special use case (like off graph nodes, or Venues with same Vortexes) use the drawPathSegment function.

Returns an array of pathSegments if you want to customize the animation triggers. The pathSegements are added to the scene, chained together, and start animating automatically.

Parameters:

  • path [MappedinNode]

    An array of Nodes, probably from a Node's directionsTo call.

  • [options] Object optional

    A list of style options for the path. Not everything is supported in 2D. See drawPath for available options. Note that drawDuration is per segment.

Returns:

PathSegment:

An array of pathSegments.

drawPathSegment
(
  • path
  • options
)
PathSegment

Takes a list of {x, y} pairs in Mappedin coordinate space and draws a connected path on the specified Map. Use this function for special cases not handled by the drawPath convenience function. Returns a pathSegment. You will need to call it's Tween.start() function to begin animation and make the path segment visible. You can customize the Tween.js tween if you like, but make sure tryRendering is always called in onUpdate or the path may stop.

Parameters:

  • path [MappedinNode]

    An array of Nodes, probably from a Node's directionsTo call.

  • [options] Object optional

    A list of style options for the path. Not everything is supported in 2D.

    • [color=this.colors.path] Integer optional

      Color of path. Uses colors.path if not specified.

    • [pulseColor=this.colors.pathPulse] Integer optional

      Color of path pulse. Uses colors.pathPulse if not specified. Ignored in 2D.

    • [radius=10] Integer optional

      The radius of the path.

    • [drawDuration=3000] Integer optional

      Duration the path fade in animation for this segment, in milliseconds.

    • [curve=Mappedin.Easing.Circular.InOut] Easing optional

      The animation curve to use for the path fade in animation.

Returns:

PathSegment:

A path segment object, with a tween property you should start(), and a reset() function to set it back to it's default state.

enableImageFlippingForAllLocations
(
  • options
)

Let any image attached to a Polygon attached to a Location flip 180 degrees with the camera so it's always upright.

Parameters:

  • options Object
    • [excludeTypes=[]] [String] optional

      A list of Location types to skip, if for some reason there are Locations that have logos that shouldn't flip.

    • [locations] [MappedinLocation] | [String] optional

      An array of Location objects, or Location IDs. If excludeTypes is not sufficient you can explicitly set the Locations you are marking to flip. You can also call enableImageFlippingForPolygon manually for every polygon you care about instead.

enableImageFlippingForPolygon
(
  • options
)

Mark a specific Polygon so, if it has an image, it rotates with the camera.

Parameters:

  • options Object
    • polygonId String

      The ID of the Polygon who's image (if any) should rotate.

    • [rotation] Number optional

      The how much the image has been rotated so that it's "up". Determined from the Polygon object itself typically, but can be set manually if needed.

expandMaps
(
  • mapIds
  • options
)
Promise

Expand maps to display within view, typically used for multi-floor navigation. When passed a connection, maps included will not be displayed, instead, their 2d projection will be available in the resulting promise, which can be used to display a 2D component in the client-side app.

Parameters:

  • mapIds Array

    Array of mapIds or mapObjects to display while expanded. For connections, pass { connection: true, maps: [], connectionNodes: [], }

  • options Object

    Options object @optional

    • [focus=false] Boolean optional

      Focus the camera onto expanded maps

    • [debug=false] Boolean optional

      Display cubes around focus bounding box for debug info

    • [rotation=0] Number optional

      Rotation of scene relative to zero (degrees)

    • [duration=300] Number optional

      Duration of focus animation in ms

Returns:

Promise:

Promise that resolves to 2d screen projections of each layer/map (see example)

Example:

// expand maps with 3 connection maps in between
  expandMaps(
      '55e89771d982bc06ca000000',
          {
              connection: true,
              // connection nodes are an exit node from the '55e89771' man and entry node for the '55e9c73f' map
              connectionNodes: [{
                  map: "55e89771",
                  x: 6232,
                  y: 4575
              }, {
                  map: "55e9c73",
                  x: 5945.000000000001,
                  y: 4059.000000000001
              }],
              maps: [
                  '55e9acbf',
                  '55e8a9ed',
                  '55e85e23'
              ]
          },
          '55e9c73f'
       );
  
       // resulting promise (sorted by elevation (top to bottom))
  
       [
          {
              min: { x: -100, y: -50 },
              max: { x: -100, y: -50 }
          },
          {
              min: { x: -100, y: -50 },
              max: { x: -100, y: -50 }
          },
          {
              min: { x: -100, y: -50 },
              max: { x: -100, y: -50 }
          }
       ]
focusOn
(
  • options
  • option.changeZoom=true
)
Tween

A flexible function that will let you focus on collections of Nodes and/or Polygons. This will move the camera to the center of all items passed in, and by default. zoom the camera in or out to fit everything in view, scaled by focusZoomFactor.

Parameters:

  • options Object

    You should provide at least one Node or Polygon, but everything else is optional.

    • [nodes] [MappedinNode] optional

      An array of Nodes to focus in on.

    • [polygons] [MappedinPolygon] optional

      An array of Polygons to focus on. It's the center of the bounds of all Polygons, designed to fit everything into view.

    • [duration=100] Number optional

      The duration the focus animation should last for.

    • [curve] Easing optional

      The animation curve to use for zooming in. Uses the animateCamera one by default.

    • [focusZoomFactor=this.focusZoomFactor] Number optional

      You can overide the focusZoomFactor for a specific focusOn call, rather than globally, if you like.

    • [minZoom=0] Number optional

      Sets a floor for how close you can zoom in on the scene. If it's lower than mapView.controls.minZoom, it's ignored.

  • [option.changeZoom=true] Boolean optional

    Whether to zoom the camera in or out, or just pan it.

Returns:

Tween:

Returns the Tween for advanced usage. Can generally be ignored.

focusOnPath
(
  • path
  • polygonIds
  • changeZoom=false
  • duration=100
  • curve=Mappedin.Easing.Quadratic.In
)

Moves the camera to focus on an entire path and optionally it's starting and ending Polygon.

Parameters:

  • path [MappedinNode

    The Nodes to fit the camera to.

  • polygonIds [String] | [MappedinPolygon]

    The Polygon or Polygon ID to focus on. The camera will move to the centroid of Polygon.

  • [changeZoom=false] Boolean optional

    Whether to zoom the camera in or out so it fits the Polygon's bounds. Scaled by focusZoomFactor.

  • [duration=100] Integer optional

    The time the camera should spend moving, in milliseconds.

  • [curve=Mappedin.Easing.Quadratic.In] Easing optional

    The animation curve to use.

focusOnPolygon
(
  • polygon
  • changeZoom=false
  • duration=100
  • curve=Mappedin.Easing.Quadratic.In
)

Moves the camera to focus in on a specific Polygon

Parameters:

  • polygon String | MappedinPolygon

    The Polygon or Polygon ID to focus on. The camera will move to the centroid of Polygon.

  • [changeZoom=false] Boolean optional

    Whether to zoom the camera in or out so it fits the Polygon's bounds. Scaled by focusZoomFactor.

  • [duration=100] Integer optional

    The time the camera should spend moving, in milliseconds.

  • [curve=Mappedin.Easing.Quadratic.In] Easing optional

    The animation curve to use.

getNorth () Number

Returns the angle that points to north, in radians, from the default orientation.

Returns:

Number:

The angle to north from the default orientation, in radians.

getPathLength
(
  • path
)
Integer

Calculates the length of the connected path in list of Nodes. Breaks in the path (to go to other floors) count as 0 distance. The Z value is also ignored.

Parameters:

Returns:

Integer:

The 2D length of the path

getPositionNode
(
  • node
)
Object

Gives you the position of a Mappedin node in the 3D scene. Suitable for use as a Marker's position.

Parameters:

Returns:

Object:

The position to anchor a marker in 3D space.

getPositionPolygon
(
  • polygon
)
Object

Gives you the top center of a Polygon in 3d scene space. Suitable for use as a Marker's position.

Parameters:

Returns:

Object:

The position to anchor a Marker in 3D space.

getPrimaryLocationForPolygon
(
  • polygon
)
MappedinLocation

Finds the main Location associated with a Polygon. This means a Location attached to the Polygon that has no parents, or, if there are none of those, a Location nearest the top of some hierarchy that does have the Polygon attached.

This means if there are multiple hierarchies of Locations attached to the Polygon, the one that gets returned is not guaranteed to be what you want.

Parameters:

Returns:

getZoomLevelForCurrentMap () Integer

Returns the value you should call setZoom on to fit the currentMap exactly.

Returns:

Integer:

The zoom level that will fit the currentMap.

getZoomLevelForPolygon
(
  • polygon
)
Integer

Returns the value you should call setZoom on to fit the Polygon exactly.

Parameters:

Returns:

Integer:

The zoom level that will fit the Polygon

labelAllLocations
(
  • options
)

Labels all Locations, in order of distance from the center of the Map. See labelPolygon for available label options. The options are all optional, as the text and Polygon properties will be set for each Location.

Parameters:

  • options #crossLink "MapView/labelPolygon:property"

    Any option from }{{/crossLink}} (except text, polygon, canvasBounds, height and map), plus:

    • [excludeTypes=[]] A list of Location types to skip labeling. ["Amenities"] [String] optional

      is often used.

    • [sortFunction] Function optional

      A sorting function that will determine which Location wins when a Polygon belongs to more than one. Uses the Location.sortOrder property by default, but if you have special logic you can use it here.

    • [locations] [MappedinLocation] | [String] optional

      An array of Location objects, or Location IDs. If excludeTypes and the sort function are not sufficient, you can explicitly set the Locations you are labeling. You can also call MapView/labelPolygon:property manually for every polygon you care about instead.

labelPolygon
(
  • options
)
TextLabel

Labels a specific Polygon (or area of 3D space) with a TextLabel that lives in 3D space. That means it will be smaller when the camera is further away, and the angle you see it at will change with the camera. The text will flip 180 degrees when the camera rotates so it's never totally upside-down.

It also sets the hover label (in 2D and 3D). Many of these options do nothing in 2D, as TextLabels are not supported, but it won't break anything.

You must provide text, and either a Polygon, or a canvasBounds and height

Parameters:

  • options Object

    Most options are optional, but you do need text and either a Polygon, or a canvasBounds and height.

    • text String

      The full name text to use for the label.

    • shortText String

      The short name text to use for the label.

    • polygon MappedinPolygon | String

      The Polygon or Polygon Id to make a label for. Only optional if you have set canvasBounds and height.

    • [canvasBounds] CanvasBounds optional

      Set this if you want to label an arbitrary part of the Map. You will need to specify height as well.

      • x Integer
        The x coordinate for the TextLabel anchor.
      • y Integer
        The y coordinate for the TextLabel anchor.
      • width Integer
        The horizontal space we have to fit the TextLabel.
      • height Integer
        The vertical space we have to fit the TextLabel.
      • align "left" | "right" | "center"
        Whether the TextLabel should be anchored against the (x,y), or the opposite (horizontal) side of the box, or in the middle. It is always vertically centered.
    • [height] Float optional

      By default this is the upper bounds of the Polygon. If you don't have a Polygon, or want a custom height for some reason, you can set this.

    • [map] MappedinMap | String optional

      If Polygon is not set, this will let you add a TextLabel to another Map. Otherwise, it will use the currentMap.

    • [margin=5] Float optional

      The amount of space to leave before starting the text

    • [color=this.colors.text] Integer optional

      A optional special color if you don't want to use MapView.colors.text

    • [fontSize=12] Integer optional

      How big to make the font. Defaults to 12

    • [font] optional

      A CSS style string font. ie "sans-serif". You can specify your own font via @font-face rule with a font family, and then include that here. Note: Support for a THREE.Font object is still supported, but is deprecated.

    • [scaleMin=0.25] Float optional

      The minimum percentage we can shrink the label to if it won't fit within the bounds at 100%. If it doesn't fit at that level, it won't be created.

    • [scaleStep=.25] Float optional

      How much to decrement the scale each time it doesn't fit, so we don't end up with too many different font sizes on screen at once. If you are only labeling a few Polygons rather than everything, you can set this and and scaleMin to 0.1 to fit everything except really long names perfectly.

Returns:

TextLabel:

The TextLabel, added to the scene for the correct Map.

lockNorth
(
  • element
  • offset
)

Takes an element on the DOM and rotates it such that the top is pointing north. It will rotate with the camera, staying locked on north. If you would like to align it do a different direction, or a different side of the element, pass in an offset. This is how you would do a compass rose.

This will modify your element's transform.

Parameters:

  • element DOM Node

    The element on the page to rotate.

  • offset Number

    The amount to offset the rotation by, in radians.

onNothingClicked ()

This is fired when the user taps/clicks on the MapView without hitting an interactive Polygon. You will almost certainly want to replace this with your own function in your client app. You would probably use this to clear any Polygon highlighting, in certain situations.

onPolygonClicked
(
  • polygon
)
Boolean

This is called when an interactive Polygon is clicked on. You will almost certainly want to replace this with your own function in your client app. Return "false" if you have consumed the event and it shouldn't bubble down to other Polygons beneath this one.

Parameters:

Returns:

Boolean:

False if the event has been consumed and should not bubble down to other Polygons beneath it.

removeAllLabels ()

Removes all labels from all Maps.

removeAllMarkers ()

Removes all Markers (from all Maps, not just the current one).

removeAllPaths ()

Removes all pathSegments from all Maps.

removeInteractivePolygon
(
  • polygon
)

Makes a polygon no longer hoverable/clickable.

Parameters:

  • polygon MappedinPolygon | String

    The previously interactive Polygon/Polygon ID to make non-interactive.

removeMap
(
  • map
)

Removes a Map

Parameters:

removeMarker
(
  • marker
)

Removes a Marker you have added previously.

Parameters:

removePathSegment
(
  • pathSegment
)

Removes a specific path segement from the map it's on.

Parameters:

resetCamera
(
  • forceOrigin=false
)

Resets the pan, tilt and rotation of the camera and sets the zoom to fit the currentMap.

Parameters:

  • [forceOrigin=false] Boolean optional

    Flag to forcibly reset the camera to origin (0, 0) instead of the centre of the map's bounding box.

setBackgroundColor
(
  • color
  • alpha=1
)

Sets the clear color of the Map something else, it you want it to fit it more with your website. Otherwise the div will be white where there is no Map visible.

Parameters:

  • color Integer

    The color to use. Not an HTML color name.

  • [alpha=1] Number optional

    Opacity between 0 and 1.

setMap
(
  • map
)

Change the currently displayed Map to a new one.

Parameters:

setPolygonColor
(
  • polygon
  • color=this.colors.select
  • textColor=this.colors.textSelect
)

Given a polygon/polygon id, set it to a specific color, and set any text label associated with that polygon to another color.

Parameters:

  • polygon String | MappedinPolygon

    The Polygon/Polygon ID to change the color of.

  • [color=this.colors.select] Integer optional

    The color to use.

  • [textColor=this.colors.textSelect] Integer optional

    The color to use for any TextLabel.

tryRendering ()

The scene only renders when something has changed. This should be something a 3rd party developer doesn't need to worry about, but if you are doing something weird, or have your own special tween for something, you will want to call this function. You can call it as often as you want, it just sets a flag that we need to render again, and renders a few frames if we weren't already doing that. Ignored in 2D.

unlockNorth
(
  • element
)

Stops the MapView from trying to rotate your element with the camera. Do this if you remove the element, or want to stop it from rotating.

Parameters:

  • element DOM Node

    The node to stop rotating. It won't reset the transform, just leave it as is.

colors

Object

These are the default colours used by the MapView to control things like path and selection. You can override these here to quickly style your app, but most of them can also be set (especially for special cases) in their respective functions. The only value that MUST be set here is hover.

Sub-properties:

  • hover Integer

    The color a polygon changes to on mouse over. Defaults to 0xcccccc

  • select Object

    The color used when you call setPolygonColor with no color parameter. Defaults to 0x4ca1fc

  • text Object

    The color used for TextLabels, if you don't specify it in labelAllLocations/labelPolygons. Defaults to 0x000000

  • path Object

    The color used for the path in drawPath/drawPathSegment if you don't specify it there. Defaults to 0xff834c

  • pathPulse Object

    The color of the animated path pulse if not specified in drawPath/drawPathSegment. Defaults to 0xffffff

  • textSelect Object

    The color a TextLabel is set to when you call setPolygonColor, if you don't specify it there. Defaults to 0xffffff

container

Div const

The div MapView is using.

controls

CameraControls const

Manual camera controls for MapView. Generally you should be using the functions on MapView like focusOn, but if you have some cool animations in mind, you can do it with the CameraControls. Some of the functions don't do anything in 2D.

currentMap

String

READ ONLY The ID of the Map currently being displayed.

focusZoomFactor

Integer

Change this factor to influence how much the camera zooms in on a focusOn call.


Default: 3

type

String const

This property identifies which of the Mappedin.modes you are in, incase you have special functionailty in your app when in 2D vs 3D mode. It will be one of "MapView", "MapView3D," or "MapView2D".

venue

MappedinVenue const

The Venue data this MapView is using.