v3.0 Specification


While we're still supporting XML, JSON is going to become our primary
format soon. Our editor API also exposes the state of currently edited
floorplan, so this documentation will help those who need to use it for
various purposes at runtime.

A good way to explore the format

You can examine the state of currently edited floorplan
via the editor API property called state. The API is available as
window.api. You can start a new project, draw something in the
editor and check the state in browser's developer console. Drawing a
single wall and checking api.state.walls[0] is a good start. Also,
note the section about runtime format vs
persistent format.

The format

Using Typescript notation

In order to describe the format, we decided to use
Typescript notation. This will
allow to show what properties each object has and of what data
type. Furthermore, this will allow declaring nested objects and
frequently used sets of properties as separate interfaces with their
own names, making it easier to comprehend.

Runtime vs persistent

At runtime, a floorplan is represented by one big javascript
object. That's what you'll get from editor's API. When a floorplan is
saved or when it's exported as JSON, we use slightly different format
we call persistent. That's the format we describe in this
document. It doesn't contain some of runtime properties, and the one
called asset is replaced by refid. References to assets are
resolved when the plan is loaded, and the rest of runtime properties are
derived from those stored in the persistent format.


When you start working on a plan in Flooplanner, you start with a
project. A project has one or more floors.

interface Project {
    id: number;
    name: string;
    public: boolean;
    settings?: ProjectSettings;
    floors: Floor[];

Project settings

One important attribute of a project is settings. It
contains a lot of configuration options specific for given project.

interface ProjectSettings {
    wallHeight: number;
    wallSectionHeight: number;
    wallThickness: number;
    wallOuterThickness: number;
    useMetric: boolean;
    showGrid: boolean;
    showDims: boolean;
    showShortDims: boolean;
    showAreaDims: boolean;
    generateOuterDimension: boolean;
    showDropShadows: boolean;
    showObjects: boolean;
    showFixtures: boolean;
    showItemOutline: boolean;
    showObjectColour: boolean;
    showStructuralColour: boolean;
    showFloorsBelow: boolean;
    showObjects3d: boolean;
    showObjectMono: boolean;
    showLights: boolean;
    useSection3D: boolean;
    showLabels: boolean;
    areaLabelOutline: boolean;
    areaLabelLetterSpacing: number;
    dimLineLabelHorizontal: boolean;
    exportLabels3D: boolean;
    showShadows3D: boolean;
    exportOrtho3D: boolean;
    visuals: "ALL" | "BW" | "BWC";
    showTexts: boolean;
    arrowHeadType: "arrow-stop" | "stop" | "reverse-arrow-stop" | "arrow";
    northArrowRotation: number;
    northArrowKind: number;
    blueprintMode: boolean;
    dimLineFont: string;
    hideItemsAboveHeight: number;
    hideItemsAbove: boolean;


A floor is a container for designs, which are actual
Floorplans. It's also used as a container for cameras, which are
shared between desings on the same floor.

interface Floor {
    id: number;
    name: string;
    level: number;
    height: number; // default wall height
    designs: Floorplan[];
    cameras: Camera[];
    drawing?: Drawing


Another important attribute a floor may contain is called
drawing. It is an image a user can upload and then draw the plan on
top of it. Useful for tracing scans of paper floorplans.

interface Drawing {
    x: number;				// position of the drawing on the plan
    y: number;
    width: number;			// size of the drawing in cm
    height: number;
    visible: boolean;
    url: string;
    rotation: number;		// in degrees
    alpha: number;
    depth?: "LOW" | "HIGH"	// drawn above or below the floorplan


Cameras are used as viewpoints to create 3D renders of floorplans.

interface Camera {
    id: number;
    name: string;
    type_name: 'orbital' | 'walkthrough';
    x: number;		// position
    y: number;
    z: number;
    ux: number;		// direction of normals
    uy: number;
    uz: number;
    dx: number;		// direction of camera
    dy: number;
    dz: number;
    fov: number;	// field of view, in degrees
    lightSettings: CameraLightSettings;
    background_image: PresetSky | UserDefinedSky | {}

Camera light settings

Each camera has light environment settings, which describe the
position of the sun on the sky (if it's a day) as well as light

interface CameraLightSettings {
    altitude: number;
    azimuth: number;
    day: boolean;
    intensity: number;
    profile: boolean;

Camera background image

A camera may have a background image. Either a preset one or an image uploaded
by the user.

interface PresetSky {
    sky_id: number;
    url: string;
    type_name: 'sphere'

interface UserDefinedSky {
    url: string;
    type_name: 'plane'


Floorplan is the core object in Floorplanner. It describes things like
walls, doors, windows and furniture items.

interface Floorplan {
    id: number;
    name: string;
    walls: Wall[];
    areas: Area[];
    surfaces: Surface[];
    dimensions: Dimension[];
    items: Item[];
    labels: Label[];
    lines: Line[];
    settings?: DesignSettings;

Before we go on describing all these types, let's introduce a few
basic ones used in multiple places in a floorplan.

We use centimeters for coordinates. The X axis is directed from left
to right and the Y axis - from the top to the bottom of the screen.

interface Point {
    x: number;
    y: number;

Not all the floorplan coordinates are 3D. We use the third dimension
when needed.

interface Point3D extends Point {
    z: number;

For colors, we use a string starting with the # symbol and having
six hexadecimal digits.

type Color = string

All the lines in a Floorplan have two endpoints we refer to as a and
b. When the direction is important, we say that the line goes from
a to b

interface GenericLine {
    a: Point;
    b: Point;


A wall is defined by the coordinates of the endpoints of its centerline. Curved walls also have the
control point. Wall balance defines how much of wall thickness goes to
the left and to the right of the centerline.

Terms left and right are also used when decorating a wall and, at
runtime, for holding data about wall's outline. Imagine standing at
point a and looking at point b. The left side then will be to the
left and the right side - to the right.

interface Wall extends GenericLine {
    c?: Point | null; // control point for curved walls (quadratic bezier)
    az: Endpoint3D;
    bz: Endpoint3D;
    thickness: number; // in cm
    balance: number; // 0..1
    openings: Opening[];
    decor: WallDecor;

Note that each endpoint also has two z-coordinates: the lower and the higher.

interface Endpoint3D {
    z: number; // elevation of the bottom of the wall's endpoint
    h: number; // elevation of the top of the wall's endpoint


A wall also serves as a container for openings - doors and
windows. Type of the door or window is defined by the referenced
asset. The t parameter describes the horizontal position of the opening relative to wall's endpoints. When it's 0, the middle of the opening is over the endpoint a, when 1 - over the endpoint b.

interface GenericOpening {
    refid: string;
    width: number;
    z: number; // elevation
    z_height: number; // height
    t: number; // 0..1 - relative position of the opening on the wall
    frameColor?: Color;

interface Door extends GenericOpening {
    type: 'door';
    mirrored: [0 | 1, 0 | 1]; // vertical and horizontal flipping
    doorColor?: Color;

interface Window extends GenericOpening {
    type: 'window'


Finally, each side of a wall may be independently decorated with
a color, a material or an image uploaded by the user.

interface WallDecor {
    left: WallSideDecor;
    right: WallSideDecor;

type WallSideDecor = null | WallSideWithColor | WallSideWithMaterial | WallSideWithTexture;

interface WallSideWithColor {
    color: Color;

interface WallSideWithMaterial {
    refid: string;

interface WallSideWithTexture {
    texture: WallTexture;

interface WallTexture {
    src: string;	// url to the image
    fit: 'free' | 'no-stretch' | 'fill' | 'contain' | 'tile-horizontally' | 'tile-vertically' | 'tile-both';
    tlx: number;	// top left corner coordinates on the wall side
    tly: number;
    brx: number;	// bottom right corner coordinates on the wall side
    bry: number;


Areas in Floorplanner are generated automatically, whenever plan walls
make closed spaces. Quite often areas have a texture applied to them,
hence a set of texture-specific properties.

interface TextureProps {
    rotation?: number; // rotation of the texture, in degrees, if a texture applied and rotation is not zero
    tx?: number; // horizontal texture offset, in pixels, if a texture is applied and if the offset is not zero
    ty?: number; // vertical texture offset, in pixels, if a texture is applied and if the offset is not zero
    sx?: number; // horizontal texture scale, in %, if a texture is applied and scale is not 100%
    sy?: number; // vertical texture scale, in %, if a texture is applied and scale is not 100%

Another set of area attributes is related to its purpose - an area may
have a name, either a standard one representing one of room types, or
a custom one. The same set of attributes is also used by surfaces.

interface AreaProps extends TextureProps {
    refid?: string;
    color: Color;
    showSurfaceArea?: boolean;
    showAreaLabel: boolean;

    name?: string;			// standard name, derived from the applied roomtype
    customName?: string;	// custom name, if supplied
    role?: number;			// roomtype identifier, if a roomtype is applied
    name_x?: number;		// area label position, horizontal offset from the area polygon centroid, in metres
    name_y?: number;		// area label position, vertical offset from the area polygon centroid, in metres

Finally, the shape of the area is represented by an array of 2D
points. Note that these points are located on edges of walls (not
on their center lines).

interface Area extends AreaProps {
    poly: Point[];
    ceiling?: Ceiling;
    roomstyle_id?: string;  // if a roomstyle was chosen for this area


Surfaces are quite similar to areas and share many attributes. They
are used for drawing special purpose stuctures such as roofs or
cutouts, as well area-like structures without walls. For instance,
a patch of grass in the garden. Unlike areas, surfaces are drawn
point-by-point by the user.

interface Surface extends AreaProps {
    poly: SurfacePoint[];
    isRoof?: boolean;
    isCutout?: boolean;
    transparency?: number;

Sufaces can also be elevated, therefore their points have the z
coordinate. Curves for surfaces are also modelled differently, areas
use approximation with straight segments for curved walls.

interface Point3D extends Point {
    z: number;

interface BezierPoint extends Point {
    cx: number;
    cy: number;
    cz?: number;

type SurfacePoint = Point3D | BezierPoint;

Dimension line

Dimension line is one of the simplest types in the Floorplan. It's
label shows the length of the corresponding line.

interface Dimension extends GenericLine {
    type: 'custom_dimension';


Furniture items, structural elements, icons and symbols - they all are
item objects in the floorplan. Exact type of the item is defined by
its asset, referenced by the refid attribute.

interface Item extends Point3D {
    refid: string;
    width: number;
    height: number;
    z_height: number;
    rotation: number;
    mirrored?: [0 | 1, 0];
    light?: Light;
    materials?: SmartMaterials;


Some of items represent light sources. In such case they also have the
light attribute containing the following data structure.

interface Light {
    on: boolean;  // a light can be switched off
    color: Color;
    watt: number; // light intensity, integer in range 0..200

Smart items

Some of items are so-called smart items. These may have some of
their materials swapped, resulting in multiple variations with the
same geometry. Think of a table with a set of material options for its
top and legs.

interface SmartMaterials {
    [materialName: string]: number;

The list of material names and available options is defined by the
asset for given item.


Labels represent formatted pieces of text in the floorplan.

interface Label extends Point {
    text: string;
    fontFamily: string;
    fontSize: number;			// in px
    letterSpacing: number;		// in %
    fontColor: Color;
    backgroundColor: Color;
    backgroundAlpha?: number;	// in %
    align: 'left' | 'center' | 'right';
    rotation: number;
    outline?: boolean;
    bold?: boolean;
    italic?: boolean;


Lines are usually added to the floorplan for the notation purpose.

interface Line extends GenericLine {
    type: 'solid_line' | 'dashed_line' | 'dotted_line' | 'dashdotted_line';
    color: Color;
    thickness: number; // in pixels

Design settings

Finally, there are several settings stored in each floorplan. This
means that they can vary from one plan to another, even on the same

interface DesignSettings {
    engineAutoThickness: boolean;		// no longer used, always false
    engineAutoDims: boolean;			// automatically generate dimension lines
    areaLabelMultiplier: number;		// text scale factor for area labels
    scaleMultiplierDimensions: number;	// text scale factor for dimension text
    scaleMultiplierComments: number;	// text scale factor for regular labels
    showCeilings3D: boolean;
    minWallLength?: number;				// defaults to 4; walls shorter than this size are discarded