Furnishing AI - API V4 Reference

Furnish a Room

The FurnishingAI.furnish.v4 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.

We provide JSON schema definitions for parameter validation.

{
    "jsonrpc": "2.0",
    "method": "FurnishingAI.furnish.v4",
    "id": "a2716497-3999-4630-8674-002d484429f0",
    "params": {
        "usage": "dining",
        "furniture": [
            {
                "type": "diningChair",
                "targetCount": 4,
                "shape": { "type": "box", "a": 0.5, "b": 0.5, "h": 0.5, "customData": {"id": "qwe"} }
            },
            {
                "type": "diningTable",
                "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"} }
            }
        ],
        "space": {
            "geometry": {
                "type": "Polygon",
                "coordinates": [[[-2,2], [2,2], [2,-2], [-1.5,-2], [-2,-1]]]
            },
            "properties": {
                "height": 2.7
            },
            "geometryOpenings": [
                { "type": "window", "pos": 1, "y": 0.6, "l": 1.6, "h": 1.6, "edgeIdx": [0, 0] },
                { "type": "door", "pos": 0.2, "y": 0, "l": 0.8, "h": 2.1, "edgeIdx": [0, 1] }
            ]
        },
        "maxResults": 10
    }
}

Conceptually there are two key pieces of information the algorithm needs as input:

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

The following are the top level parameters:

Property Type Required Description
space object required A room description defining the geometry and semantics (i.e. windows, doors) of a room.
usage string required The usage of the space from the list here.
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.

Space usage

Available usages are:

  • openWorkspace
  • enclosedWorkspace
  • meetingRoom
  • privateOffice
  • lounge
  • bedroom
  • dining
  • dining_living
  • living
  • homeOffice

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
  • sofa
  • coffeeTable
  • rug
  • floorLamp
  • singleBed
  • doubleBed
  • nightstand
  • tableLamp
  • wardrobe
  • diningChair
  • diningTable
  • ceilingLight
  • shelf
  • sideboard
  • tv
  • taskChair
  • desk
  • pedestal
  • conferenceChair
  • conferenceTable
  • other

Space

Describes the shape of the space and the openings along the boundary. The boundary is considered to be walls 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
geometry object required A space geometry object.
geometryOpenings object optional An openings object.
edgeTypes array optional Types of the polygon edges as an array of arrays of strings from wall, wall:facade, wall:core, gap, railing, corresponding to the edges defined by the coordinates in the geometry.
properties object optional To specify the ceiling height in its height attribute.

Space geometry

Defines the shape as a polygon, possibly with holes.

Property Type Required Description
type string required Has to be Polygon.
coordinates array required An array of polygonal rings, which are in turn an array of 2-length arrays, defining the points. The first ring is the outer one, the others are holes inside the polygon.

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.
edgeIdx array required Gives the polygon edge that the opening resides in as a pair of numbers: the first one gives the index of the ring, the second one the index of the edge on the ring (where the edge from the 0th vertex to the 1st is edge 0, etc.).
pos number required Position on the polygon edge that the opening resides in.
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.
onFacade boolean optional Wether the opening goes to the outside of the building.

Shape

A placeholder geometry describing the outer boundary of a furniture item. 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.v4 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.v4",
    "id": "cdd5cb62-20e1-42c2-ac21-c5b451d0cbbc",
    "params": {
        "groupType": "dining",
        "furniture": [
            {
                "type": "diningChair",
                "targetCount": 6,
                "shapes": [
                    { "type": "box", "a": 0.5, "b": 0.5, "h": 0.8  }
                ]
            },
            {
                "type": "diningTable",
                "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":  0.74  }
                ]
            }
        ],
        "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.

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": "desk",
        "shape": { "type": "box", "a": 1.6, "b": 0.8, "h": 0.75}
      },
      {
        "type": "taskChair",
        "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 desks, task chairs and sideboards are 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"
}