HART Estate Widget

The package is designed to present 2D and 3D floor plans generated by the AI service getfloorplan.com.

Table of Contents

• Quick Start
• • Example index.html
• • Example index.js
• • Example index.sass
• Docs
• • Parameters
• • Types of Elements
• • REST API Object
• Versioning
• Copyright and License

Quick Start

As a result, you will receive a website that can display various floor plans.

• Download NodeJS 18+;
• Create a new project;
• Download the required packages

npm install hart-estate-widget@2.7.5
npm install sass@1.62.1
npm install parcel@2.8.3
npm install @parcel/transformer-sass@2.8.3

• Example structure of project:

.
├── package-lock.json
├── package.json
├── src
│   ├── assets
│   │   ├── img
│   │   │   ├── logo.png
│   │   └── sass
│   │       └── index.sass
│   ├── index.html        
│   └── js
└       └── index.js      

• Copy-paste sample assets from below.
• Run with rm -rf dist && npx parcel ./src/index.html
• Open browser at:
  https://localhost:1234/?id=228ba1dd-64d3-4d33-bcd7-b4c670bed40e

> The query id parameter accepts the UUID4 received from getfloorplan.com
> You can use these UUID4 for test purposes:
> - Scandy style: 228ba1dd-64d3-4d33-bcd7-b4c670bed40e > - Boho style: f9032373-bb2c-416e-b0ab-20b8fd24d482 > - England style: b21871a2-2d5b-4beb-817b-ed750eebab9a > - Neutral style: e8553134-0457-488c-8d3e-611b0e2be4d4 > - Modern style: 73b833c3-072a-4ac2-9f5d-7f7ac3d1fc9c

HTML

Insert the example into a file src/index.html

  
    
    
    <title>katmosfera</title>
    
    
  

  
    <section class="widget-section">
      <div id="widget" class="widget"></div>  
    </section>
  

JavaScript

Insert the example into a file src/js/index.js

import { ApiStore, Widget, rotationModes } from 'hart-estate-widget';
import '../assets/sass/index.sass'; // style
import logo from '../assets/img/logo.png'; // logo

const WIDGET_API_URL = 'https://backend.estate.hart-digital.com';

const createWidget = async (logoUrl) => {
  const widgetApiHandler = new ApiStore(WIDGET_API_URL)

  const { searchParams } = new URL(document.location);
  const planId = searchParams.get("id");

  const planData = await widgetApiHandler.loadWidgetData(planId);
  const options = { // the parameters you need that are described below in "Parameters"
    ...planData.parsed,
    API_URL: WIDGET_API_URL,
    rotationMode: rotationModes.DEFAULT,
    tabs: ['panorama', 'rotation'],
    locale: 'en',
    logoUrl,
    logo,
  }

  new Widget('#widget', options); // must match the element id
}

createWidget('https://yoursite/'); // create a widget

SASS

Insert the example into a file src/sass/index.sass

*, *:before, *:after
  -webkit-font-smoothing: antialiased
  -moz-osx-font-smoothing: grayscale
  font-family: 'Proxima Nova'
  text-decoration: none
  font-weight: 400
  color: #fff
  outline: none
  padding: 0
  margin: 0
  box-sizing: border-box
  -webkit-box-sizing: border-box

body
  width: 100%
  height: 100%
  overflow: hidden

.widget-section
  width: 100%
  height: 100%
  .widget
    width: 100%
    height: 100%

Docs

Parameters:

Here you can see a list of accessible options and examples of usage. There are accessible values for each option below in the block "Types of Elements".

{
  // elements  
  tabs: ['rotation', 'panorama'], // included elements

  // logo
  logo: '', // path/link to the logo
  logoUrl: '', // link opened when logo is clicked

  // localization
  // accessible languages are in "Types of Elements"
  locale: 'en', // ISO 639 language code

  // width/height
  width: 1920,
  height: 1080,
  resizable: true, // automatically resize the widget to the size of the container when the window is resized

  // values
  rotationMode: '', // mode of operation for plan images
  panoramaFov: 75, // camera field of view angle for panoramic tour
  preloadPerPanoramaCount: 3, // the number of panoramas loaded next to the current one to optimize transitions
  enablePreloadMasks: true, // also preload depth textures
  forcePreloadNonCached: true, // give preloading a higher priority for unloaded panoramas than by distance from the current one
  forceTopViewOnMap: true, // show top view map instead of standard by default
  topViewResolutionUpscale: 2, // upscale top view map by coef (200px * 2 = 400px)
  enableCameraTransitionBetweenPanoramas: true, // enable/disable camera rotation transition between panoramas (if CameraPoint.Rotation.Yaw is defined in JSON)
  enableCameraRotationBetweenPanoramas: true, // enable/disable camera rotation between panoramas (if CameraPoint.Rotation.Yaw is defined in JSON)
  instructionVisible: true, // enable/disable modal of instruction in 3D tour
  autoRotate: false, // enable/disable auto rotation in 3D tour
  primaryCameraPointId: null, // primary camera point ID for panorama tour
  floors: [ // array of floors, contains 360° images and panoramic tour data
    {
      original_plan_img: '',  // path to the original plan image (required for panoramic tour)
      styled_plan_img: '',  // path to the styled plan image (required for panoramic tour)
      top_view_img: '',  // path to the top view image
      panorama: '',  // type of panorama and paths to 360° images
      rotate: '',  // type of images and paths to circular view images (order is mandatory)
    }
  ],

  // colors
  colors: {
    main: '#HEX', // main color of buttons, elements
    mainText: '#HEX', // text color for buttons, elements contrasting with the main color
  },

  // copyRight: all text in widget
  dictionaryOverrides: {
    "create-points": "Create a point", // text for create point
    "delete-points": "Remove point", // text for delete point
    "research-plan": "Research plan", // text for research plan
    "rotate-plan": "Rotate plan", // text for rotate plan
    "ok": "Ok", // button text
    "made-by-link": "https://getfloorplan.com/", // watermark link
    "made-by-text": "getfloorplan.com", // watermark text
    "instructions-hint-text": "", // additional text on the bottom of instruction modal
    "floor": "$0 floor" // floor text
  },

  API_URL: '', // API URL

  // branding.
  branding: {
    company_url: '', // link opened when logo is clicked (higher priority than logoUrl)
    company_name: '', // watermark text (higher priority than dictionaryOverrides['made-by-text'])
    widget_language: 'en', // ISO 639 language code
    logo_path: '', // path to logo
    
  // panorama icons
  panoramaIcons: {
    spot: 'URL', // icon for camera points in one room
    door: 'URL' // icon for door
  },

  // scales
  scales: ['x05', 'x1'],
    
  // integrations
  integrations: {
    sentry: {
      dsn: '',
      // Other sentry params
    },
  },

  movementType: 'interroom', // allows movement only within a room or between rooms

  defaultLinkOptions: {
    hasRealSize: false, // enable real size icons in classic navigation mode
    realSize: 300, // real size
    realSizeMobileScale: 1, // mobile scale factor in real size
    realSizeMinDistance: 100, // minimal distance to scale down real size icon
    realSizeDistanceMinScale: 0.1, // minimal scale for minimal distance scale down
    hoverScale: 1.2 // hover scale factor
  },
}

Types of elements

tabs: [
  'rotation', // circular view images (order is mandatory)
  'panorama', // 360° images
],
rotationMode: [
  rotationModes.DEFAULT, // top view mode (multiple perspectives) and stylized plan view
  rotationModes.THREESIXTY, // image scrolling mode for circular view
],
floors[0].rotate.type: [
  'top_down', // full model
  'middle_cut', // model with cut in the middle
],
floors[0].panorama.type: [
  'sphere', // 360° panorama
  'cube', // panorama with 6 images (top, down, left, right, front, back)
],
locale: [
  'ru', // Russian language
  'en', // English language
  'es', // Spanish language
  'de', // German language
  'ja', // Japanese language
],
scales: [
  'x1',
  'x2',
  'x05'
],

Widget object from the REST API

JSON object returned from backend

name: "", // CRM plan ID (only for CRM API)
original_plan_img: "", // deprecated, path to the original plan image
original_plans_img: [ // array of paths to the original plan images
  ""
], 
styled_plan_img: "", // path to the styled plan image
top_view_img: "", // path to the top view image
json: { // JSON with data for 3D tour
  type: "furniture", // type of JSON (furniture, neural)
  value: "" // path to JSON
},
panorama: { // type of panorama and paths to 360° images
  type: "sphere", // 360° panorama or 'cube' for 6 images
  items: {
    [
      camera_id: "" // camera ID for panorama
      room_id: "" // room ID for panorama  
      images: [ // array of paths to 360° sphere and sides of the cube if type is cube
        sphere: "",
        front: null,
        back: null,
        left: null,
        right: null,
        top: null,
        bottom: null,
        scene_depth: "", // path to EXR file for depth map if available
      ]
    }
  ]
},
rotate: { // type of images and paths to circular view images
  type: "top_down", // full model or model with cut in the middle ('middle_cut')
  items: [ // array of paths to circular view images
    ""
  ]
}

Versioning

For the latest stable version refer to the latest up-to-date version in Quick Start

This project is maintained under the Semantic Versioning guidelines.

However, some versions are being developed for specific clients. We do not recommend using them, as changes in these versions are not documented and may affect your functionality.

Copyright and license

The project code is licensed under the GPLv3 license.

Project code and documentation copyright hart-digital.com.
All renders of floor plans copyright getfloorplan.com.