Room3D

Introduction

Room3D is a javascript plugin which you can use it to create a 3D room or box by html&css so easily.
It is light-weight and no need to rely on any other library. We design it just for help developers to quick create some simple 3D scene, or be used for some simple web 3D effects. If you need to create some huge complicated scene in your project, and hope it has a perfect render effect, you may not be content for it. We suggest to use some library which it based on WebGL like threeJs/babylonJs.

———— Author: DAN

中文文档    |    English Document   |   DEMO on gitee   |   DEMO on git   |   Github Repository   |   Npm Package

Get Started

1. After installed plugin you can get a constructor named Scene3D

   • Import plugin with script tag <script src="room3d.js"></script> , or
   • Install plugin by npm npm install room3d , then
     • use const Scene3D = require("room3d") or
     • import Scene3D from "room3d" to get Scene3D constructor.

2. Import stylesheet room3d.css

3. Create HTML element <div id="wraper"><div> , you can use id or class as the css selector. You can also set css rules width and height for the element. If you don't, the plugin will set the rules widt:100%; height:100%; for it.

4. Now you can write javascript codes to create 3D scene and 3D elements by configurations.

   let myScene = new Scene3D("#wraper",{
     width:"400px",
     depth:"400px",
     rooms:[
       {
         height:"400px",
         boxes:[
           {
             width:"100px",
             depth:"100px",
             height:"100px",
             left:"150px",
             top:"160px",
             color:"green"
           }
         ]
       }
     ]
   })

Relation Diagram

API

Scene Object

Options

| Name | Type | Default | Description | | :---- | :----: | :----: | ---- | | width | string | "1000px" | The value must contain unit. Percentates are NOT supported| | depth | string | "1000px" | The value must contain unit. Percentates are NOT supported | | offsetVer | string | "-200px" | The initial vertical offset, negative means offset down, positive means offset up. Percentates are NOT supported | | rotateVer | string | "70deg" | The initial vertical rotation of scene, it must be contain unit "deg", negative means reversed | | rotateHor | string | "-40deg" | The initial horizontal rotation of scene, it must be contain unit "deg", negative means reversed | | scaleRat | number | 0.8 | The initial scale of scene | | wheelScale | boolean | true | Allow scale scene by mousewheel | | showGrid | boolean | true | Show grid | | perspective | number | 2000 | Recommend set the value between 800 to 8000, the bigger number the stronger sense of perspective | | dragRotate | boolean | true | Allow rotate scene by mousedrag | | rotateFixed | string | "aroundRestric" | It works only when the dragRotate set true . Optional value: "around" , "aroundRestric" (Around rotation with restrictions. you can just rotate between 0-90 degree on vertical direction. Specifically you can't rotate the scene upside down) "horizontal", "vertical" , "verticalRestric" (Vertical rotation with restrictions)| | rooms | array | [ ] | Room configurations array, be used to create Room |

Methods

Create a Scene object let Scene = new Scene3D("#Scene1",{options...}) , it can use the methods below:

• Scene.showGrid( boolean )

  • Parameters
    boolean {boolean} | Required | True means visible, false means hidden

  • Returns
    Return this current Scene object, which be use for chain calling.

  • Details
    To show or hide the grid of scene.

• Scene.resetScene()

  • Parameters
    -

  • Returns
    Return this current Scene object, which be use for chain calling.

  • Details
    Reset the scene rotation and scale to initial status.

• Scene.buildRoom( options )

  • Parameters
    options {object} | Optional | Options object, refer to Room configurate options

  • Returns
    Return the new Room object

  • Details
    Use the options that passed in to create room manually. If it's empty, will use the default options.

Room Object

Options

| Name | Type | Default | Description | | :---- | :----: | :----: | ---- | | className | string | "" | That will be use for Room dom element's class name after concatenated with "Room3D_room_" . | | width | string | "100%" | The value must contain unit. Percentates are supported | | depth | string | "100%" | The value must contain unit. Percentates are supported | | height | string | "300px" | The value must contain unit. Percentates are NOT supported | | left | string | "auto" | Distance from Room to the left edge of Scene, the value must contain unit. You can also set percentates or "auto" as the value. | | top | string | "auto" | Distance from Room to the back edge of Scene, the value must contain unit. You can also set percentates or "auto" as the value. | | right | string | "auto" | Distance from Room to the right edge of Scene, the value must contain unit. You can also set percentates or "auto" as the value. | | bottom | string | "auto" | Distance from Room to the fore edge of Scene, the value must contain unit. You can also set percentates or "auto" as the value. | | showWall | boolean | true | Show wall | | wallColor | string | "#ddd" | Wall color | | wallOpacity | number | 0.9 | Wall opacity | | wallBackFace | string | "hidden" | Set style rule backface-visibility for wall element, the optional values are "hidden" and "visible" | | showLine | boolean | true | Show corner line | | lineColor | string | "#666" | Corner line color, you can set all the color types which supported by css | | lineOpacity | number | 1 | Corner line opacity | | lineWidth | string | "1px" | Corner line width | | showFloor | boolean | true | Show floor | | floorColor | string | "#444" | Floor color, you can set all the color types which supported by css | | floorOpacity | number | 1 | Floor opacity | | boxes | array | [ ] | Box objects configurations array |

The options top right bottom left are use for locate Room's horizontal position relative to the Scene, you just need to set only one of left and right . And the same as top and bottom .
For the definitions of width, depth and height, you can see the diagram at the top of this document.

Methods

Create and get a Room object by let Room = Scene.buildRoom() . If you want to get a existing Room, you can get it by let Room = Scene.rooms[index] . It can use the methods below:

• Room.showFloor( boolean )

• Room.showWall( boolean )

• Room.showLine( boolean )

  • Parameters
    boolean {boolean} | Required | True means visible, false means hidden

  • Returns
    Return this Room object that be use for chain calling

  • Details
    Be use for show or hide Floor, Walls and Corner Lines.

• Room.backface( value )

  • Parameters
    value {string} | Required | The optional values are "hidden" and "visible" .

  • Returns
    Return this Room object that be use for chain calling.

  • Details
    Be use for set the value of css rule backface-visibility of Wall elements. Specifically, If set "hidden", the side which facing the screen of wall will become transparent. So that the elements in the Room can be seen, and it does not block the mouse events on this elements in the Room.

• Room.buildDoor( wall , doorOptions )

  • Parameters
    wall {string} | Required | The optional values are: "left" , "right" , "fore" and "back" doorOptions {object} | Optional | Door object configurations, refer to the configurations below.

  • Returns
    Return the new Door object

  • Details
    Use the options that passed in to create a Door manually

    Door Options

    | Name | Type | Default | Description | | :---- | :----: | :----: | ---- | | className | string | "" | That will be use for Door dom element's class name after concatenated with "Room3D_door_" | | width | string | "60px" | The value must contain unit, Percentages are supported | | height | string | "120px" | The value must contain unit, Percentages are supported | | left | string | "50%" | Distance from Door to the left edge of Wall, the value must contain unit. Percentages are supported. | | right | string | - | Distance from Door to the right edge of Wall, the value must contain unit. Percentages are supported. Notice that if you want to position the Door with right option, you must set "auto" for the left option| | show | boolean | true | Show Doors, If set to false , you will only see a rectangular hole in the wall. | | type | string | "single left" | Type of Door. Optional values are: "single left" single Door with left shaft, "single right" single Door with right shaft, "double" double Doors. | | openSide | string | "outside" | Direction of Door opening. Optional values are: "outside" and "inside" | | color | string | "#634A42" | Color of Door. | | doorFrameWidth | string | "3px" | The width of Door frame, the value must contain unit, Percentages are NOT supported. | | doorFrameColor | string | "#3B2A24" | Color of Door frame |

    Door Methods

    Use let Door = Room.buildDoor( wall , doorArray )[index] or let Door = Room.walls[wall].doors[index] to get Door object, it can use the methods below:

    • Door.openDoor() Open the door
    • Door.closeDoor() Close the door

• Room.buildBox( options )

  • Parameters
    options {object} | Optional | Options object, refer to Box configurate options

  • Returns
    Return the new Box object

  • Details
    Use the options that passed in to create Box manually. If it's empty, will use the default options.

• Room.destroy()

  • Parameters
    -

  • Returns
    -

  • Details
    Destroy Room object

Box Object

Options

| Name | Type | Default | Description | | :---- | :----: | :----: | ---- | | className | string | "" | That will be use for Box dom element's class name after concatenated with "Box3D_box_" . | | name | string | "" | Box name that will be displayed in Marker content | | width | string | "100%" | The value must contain unit. Percentates are supported | | depth | string | "100%" | The value must contain unit. Percentates are supported | | height | string | "100%" | The value must contain unit. Percentates are supported | | left | string | "auto" | Distance from Box to the left edge of Room, the value must contain unit. You can also set percentates, negatives or "auto" as the value | | top | string | "auto" | Distance from Box to the back edge of Room, the value must contain unit. You can also set percentates, negatives or "auto" as the value | | right | string | "auto" | Distance from Box to the right edge of Room, the value must contain unit. You can also set percentates, negatives or "auto" as the value | | bottom | string | "auto" | Distance from Box to the fore edge of Room, the value must contain unit. You can also set percentates, negatives or "auto" as the value | | offsetZ | string | "0px" | Vertical offset, the value must contain unit. negative means offset down, positive means offset up. Percentates are NOT supported | | rotateX | string | "0deg" | The angle of rotation around X axis, must contain unit "deg" | | rotateY | string | "0deg" | The angle of rotation around Y axis, must contain unit "deg" | | rotateZ | string | "0deg" | The angle of rotation around Z axis, must contain unit "deg" | | opacity | number | 1 | Box opacity | | color | string | "#999" | Box color, you can set all the color types which supported by css | | showLine | boolean | true | Show Box border | | lineColor | string | "#666" | Box border color, you can set all the color types which supported by css | | lineOpacity | number | 1 | Box border opacity | | lineWidth | string | "1px" | Box border width | | marker | object | { } | Marker configurations |

The options top right bottom left are use for locate Box's horizontal position relative to the corresponding Room, you just need to set only one of left and right . And the same as top and bottom .

Methods

Create a Marker object by let Box = Room.buildBox() then get it. If you want to get a existing Marker, you can get it by let Box = Room.boxes[index] . It can use the methods below:

• Box.showLine( boolean )

• Box.showMarker( boolean )

  • Parameters
    boolean {boolean} | Required | Pass in true to show, and false to hide

  • Returns
    Return this Box object, which be use for chain calling

  • Details
    Be use for show or hide the border line and Marker.

• Box.buildMarker( options )

  • Parameters
    options {object} | Optional | Marker configurations

  • Returns
    Return the new Marker

  • Details
    There is a correspooding Marker object is create automatically at each Box object created. So the method updateMarker() actually destroys the original Marker first, and then creates a new Marker with the new configurations. If you just want to update content of Marker, you can use the method updateMarker() of Marker object.

• Box.destroy()

  • Parameters
    -

  • Returns
    -

  • Details
    Destroy Box object

Marker Object

Options

| Name | Type | Default | Description | | :---- | :----: | :----: | ---- | | width | string | "auto" | The value must contain unit. Percentates are NOT supported. | | height | string | "auto" | The value must contain unit. Percentates are NOT supported. | | left | string | expression | Distance from Marker center to the left edge of scene, the value must contain unit. You can also set percentates, negatives or "auto" as the value | | top | string | expression | Distance from Marker center to the back edge of scene, the value must contain unit. You can also set percentates, negatives or "auto" as the value| | right | string | "auto" |Distance from Marker center to the right edge of scene, the value must contain unit. You can also set percentates, negatives or "auto" as the value| | bottom | string | "auto" | Distance from Marker center to the fore edge of scene, the value must contain unit. You can also set percentates, negatives or "auto" as the value| | offsetZ | string | expression | Suspension height of Marker, The value must contain unit. Percentage and "auto" are NOT supported. | | show | boolean | true | Show Marker | | lineColor | string | "#666" | Marker connection line color | | lineWidth | string | "1px" | Marker connection line color width | | fontSize | string | "14px" | Marker content font size | | fontColor | string | "#ffffff" | Marker content font color | | backgroundColor | string | "rgba(36, 212, 174, 0.9)" | Background color of Marker, since not provide opacity option with Marker object configuration, If you need translucent effect, you can set the color with alpha channel | | content | string | "<h4>{{params.title}}</h4>" | Marker content template, which can use the form {{params.propertyName}} as a placeholder to receive arguments passed in by property "params". You can edit richer templates using HTML strings. | | params | object |{title:box.options.name || "Marker"}| Save the parameters that need to be passed, It be use for parse Marker content template. There is a property named "title" by default, which takes name option of the box which bound this Marker as value |

Since in DOM structure the Marker elements are created directly in scene element, so their top right bottom left are positioned relative to the scene element. You just set only one between left and right . And the same as top and bottom. And since the default value of left and top is an expression that makes the Marker be created right above the box. So if you want to use right and bottom for positioning, you must set the corresponding left and top values to auto .

Methods

Create and get a Marker object by let Marker = Box.buildMarker() . If you want to get a existing Marker, you can get it by let Marker = Box.marker . It can use the methods below:

• Marker.updateMarker( params )

  • Parameters
    params {object} | Required | The params object must contain properties that match the Marker content template and the values that need to be updated.

  • Returns
    Return this Marker object

  • Details
    Be use for update Marker content template.

• Marker.destroy()

  • Parameters
    -

  • Returns
    -

  • Details
    Destroy Marker object

Notice

1. All the options of length and distance must set the same unit, "px" is recommended. Otherwise there will be some bugs due to the unit conversion.

2. If two immediately adjacent rooms that need to create doors on adjacent walls, you need to use buildDoor() method for the corresponding wall objects of both rooms on the symmetrical positions while set one of the doors invisable, then you can achieve it.

3. You can also add css rule background-image for various elements in the scene, simulate mapping effect to achieve richer scene

NPM Package Versions & Updates

• 1.0.0 Release date: 2022/6/8
  • 1.0.1 & 1.0.2 Release date：2022/6/8
    • Modify readme.md
  • 1.1.0 Release date: 2022/6/15
    • Marker object add property scene , its value points to the current Scene objec.
    • Box object add method .destroy()
    • Room object add method .destroy()

Others