@wework/floormap.gl NPM

floormap.gl

A javascript rendering engine that provides a simple interface to draw shapes, image, text and line on the screen.

Quick Start
Building the library
Example usage in HTML
Example usage in ReactJs application
Creating a new Renderer
Events
RenderObjects

Quick Start

Clone the project

git clone git@github.com:WeConnect/floormap.gl.git
cd floormap.gl

Install dependencies

yarn install

Start the demo

yarn start:demo

Outcome

alt text

Building the library

yarn build

A dist folder will be created, and outputs files are floormap.gl.min.js, index.js and index.es.js files

Gently reminder: In order to use this floormap.gl library in your own node application, you may yarn link first and it will register @wework/floormap.gl in your local development. Then yarn link '@wework/floormap.gl' in your node application

Example usage in HTML

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>FloorMapGL</title>
</head>
<body>
  <div id="floormap"></div>
  <script type="text/javascript" src="dist/floormap.gl.min.js" ></script>
  <script>
    // create a renderer
    var renderer = new FloorMapGL({
      target: document.getElementById('floormap'),
      size: {
        width: 500,
        height: 500
      },
      backgroundColor: 'grey',
      antialias: true,
      pixelRatio: 2
    })

    // draw a simple mesh
    renderer.draw({
      id: '001',
      tags: ['hello'],
      type: 'MESH',
      style: {
        color: 'rgb(155, 255, 55)',
        side: 'FRONT',
        outline: {
          color: 'rgb(255, 0, 0)',
          only: false
        }
      },
      points: [
        { x: -1, y: -1 },
        { x: 1, y: -1 },
        { x: 1, y: 1 },
        { x: -1, y: 1 }
      ],
      interactable: true,
      extrude: 0,
      position: { x: 0, y: 0, z: 0 },
      rotation: { x: 0, y: 0, z: 0 },
      scale: { x: 10, y: 10, z: 10 }
    },
    false,
    (success) => {
      console.log(success)
    },
    (error) => {
      console.log(e)
    })
  </script>
</body>
</html>

Example usage in ReactJs application

link the floormap.gl package in your node application

yarn link '@wework/floormap.gl'

or download the package directly from the npm

yarn add '@wework/floormap.gl'

Example usage in a react application

import React, { Component } from 'react'
import FloorMapGL from '@wework/floormap.gl'

class FloorMap extends Component {
  componentDidMount() {
    this.renderer = new FloorMapGL({
      target: this.mount,
      size: {
        width: 500,
        height: 500
      },
      backgroundColor: 'grey',
      antialias: true,
      pixelRatio: 2
    })

    this.renderer.draw(
      {
        id: '001',
        tags: ['hello'],
        type: 'MESH',
        style: {
          color: 'rgb(155, 255, 55)',
          side: 'FRONT',
          outline: {
            color: 'rgb(255, 0, 0)',
            only: false
          }
        },
        points: [
          { x: -1, y: -1 },
          { x: 1, y: -1 },
          { x: 1, y: 1 },
          { x: -1, y: 1 }
        ],
        interactable: true,
        extrude: 0,
        position: { x: 0, y: 0, z: 0 },
        rotation: { x: 0, y: 0, z: 0 },
        scale: { x: 10, y: 10, z: 10 }
      },
      false,
      (success) => {
        console.log(success)
      },
      (error) => {
        console.log(e)
      }
    )
  }

  render() {
    return (
      <div
        ref={(mount) => {
          this.mount = mount
        }}
      />
    )
  }
}

export default FloorMap

Creating a new Renderer

import FloorMapGL from '@wework/floormap.gl'

var renderer = new FloorMapGL({
  target: domElement,
  size: {
    width: 720,
    height: 480
  },
  backgroundColor: 'black',
  antialias: true,
  pixelRatio: 2,
  camera: {
    maxPolarAngle: 90,
    enableRotate: true,
    zoomLevel: 1
  },
  groundPlane: true
})

Name	Type	Description
target	object	domElement, it is `required`
size	sizeObject	window size of the renderer
backgroundColor	string	background color of the renderer, default is `'black'`
antialias	boolean	Options to smooth the jagged line, default is `true`
pixelRatio	number	The rendering resolution, default is `2`
camera	cameraObject	camera settings
groundPlane	boolean	invisible ground plane for the mouse interaction, default is `false`

sizeObject

Name	Type	Description
width	number	the width of the renderer window, by default is `700`
height	number	the height of the renderer window, by default is `400`

cameraObject

Name	Type	Description
zoomLevel	number	zoom level of the camera view, default is `1`
enableRotate	boolean	to enable to control and rotate the camera view angle, default is `true`
maxPolarAngle	number	max horizontal rotation of the camera in degree, default is `90`

List of APIs in floormap.gl

draw
updateWindowDimension
getIdsByTags
fitContent
getZoom
setZoom
getCenter
setCameraViewPoint
setCameraViewAngle
createInstancedMesh
addToInstancedMesh
drawInstancedMesh
addEventListener
removeEventListener
removeAllEventListeners
remove
removeAll

draw

Draw the list of renderObjects onto the screen

.draw(renderObjects: array, transparentUpdate: boolean, onSuccess: function, onError: function)

Parameters	Type	Description
arrayOfParams	array	array of RenderObjects
transparentUpdate	boolean	flag to enable clearing and re-render the scene again for transparent object
onSuccess	function	callback function when successfully render this draw call
onError	function	callback function when there is an error occur in this draw call

Example:

// create your renderObjects and push into your array first
const renderObjects = []
renderObjects.push({
  id: '001',
  tags: '',
  type: 'MESH',
  style: {
    color: 'rgb(155, 255, 55)',
    side: 'FRONT',
    outline: {
      color: 'rgb(255, 0, 0)',
      only: false
    }
  },
  points: [{ x: -1, y: -1 }, { x: 1, y: -1 }, { x: 1, y: 1 }, { x: -1, y: 1 }],
  interactable: true,
  visible: true,
  extrude: 0,
  position: { x: 0, y: 0, z: 0 },
  rotation: { x: 0, y: 0, z: 0 },
  scale: { x: 1, y: 1, z: 1 },
  draw: true
})

// draw all the renderObjects using .draw
renderer.draw(
  renderObjects,
  false,
  (success) => {
    console.log(success)
  },
  (errors) => {
    console.log(errors)
  }
)

// to update the renderObjects in the future
// using the same .draw() api to update the specific renderObject by id
renderer.draw(
  [
    {
      id: '001',
      style: {
        color: 'rgb(155, 255, 55)'
      },
      position: { x: 10, y: 0, z: 0 }
    }
  ],
  false,
  (success) => {
    console.log(success)
  },
  (errors) => {
    console.log(errors)
  }
)

updateWindowDimension

Update the size of the renderer window

.updateWindowDimension({ width: Number, height: Number })

Parameters	Type	Description
width	number	new width for the renderer window
height	number	new height for the renderer window

Example:

renderer.updateWindowDimension({ width, height })

setCameraViewPoint

Set the camera panning position

.setCameraViewPoint({ position: { x: Number, y: Number, z: Number } })

Example:

renderer.setCameraViewPoint({
  position: { x: 2, y: 0, z: 5 }
})

setCameraViewAngle

Set the camera rotation view angle

.setCameraViewAngle({ polarAngle: Number, azimuthAngle: Number })

Example:

renderer.setCameraViewAngle({ polarAngle: 45, azimuthAngle: -45 })

getIdsByTags

Get all the renderObjects id by tags

.getIdsByTags(tags: Array)

Example:

renderer.getIdsByTags(['tag1', 'tag2'])

fitContent

Adjust the renderer camera view frustum to fit the content space / given drawn boundaries

.fitContent(params: Object)

Parameters	Type	Description
id	string	renderObject id, default is the whole `renderScene boundary`
padding	number	add the padding for the camera view, default is `0`
points	array	custom boundary shape, `optional`

Example:

this.renderer.fitContent()
this.renderer.fitContent({ padding: 50 })
this.renderer.fitContent({ id: '07-124', padding: 50 })
this.renderer.fitContent({ points: points, padding: 50 })

createInstancedMesh

.createInstancedMesh(renderObject: object)

Example:

renderer.createInstancedMesh({
  id: 'MESH_GROUP_1',
  mesh: {
    style: {
      color: 'rgb(155, 255, 55)',
      side: 'FRONT',
      outline: {
        color: 'rgb(255, 0, 0)',
        width: 0.2,
        only: false
      }
    },
    points: [...],
    extrude: 5
  },
})

addToInstancedMesh

.addToInstancedMesh(params: object)

Example:

renderer.addToInstancedMesh({
  id: 'UUID',
  instancingId: 'MESH_GROUP_1',
  style: {
    color: 'rgb(100,101,102)'
  },
  position: { x: 0, y: 0, z: 0 },
  rotation: { z: 0 },
  scale: { x: 1, y: 1, z: 1 }
})

drawInstancedMesh

.drawInstancedMesh(params: object)

Example:

renderer.drawInstancedMesh({ id: 'MESH_GROUP_1' })

addEventListener

subscribe to a renderer event

.addEventListener(eventName: String, callback: Function)

Example:

renderer.addEventListener(renderer.Events.ONMOUSEOVER, mouseEnterCallback)
renderer.addEventListener(renderer.Events.ONMOUSEOUT, mouseLeaveCallback)
renderer.addEventListener(renderer.Events.ONCLICK, onClickCallback)

removeEventListener

unsubscribe to a renderer event

.removeEventListener(eventName: String, callback: Function)

Example:

renderer.removeEventListener(renderer.Events.ONMOUSEOVER, mouseEnterCallback)
renderer.removeEventListener(renderer.Events.ONMOUSEOUT, mouseLeaveCallback)
renderer.removeEventListener(renderer.Events.ONCLICK, onClickCallback)

removeAllEventListeners

unsubscribe all the renderer event listeners

.removeAllEventListeners()

remove

remove specific renderObject by id

.remove(id: String)

Example:

renderer.remove(id)

removeAll

remove all the renderObjects in the renderer

.removeAll()

Example:

renderer.removeAll()

Events

Name	Value	Description
ONCLICK	'onclick'	when the user select the interactable renderObject by clicking/touching
ONHOVER	'onmousehover'	when the user mouse hovering the interactable renderObject
ONMOUSEOVER	'onmouseover'	when moving the mouse pointer onto a renderObject
ONMOUSEOUT	'onmouseout'	when moving the mouse pointer out of a renderObject
ONMOUSEMOVE	'onmousemove'	when moving the mouse pointer
ONRENDER	'onrender'	when .draw api successfully sent all the data to the gpu to render
ONERROR	'onerror'	when floormap.gl renderer encounters any internal errors
ONTEXTURELOAD	'ontextureload'	when texture is loaded and sent to the gpu

ONCLICK

Payload	Type	Description
id	string	id of the renderObject
point	object	intersection point in the world space, x y z value
mousePos	object	the mouse position in screen space, x y value

ONHOVER

Payload	Type	Description
id	string	id of the renderObject
point	object	intersection point in the world space, x y z value
mousePos	object	the mouse position in screen space, x y value

ONMOUSEOVER

Payload	Type	Description
id	string	id of the renderObject
point	object	intersection point in the world space, x y z value
mousePos	object	the mouse position in screen space, x y value

ONMOUSEOUT

Payload	Type	Description
id	string	id of the renderObject
point	object	intersection point in the world space, x y z value
mousePos	object	the mouse position in screen space, x y value

ONMOUSEMOVE

Payload	Type	Description
id	string	id of the renderObject
point	object	intersection point in the world space, x y z value
mousePos	object	the mouse position in screen space, x y value

ONRENDER

Payload	Type	Description
frameTime	number	the time taken to complete this draw call
memory	object	gpu memory info
render	object	render info
renderObjects	array	list of renderObjects to render in the draw call

ONERROR

Payload	Type	Description
error	object	Error() object

ONTEXTURELOAD

Payload	Type	Description
frameTime	number	the time taken to complete this draw call
memory	object	gpu memory info
render	object	render info
renderObjects	array	list of renderObjects to render in the draw call

Mesh

Parameters	Type	Description
id `!required`	string	id of the renderObject
tags	array	renderObject tags
type `!required`	string	renderObject type, 'MESH', 'SPRITE', 'TEXT' or 'LINE'
style	meshStyleObject	style of the renderObject
points `!required`	array	points to construct a shape
geometryTranslate	transformObject	translation for the geometry in object space
interactable	boolean	interaction of this object disable or enable
visible	boolean	visibility flag
extrude	number	extrude level for the mesh
position	transformObject	position of the renderObject
rotation	transformObject	rotation of the renderObject
scale	transformObject	scale of the renderObject

Example:

{
  id: '001', // required
  tags: ['level 3'],
  type: 'MESH',
  style: {
    color: 'rgb(155, 255, 55)',
    side: 'FRONT',
    texture: {
      img: '',
      repeat: 0.5
    }
    outline: {
      color: 'rgb(255, 0, 0)',
      width: 0.2,
      only: false
    }
  },
  points: [
    { x: -1, y: -1 },
    { x: 1, y: -1 },
    { x: 1, y: 1 },
    { x: -1, y: 1 }
  ],
  geometryTranslate: {x: -1, y: -1, z: 0},
  interactable: true,
  visible: true,
  extrude: 2,
  position: { x: 0, y: 0, z: 0 },
  rotation: { x: 0, y: 0, z: 0 },
  scale: { x: 1, y: 1, z: 1 }
}

Draw Outcome:

Text

Parameters	Type	Description
id `!required`	string	id of the renderObject
tags	array	renderObject tags
type `!required`	string	renderObject type, 'MESH', 'SPRITE', 'TEXT' or 'LINE'
style	textStyleObject	style of the renderObject
text `!required`	string	text to draw on the screen
interactable	boolean	interaction of this object disable or enable
visible	boolean	visibility flag
position	transformObject	position of the renderObject
scalar	number	text size

Example:

{
  id: '002',
  tags: ['nothing'],
  type: 'TEXT',
  position: { x: 0, y: 0, z: 0 },
  scalar: 1.0,
  center: { x: 0.5, y: 0.5 },
  style: {
    color: 'rgb(255, 255, 255)',
    fontFamily: 'Arial, Helvetica, sans-serif',
    textAlign: 'center',
    fontWeight: 'normal', // normal, bold, bolder, lighter
    fontStyle: 'italic' // normal, italic, oblique
  },
  text: 'hello world',
  interactable: false,
  visible: true
}

Draw Outcome:

Sprite

Parameters	Type	Description
id `!required`	string	id of the renderObject
tags	array	renderObject tags
type `!required`	string	renderObject type, 'MESH', 'SPRITE', 'TEXT' or 'LINE'
position	transformObject	position of the renderObject
style	textStyleObject	style of the renderObject
interactable	boolean	interaction of this object disable or enable
visible	boolean	visibility flag

Example:

{
  id: '003',
  tags: ['level 3'],
  type: 'SPRITE',
  position: { x: 2, y: 0 },
  center: { x: 0.5, y: 0.5 },
  style: {
    color: 'rgb(255, 255, 255)',
    img: 'https://cdn.spacemob.co/img/meeting_room@2x.png',
    width: 'auto',
    height: 'auto',
    maxWidth: 3,
    maxHeight: 3
  },
  interactable: false,
  visible: true
}

Draw Outcome:

Line

Parameters	Type	Description
id `!required`	string	id of the renderObject
tags	array	renderObject tags
type `!required`	string	renderObject type, 'MESH', 'SPRITE', 'TEXT' or 'LINE'
lineWidth	number	the width of the line
points `!required`	array	points for constructing the line
position	transformObject	position of the renderObject
style	lineStyleObject	style of the renderObject
interactable	boolean	interaction of this object disable or enable
visible	boolean	visibility flag

Example:

{
  id: '004',
  tags: ['level 3'],
  type: 'LINE',
  lineWidth: 1.0,
  points: [
    { x: 0, y: 0 },
    { x: 100, y: 0 },
    { x: 100, y: 90 },
    { x: 200, y: 20 }
  ],
  style: {
    color: 'rgb(255, 0, 255)',
    opacity: 0.7
  },
  interactable: false,
  visible: true
}

Draw Outcome:

Type Definitions

transformObject

Parameters	Type	Description
x	number	set value in x-axis
y	number	set value in y-axis
z	number	set value in z-axis

meshStyleObject

Parameters	Type	Description
color	string	color of the object
side	string	'FRONT', 'BACK' or 'DOUBLE', default is 'FRONT'
texture	number	texture setting of the renderObject
texture.img	string	img path or url
texture.repeat	number	how many times to repeat the image on the object
outline	number	outline setting of the renderObject
outline.color	number	outline color of the object
outline.only	number	if true then will be outline only object

textStyleObject

Parameters	Type	Description
color	string	color of the text
fontFamily	string	default is 'Arial, Helvetica, sans-serif'
textAlign	number	text alignment, 'center', 'left' or 'right', default is 'center'
fontWeight	string	'normal', 'bold', 'bolder' or 'lighter', default is 'normal'
fontStyle	number	'normal', 'italic' or 'oblique', default is 'normal'

spriteStyleObject

Parameters	Type	Description
color	string	color of the sprite
img	string	image path or url
width	number or string	width of the sprite, default is 'auto'
height	number or string	height of the sprite, default is 'auto'
maxWidth	number	maximum width of the sprite
maxHeight	number	maximum height of the sprite