Furnishing AI - API Reference

Furnish a Room

The FurnishingAI.furnish method can be used to furnish a room (or a part of a room) with furniture chosen from a given set of furniture pieces. 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.

We provide JSON schema definitions for parameter validation.

{
    "jsonrpc": "2.0",
    "method": "FurnishingAI.furnish",
    "id": "a2716497-3999-4630-8674-002d484429f0",
    "params": {
        "template": {
            "name": "dining",
            "exclude": ["dining_table"]
        },
        "furniture": [
            {
                "type": "dining_chair",
                "targetCount": 4,
                "shape": { "type": "box", "a": 0.5, "b": 0.5, "h": 0.5, "customData": {"id": "qwe"} }
            },
            {
                "type": "dining_table",
                "shapes": [
                    {"type": "box", "a": 1.4, "b": 0.78, "h": 0.74, "customData": {"id": "asd"} },
                    {"type": "box", "a": 1.74, "b": 0.95, "h": 0.74, "customData": {"id": "zxc"} }
                ]
            },
            {
                "type": "shelf",
                "shape": { "type": "box", "a": 1.2, "b": 0.4, "h": 2, "customData": {"id": "rty"} },
                "position": [-2, 0, 2],
                "rotation": -90
            },
            {
                "type": "sideboard",
                "shape": { "type": "box", "a": 2.2, "b": 0.4, "h": 0.6, "customData": {"id": "fgh"} }
            }
        ],
        "room": {
            "boundary": {
                "shape": {
                    "type": "polygon-extrusion",
                    "points": [ [-2,2], [2,2], [2,-2], [-1.5,-2], [-2,-1] ],
                    "h": 2.7
                },
                "openings": [
                    { "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 }
                ]
            }
        },
        "maxResults": 10
    }
}

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

  • What the room looks like.
  • The type and possible shapes of furniture you want to place in the room.

The following are the top level parameters:

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 required 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
  • living
  • home_office
  • meet: meeting room
  • executive_office
  • common: common or lounge area in an office space
  • work

Furniture Item

Describes a type of furniture as an object in the furniture list top level parameter. The furniture can have one or multiple possible shapes, and optionally a fixed position, when the furniture piece has already one.

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 non-negativev integer. Default value is dependenet of the furniture type. The item count in the result might be lower in favour of meaningful furnishings.
shape object optional A shape describing the geometrical external boundary of a furniture item. Allowed shape types for furniture items are: box, cylinder, l-extrusion, polygons-extrusion.
shapes array optional A list of possible shape objects to choose from. Either shape or shapes has to be supplied.
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. Specify only for fixed furniture, i.e. that have a position.

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
  • exec_chair
  • exec_table
  • free_standing_lamp
  • meeting_chair
  • meeting_table
  • nightstand
  • other
  • 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.

You can also define a space that is a part of a larger room: for its edges that are not physical walls, set them as openings of type gap.

Property Type Required Description
shape object 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. 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, angles in degrees.

Generate Groups

Tha FurnishingAI.generateGroups method 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, or check out the JSON schema definition. Dimensions and positions in the coordinate system are defined in meters, angles in arc degrees.

{
    "jsonrpc": "2.0",
    "method": "FurnishingAI.generateGroups",
    "id": "cdd5cb62-20e1-42c2-ac21-c5b451d0cbbc",
    "params": {
        "groupType": "dining",
        "furniture": [
            {
                "type": "dining_chair",
                "targetCount": 6,
                "shapes": [
                    { "type": "box", "a": 0.5, "b": 0.5, "h": 0.8  }
                ]
            },
            {
                "type": "dining_table",
                "shapes": [
                    {
                        "type": "cylinder", "r": 0.55, "h": 0.74,
                        "customData": { "color": "white" }
                    },
                    {
                        "type": "cylinder", "r": 0.55, "h": 0.74,
                        "customData": { "color": "brown" }
                    },
                    { "type": "box", "a": 2, "b": 0.9,  "h": 0 74 },
                    { "type": "box", "a": 1.9, "b": 0.85, "h":  074  }
                ]
            }
        ],
        "boundingBox": {
            "x": 3,
            "y": 2.4,
            "z": 3
        },
        "maxResults": 20
    }
}

The following are the top level parameters:

Property Type Required Description
groupType string required Type of the furniture group to be generated, see the group types below.
boundingBox array required The bounding box the groups should fit into.
furniture array optional A list of furniture items to be added to the groups. Furniture items that do not match the group type will be ignored. Placement of the furniture items can not be specified.
maxResults number optional Maximum number of results that shall be computed (1 - 40). Defaults to 10.
fallBackToDefaults boolean deprecated This was used to fall back to deafult furniture shapes, but doesn't have an effect anymore.

Group type

The groupType is a string that specifies the furniture types that can be combined to create the group.

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
  • meeting: meeting_table, meeting_chair
  • exec: exec_table, exec_chair, task_chair, drawer_unit

Bounding Box

Describes the bounding box the group should fit into. If the bounding box is too small for a group type, there will be no result.

Property Type Required Description
x number required dimension in meters along the x-axis
y number required dimension in meters along the y-axis (this is the height of the room)
z number required dimension in meters along the z-axis

Desk grid placement

The FurnishingAI.generateDeskGrid method can be used to place desks and task chairs, and optionally sideboards in a bounding box in a repeating pattern.

You can find the JSON schema definition here for parameter validation. Here's an example request.

{
  "id": "1234qwer-abcd-1234-dcba-123qwe456rty",
  "jsonrpc": "2.0",
  "method": "FurnishingAI.generateDeskGrid",
  "params": {
    "boundingBox": {
      "x": 9.4,
      "y": 2.4,
      "z": 8
    },
    "obstacles": [
      {
        "type": "polygon-extrusion",
        "points": [[3.5, 2], [3.5, 3], [4, 3], [4, 2]],
        "h": 3
      }
    ],
    "startRows": "-z",
    "chairSpacing": 1.2,
    "spreadSpacing": true,
    "startEdgeFacing": false,
    "tableGap": 0.02,
    "corridorWidth": 1.2,
    "maxIslandLength": 4,
    "furniture": [
      {
        "type": "task_table",
        "shape": { "type": "box", "a": 1.6, "b": 0.8, "h": 0.75}
      },
      {
        "type": "task_chair",
        "shape": { "type": "box", "a": 0.68, "b": 0.66, "h": 0.95 }
      },
      {
        "type": "sideboard",
        "shape": {"type": "box", "a": 1.2, "b": 0.4, "h": 0.5 }
      }
    ]
  }
}
Property Type Required Description
boundingBox array required The bounding box the groups should fit into.
furniture array required A list of furniture items to be added to the groups. Furniture items other than task table, task chair and sideboard will be ignored. Placement of the furniture items can not be specified.
chairSpacing number required Positive number, the required space for a chair starting from the desk, in meters.
obstacles array optional Array of polygon extrusion shapes. The pairs of desks that intersect some obstacles, will be not included in the result.
corridorWidth number optional Non-negative number setting the width of the corridor in meters. Defaults to 0.
maxIslandLength number optional Maximum length of a contiguous row of desks in meters, non-negative number. Default is 0, which means no upper bound.
spreadSpacing boolean optional If set to true, the desks will be spread out to fill the length of the bounding box. Default is false.
startEdgeFacing boolean optional If set to true, the first row of desks will face the edge of the bounding box. Default is false.
startRows string optional Defines which edge of the bounding box to start the desk rows, can be x (right), -x (left), z (bottom), -z (top), default is -z.
tableGap number optional Amount of gap or margin to have around each table, in meters. Default is 0.05.

Result Response

Example

For all of the above methods (FurnishingAI.furnish and FurnishingAI.generateGroups and FurnishingAI.generateDeskGrid) , the structure of the result is as follows (the order of the key-value pairs can be different). The positions and rotations use the coordinate system.

{
    "jsonrpc": "2.0",
    "id": "a2716497-3999-4630-8674-002d484429f0",
    "result": {
        "furnishings": [
            {
                "density": 0.8,
                "id": "furnishing-uuid-for-feedback",
                "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": [
            {
                "code": "warning_5",
                "message": "Fixed furniture items overlap."
            }
        ]
    }
}

The density indicates what fraction of the room is occupied by furniture items, so 0 would mean that no area is occupied (i.e. only pictures have been placed on walls), 1 would mean that the room is occupied completely (which is not possible because of the arrangements have to satisfy a walkability constraint).

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 FurnishingAI.furnish, FurnishingAI.generateGroups, FurnishingAI.generateDeskGrid No furnishings found.
warning_2 FurnishingAI.furnish, FurnishingAI.generateGroups Found only <n> furnishings.
warning_3 FurnishingAI.furnish Not enough walls.
warning_4 FurnishingAI.furnish Fixed furniture items are too close to each other.
warning_5 FurnishingAI.furnish Fixed furniture items overlap.
warning_6 FurnishingAI.furnish Some fixed furniture item is not fully inside the room.
warning_7 FurnishingAI.furnish Position of an opening was larger than the circumference of the room.
warning_8 FurnishingAI.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 FurnishingAI API error code as described bellow.

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

Code Method Message
error_1 furnish, generateGroups Code Error: <additional info>
error_2 furnish, generateGroups Invalid request parameter: <additional info>
error_3 furnish Room is too large. Please send a room no larger than <n> square meters.
error_4 furnish The minimal area of the fixed furniture is too large. The maximum allowed is <n> square meters.
error_5 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 furnish Room is too small. Please send a room at least <n> square meters.

Example:

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