Furnishing AI

Introduction

The Furnishing AI (or Homestaging AI) allows you to automatically create furnishings for residential interior spaces. Available as a service via API:

TIP

Test the API live in our interactive HomeStaging AI playground.

Furnish a Room

The example below lists all fields that could be included in the call request. To learn more about an individual field or its type scroll down to find it in the tables below. Dimensions and positions in the coordinate system are defined in meters, angles in arc degrees.

Note that a template describes a variable set of furniture, in a similar way as giving a list of furniture, using predefined furniture types and counts, and choosing from a default set of shapes. If both template and furniture are present in a request, they will be added together.

{
    "jsonrpc": "2.0",
    "method": "HomeStaging.furnish",
    // UUID of the request
    "id": "a2716497-3999-4630-8674-002d484429f0",
    "params": {
        // A Template is a predefined list of furniture which will
        // be added to the inventory of the algorithm.
        "template":{
            "name": "living",
            // To exclude certain types of furniture from this template:
            "exclude": ["sideboard"]
        },
        // A flexible list of furniture items to be added to the 
        // furniture inventory, in addition to the template.
        // Type, shape, count and placement can be specified.
        // To replace something from a template with fixed position: 
        // exclude it in the template and add it here
        "furniture": [
            // Add one dining table:
            { "type": "dining_table" },
            // And a desired amount of chairs:
            // (Resulting count might be less in favour of meaningful furnishings)
            { "type": "dining_chair", "targetCount": 4 },
            // Also add a table with a specific shape:
            {
                "type": "task_table",
                "shape": { "type": "cylinder", "r": 2.2, "h": 0.6 }
            },
            // … and a sideboard on a specific position [X,Y,Z], rotated by 90°
            {
                "type": "sideboard",
                "position": [ 2.2, 0.6, 0.4 ],
                "rotation": 90,
                "shape": { "type": "box", "a": 2.2, "b": 0.4, "h": 0.6 }
            }
        ],
        // Now let's describe the room to be furnished:
        "room": {
            "boundary": {
                "shape": {
                    "type": "polygon-extrusion",
                    // A closed 2D polygon on the XZ plane (floor)
                    "points": [[-2,2], [2,2], [2,-2], [-1.5,-2], [-2,-1]],
                    // Room height:
                    "h": 2.7
                },
                "openings": [
                    // Openings along the boundary polygon
                    { "type": "window", "pos": 1, "y": 0.6, "l": 1.6, "h": 1.6 },
                    { "type": "door", "pos": 4.2, "y": 0, "l": 0.8, "h": 2.1 }
                ]
            }
        },
        // You can tell the AI how many proposals it should try to generate:
        // (Fewer proposals might be little faster, but the calculation
        // time is not linearly proportional)
        "maxResults": 10
    }
}

Parameters

Validation

We provide JSON schema definitions for parameter validation.

Top Level

Conceptually there is two key pieces of information the AI needs to know:

  • The type and the amount of furniture you want to place in a room.
  • What the room does look like.

The furniture items can be specified as a list with the "furniture" parameter or by using a furniture "template". Templates are simply predefined lists of furniture items for your convenience. You can use either one of those parameters separately or both in combination.

Property Type Required Description
"room" object required A room description defining the geometry and semantics (i.e. windows, doors) of a room.
"template" object optional A furniture template object to be included in the furnishing result.
"furniture" array optional A list of furniture items to be included cumulatively in the furnishing result.
"maxResults" number optional Maximum number of results that shall be computed (1 - 20). Defaults to 10.

Furniture Template

A predefined list of furniture items. Can be specified in the "template" top level parameter.

Property Type Required Description
"name" string required The name of a furniture template. Available templates are listed bellow this table.
"exclude" array required A list of furniture types to be excluded from this template.

Example:

Let's say you want all the furniture items from the "living" template, except the sofa:

{
    "name": "living",
    "exclude": ["sofa"]
}
Available Templates:
  • bedroom
  • dining
  • dining_living
  • home_office
  • living

Furniture Item

Describes a single piece of furniture as an object in the "furniture" list top level parameter.

Property Type Required Description
"type" string required Furniture type name. There is a list of available furniture types below this table.
"targetCount" number optional The target amount of this furniture type to be included in a furnishing result. Must be a multiple of 1. Default value is 1. The item count in the result might be lower in favour of meaningful furnishings.
"position" array optional [X,Y,Z] Position of the shape origin point in meter units. Omit this value in order to receive a position proposal from the furnishing AI. This parameter is only available for furniture types: armchair, bed, dining_table, sofa, shelf, sideboard, task_table, wardrobe
"rotation" number optional Rotation in arc degree units. This value will be set by the furnishing AI if the position value is omitted.
"shape" object optional A shape describing the geometrical external boundary of a furniture item. Omit this value to receive a shape proposal from the furnishing AI. Allowed shape types for furniture items are: "box", "cylinder", "l-extrusion". Support for additional shapes like "polygons-extrusion" might be added in the future.
"shapes" array optional A list of possible shape objects to choose from.

Example:

{
    "type": "sideboard",
    "position": [ 2.2, 0.6, 0.4 ],
    "rotation": 90,
    "shape": { 
        "type": "box", 
        "a": 2.2, 
        "b": 0.4, 
        "h": 0.6, 
        "wallAlignment": "x-axis",
        "customData": {
            "myId": 123,
            "properties": {
                "color": "blue"
            }
        }
    }
}
Available Furniture Types:
  • armchair
  • bed
  • bed_lamp
  • carpet
  • coffee_table
  • dining_chair
  • dining_table
  • drawer_unit
  • free_standing_lamp
  • nightstand
  • pendant_lamp
  • shelf
  • sideboard
  • sofa
  • task_chair
  • task_table
  • tv
  • wardrobe

Room

Property Type Required Description
"boundary" object required A room boundary object.

Room Boundary

Describes the outer boundary of a room. The boundary itself is considered to be a wall unless stated otherwise in the "openings" property.

Property Type Required Description
"shape" array required A polygon-extrusion shape describing the room boundary.
"openings" array optional Describes openings in the room polygon boundaries.

Room Boundary Openings

The AI takes room boundary openings into account to preserve circulation areas and to avoid placing furniture items in front of doors or windows. Dimensions are in meter units and relative to the room polygon boundary.

Property Type Required Description
"type" string required Can be one of "window", "door", "gap"
"pos" number required Position sliding along the room boundary polygon, starting at the first point.
"l" number required Length of the opening along the polygon boundary.
"y" number required Vertical position of the opening relative to the floor.
"h" number required Height of the opening.
"circulationWidth" number optional Width of space to be left empty next to the opening (except for carpets and furniture fitting under the window). Defaults to 0.5m for windows and gaps, 0.9m for doors. Note that wall-aligned furniture will not be placed next to doors and gaps, even if the circulationWidth is set to 0.

Shape

A placeholder geometry describing the outer boundary of a furniture item or a room. All units are in meters and arc degrees.

Box Shape
Property Type Required Description
"type" string required = "box"
"a" number required Rectangle size along the X axis in meter units.
"b" number required Rectangle size along the Z axis in meter units.
"h" number required Extrusion height along the Y axis in meter units.
"wallAlignment" string optional Whether and how the shape should be aligned to a wall. Possible values: "none", "x-axis", "z-axis", "corner"
"customData" object optional A pass-through object which will be ignored by the AI and reappears in the result. You could for example store your own furniture ID here in order to correlate furniture items from your request to the ones in the result.
Cylinder Shape
Property Type Required Description
"type" string required = "cylinder"
"r" number required Radius in meter units.
"h" number required Extrusion height along the Y axis in meter units.
"customData" object optional A pass-through object which will be ignored by the AI and reappears in the result. You could for example store your own furniture ID here in order to correlate furniture items from your request to the ones in the result.
L-Extrusion Shape
Property Type Required Description
"type" string required = "l-extrusion"
"a" number required Bounding box size along the X axis in meter units.
"b" number required Bounding box size along the Z axis in meter units.
"c" number required Object depth along the X axis in meter units.
"d" number required Object depth along the Z axis in meter units.
"h" number required Extrusion height along the Y axis in meter units.
"wallAlignment" string optional Whether and how the shape should be aligned to a wall. Possible values: "none", "x-axis", "z-axis", "corner"
"customData" object optional A pass-through object which will be ignored by the AI and reappears in the result. You could for example store your own furniture ID here in order to correlate furniture items from your request to the ones in the result.
Polygon-Extrusion Shape
Property Type Required Description
"type" string required = "polygon-extrusion"
"points" array required A closed 2D polygon on the XZ plane (floor) describing. Format: [ [x1,z1], [x2,z2], [x3,z3], … ]
"h" number required Extrusion height along the Y axis in meter units.
"customData" object optional A pass-through object which will be ignored by the AI and reappears in the result. You could for example store your own furniture ID here in order to correlate furniture items from your request to the ones in the result.

Shape Axes in Relation to Furniture Types

Coordinate System

A three-dimensional, right-handed coordinate system with the Y axis pointing up. Positive rotations are in clockwise direction. Coordinate units are meters.

Generate Groups

This API allows to generate furniture groups for a given group type and bounding box.

The example below lists all fields that could be included in the call request. To learn more about an individual field or its type scroll down to find it in the tables below. Dimensions and positions in the coordinate system are defined in meters, angles in arc degrees.

Note that a groupType describes a variable set of furniture, in a similar way as giving a list of furniture, using predefined furniture types and counts, and choosing from a default set of shapes. If specific furniture items are present in a request, they will overwrite the group template.

{
    "jsonrpc": "2.0",
    "method": "HomeStaging.generateGroups",
    // UUID of the request
    "id": "cdd5cb62-20e1-42c2-ac21-c5b451d0cbbc",
    "params": {
        // The groupType specifies the furniture types that can be combined to create the group.
        "groupType": "dining",
        // A flexible list of furniture items to be added to the groups.
        // These furniture items will replace the item of their type 
        // in the group template.
        // Type, shape and count can be specified.
        "furniture": [
            // And a desired amount of chairs:
            // (Resulting count might be less in favour of meaningful furnishings)
            { "type": "dining_chair", "targetCount": 4 },
            // Alternatively add a table with a list of shapes:
            {
                "type": "dining_table",
                "shapes": [
                    { "type": "cylinder", "r": 0.9, "h": 0.6,
                      "customData": {
                          "color": "white"
                      }
                    },
                    { "type": "cylinder", "r": 0.9, "h": 0.6,
                      "customData": {
                          "color": "brown"
                      }
                    },
                    { "type": "box", "a": 2.2, "b": 0.9, "h": 0.6 }
                ]
            }
        ],
        // Now let's describe the area:
        "boundingBox": {
            "x": 3,
            "y": 2.4,
            "z": 3
        },
        // You can tell the API how many proposals it should try to generate:
        // (Fewer proposals might be little faster, but the calculation
        // time is not linearly proportional)
        "maxResults": 10
    }
}

Parameters

Top Level

Property Type Required Description
"groupType" string required Type of the furniture group to be generated, see the available group types below. Every group type has a default list of furniture items with shapes to choose from.
"furniture" array optional A list of furniture items to be added to the groups. These furniture items will replace the item of their type in the group template, but furniture items from the group template that aren't in the given furniture, are added to the inventory with a default target count (you can exclude a furniture type by adding it with "targetCount": 0). Furniture items that do not match the groupType will be ignored. Placement of the furniture items can not be specified.
"boundingBox" array required The bounding box the groups should fit into.
"maxResults" number optional Maximum number of results that shall be computed (1 - 40). Defaults to 10.
"fallBackToDefaults" boolean optional Set to true to fall back to default shapes for furniture types for which no shapes are specified and also to try to generate groups again with default shapes if no groups are found. Default is false.
Available Group Types

These are the available groups and the types of furniture they might contain:

  • dining: dining_table, dining_chair, pendant_lamp, carpet
  • relaxing: sofa, armchair, coffee_table, free_standing_lamp, carpet
  • sleeping: bed, nightstand, bed_lamp, carpet
  • storing: shelf, sideboard
  • working: task_table, task_chair, drawer_unit

Bounding Box

Describes the bounding box the group should fit into. Results will be sorted by closest size. If the bounding box is too small for a group type there will be no result. If a specified list of furniture items does not fit the bounding box - that furniture item will be ignored to produce a result.

Property Type Required Description
"x" number required Dimension in along x-axis
"y" number required Dimension in along y-axis
"z" number required Dimension in along z-axis

Result Response

Example

For both the HomeStaging.furnish and HomeStaging.generateGroups methods, the structure of the result is as follows (the order of the key-value pairs can be different).

{
    "jsonrpc": "2.0",
    // UUID correlating to the one from the call request
    "id": "a2716497-3999-4630-8674-002d484429f0",
    "result": {
        "furnishings": [
            {
                // indicates how much in the room is occupied by furniture items
                // 0 = no area occupied (i.e. only pictures have been placed on walls)
                // 1 = area is occupied completely
                "density": 0.8,
                // A randomly assigned UUID for later feedback
                "id": "furnishing-uuid-for-feedback",
                // A list of placed furniture items
                "furniture": [
                    {
                        "type": "dining_table",
                        "position": [ 0.3, 0, 2.2 ],
                        "rotation": 0,
                        "shape": { "type": "cylinder", "r": 0.75, "h": 0.72 ,
                            "customData": {
                                "color": "white"
                            }
                        },
                        "groupId": "a3628acb-ad8b-470f-a63c-60e08872b82e"
                    },
                    {
                        "type": "sideboard",
                        "position": [ 2, 0, 1.2 ],
                        "rotation": 90,
                        "shape": { "type": "box", "a": 2, "b": 0.6, "h": 0.4 },
                        "groupId": "0a25dcd2-0201-44b0-b184-ee94c859b166"
                    }
                ]
            }
        ],
        "warnings": [
            // suboptimal, non-breaking conditions
            {
                "code": "warning_5",
                "message": "Fixed furniture items overlap."
            }
        ]
    }
}

Result warnings

Provides information on suboptimal, non-breaking conditions, not preventing the AI from generating furnishing results or furniture groups. Possible warnings are:

Code Method Message
warning_1 HomeStaging.furnish, HomeStaging.generateGroups No furnishings found.
warning_2 HomeStaging.furnish, HomeStaging.generateGroups Found only <n> furnishings.
warning_3 HomeStaging.furnish Not enough walls.
warning_4 HomeStaging.furnish Fixed furniture items are too close to each other.
warning_5 HomeStaging.furnish Fixed furniture items overlap.
warning_6 HomeStaging.furnish Some fixed furniture item is not fully inside the room.
warning_7 HomeStaging.furnish Position of an opening was larger than the circumference of the room.
warning_8 HomeStaging.generateGroups No groups were generated with the given furniture, trying with the default ones.

Error response

Indicates that the process could not finish. Please be aware that an error response always provides 2 error codes:

error.data[0].code = The HomeStaging API error code as described bellow.

error.code = Default JSON RPC 2 error code, not related to HomeStaging API.

Code Method Message
error_1 HomeStaging.furnish, HomeStaging.generateGroups Code Error: <additional info>
error_2 HomeStaging.furnish, HomeStaging.generateGroups Invalid request parameter: <additional info>
error_3 HomeStaging.furnish Room is too large. Please send a room no larger than <n> square meters.
error_4 HomeStaging.furnish The minimal area of the fixed furniture is too large. The maximum allowed is <n> square meters.
error_5 HomeStaging.furnish The minimal area of the fixed furniture is too large compared to the useful area of the room. The maximum allowed ratio is <n>.
error_6 HomeStaging.furnish Room is too small. Please send a room at least <n> square meters.

Example:

{
    "jsonrpc": "2.0",
    "error": {
        "data": [
            {
                // HomeStaging API error info
                "code": "error_6",
                "message": "Room is too small. Please send a room at least 2 square meters."
            }
        ],
        // Default JSON-RPC2 error info
        "code": -32602,
        "message": "Invalid params"
    },
    "id": "a2716497-3999-4630-8674-002d484429f0"
}