Configuration and Plan

Plan Objects

Object position

Objects are positioned in the room with the bottom center of the objects' bounding box. When some components are added to a configurable object in a room, the bounding box of the object changes, resulting in a displacement of the original components of the object. To compensate for this, the position of the root component of the object is retained.

original object	modified object	compensated position

Snapping

Snapping of an object in the plan is done with the following stages. If the information to perform a stage is not available, the next stage is used. If a stage leads to a snapping, the following stages are not executed and the snapping is finished.

1. Snap Vector

2. Bounding geometry

3. Bounding box for measurement

4. Bounding box of the geometry

Box for measurement

Usually the bottom center of the bounding box is used to position the object in the plan. If the object is a configurable object, and the bounding box for measurement is set, the bottom center of the bounding box for measurement is used to position the object in the plan.

For example, the bounding box for the measurement can be set to the carcass of a cabinet so that the cabinet is positioned in plan with the bottom center of the carcass, regardless of the components that are added to the cabinet.

configurable object position in plan

Bonding geometry

Objects are snapped by the projected rectangle of the bounding box of the geometry or bounding box for measurement in the ground plane. If a bounding geometry is defined, the bounding geometry is used to snap the object in the plan. The bounding geometry is projected in the ground plan and the resulting 2D contour is used to snap the objects.

object snapping bounding geometry

Example - snapping with bounding geometry

{
    "id": "roomle_script_documentation:trapezoid_with_bounding_geometry",
     "geometry": "
        AddPrism(1000, Vector2f[{ -500, 500}, {500, 500}, {1077.35, -500}, { -1077.35, -500}]);
        SetObjSurface('roomle_script_documentation:magenta');
    ",
    "boundingGeometry": "
        AddPrism(1000, Vector2f[{ -500, 500}, {500, 500}, {1077.35, -500}, { -1077.35, -500}]);
    "
}

Snap Vector

Snap vectors are additional information that is used to snap and merge objects together. The vectors define the positions and orientations at which the objects are snapped to each other or to the wall. The vectors consists of a positionFrom, positionTo, type and enabled property. The positionFrom and positionTo define the start and end point of the vector. The type defines the type of the vector. The enabled property defines if the vector is enabled or not. The positionFrom, positionTo and type are either constants or expression scripts. The scripts are re-evaluated when a configuration is changed. The allowed types are "righttop", "backtop", "lefttop", "rightbottom", "backbottom", "leftbottom", "leftbacktop", "rightbacktop", "leftbackbottom" and "rightbackbottom". Objects can be snapped left to right or back to back. The back side vectors are also used to snap objects to walls or wall corners.

Snap vectors for regular objects:

left	right	back

Snap vectors for corner objects:

corner	corner back

Example - snap vectors

Backside snap vector example:

{
    "id": "roomle_script_documentation:backside_snap_vector",
    "geometry": "
        AddPrism(100, Vector2f[{-404.5, -250}, {404.5, -250}, {404.5, 250}, {-404.5, 250}]);
        SetObjSurface('roomle_script_documentation:wood_oak_veneer2');
    ",
    "planInteraction": {
        "snapVectors": [
            {
                "type": "backbottom",
                "positionFrom": "{-404.5, -250, 0}",
                "positionTo": "{404.5, -250, 0}",
                "enabled": true
            }
        ]
    }
}

Corner snap vector example:

{
    "id": "roomle_script_documentation:corner_snap_vector",
    "geometry": "
        AddPrism(100, Vector2f[{-500, -500}, {500, -500}, {500, 0}, {0, 0}, {0, 500}, {-500, 500}]);
        SetObjSurface('roomle_script_documentation:wood_oak_veneer2');
    ",
    "planInteraction": {
        "snapVectors": [
            {
                "type": "rightbackbottom",
                "positionFrom": "{-500, -500, 0}",
                "positionTo": "{500, -500, 0}",
                "enabled": true
            },
            {
                "type": "leftbackbottom",
                "positionFrom": "{-500, -500, 0}",
                "positionTo": "{-500, 500, 0}",
                "enabled": true
            }
        ]
    }
}

Curved shape with snap vector:

{
    "id": "roomle_script_documentation:curved_geometry_snap_vector",
    "geometry": "
        AddPrism(height, Vector2f[{338.5, -304.9}, {569, 252.4}, {443.2, 292.9}, {338.0, 321.2}, {231.3, 341.5}, {122.8, 354.3}, {0.2, 359.2}, { -122.8, 354.3}, { -231.3, 341.5}, { -338.6, 321.0}, { -444.1, 292.7}, { -571.5, 252.4}, { -340.6, -304.9}, { -240.2, -264.6}, { -157.7, -246.4}, { -73.8, -235.8}, {0, -232.9}, {74.0, -235.8}, {157.7, -246.4}, {240.3, -264.7}]);
        SetObjSurface('roomle_script_documentation:wood_maple_veneer');
    ",
    "planInteraction": {
        "snapVectors": [
            {
                "type": "rightbottom",
                "positionFrom": "{338.5, -304.9, 0}",
                "positionTo": "{569, 252.4, 0}",
                "enabled": true
            },
            {
                "type": "leftbottom",
                "positionFrom": "{-340.6, -304.9, 0}",
                "positionTo": "{-571.5, 252.4, 0}",
                "enabled": true
            },
            {
                "type": "leftbottom",
                "positionTo": "{338.5, -304.9, 0}",
                "positionFrom": "{569, 252.4, 0}",
                "enabled": true
            },
            {
                "type": "rightbottom",
                "positionTo": "{-340.6, -304.9, 0}",
                "positionFrom": "{-571.5, 252.4, 0}",
                "enabled": true
            }
        ]
    }
}

Snap Level

Snap vectors are additional information that is used to snap objects to walls at certain levels. The levels define the heights at which an object is snapped. One level can be defined as the "default" level and is then used as the initially selected level when an object is inserted into the plan. If the levels are "fixedSnapLevels", the object cannot be placed off the defined levels, but can only jump from one level to another. The default value for the "fixedSnapLevels", "default" and "fixed" properties is false and the default value for the "enabled" propety is true. The default value for the "level" is 0. If more than one level is specified as default level, the behavior is undefined. "fixedSnapLevels", "level", "default", "enabled" are either constants or expression scripts. The scripts are re-evaluated when a configuration is changed. Levels can only be defined on the basis of a component, although levels must actually be defined on the basis of objects. So if an object consists of multiple components, the level information is read from the root component.

e.g.

Example - snap levels

{
    //...
    "fixedSnapLevels": true,
    "planInteraction": {
        "snapLevels": [
            {
                "level": 1000,
                "default": true,
                "enabled": true
            },
            {
                "level": 1600,
                "enabled": true
            }
        ]
    }
}

This defines the snap levels 1000 and 1800 for the object, with 1000 being the default level.

Intersect with walls

In the case of walls, this is a 2-step process. In the plan component itself the state intersectWithWalls needs to be set. If this state is not set, the PlanComponent and its underlying SubParts are not checked for intersections with walls. How to intersect the geometry with walls in detail must be defined with the special geometry function IntersectWithWalls.

Example - cut off by walls

{
    "id": "roomle_script_documentation:worktop_cut_off_by_walls",
    "onUpdate": "
        setBoxForMeasurement(Vector3f{1000, 600, 900}, Vector3f{0, 0, 0});
    ",
    "geometry": "
        AddPlainCube(Vector3f{1000, 600, 850});
        SetObjSurface('roomle_script_documentation:gray');
        AddPlainCube(Vector3f{1400, 1000, 50});
        MoveMatrixBy(Vector3f{ -200, -200, 850});
        SetObjSurface('roomle_script_documentation:texture_4x4');
        IntersectWithWalls();
    ",
    "planInteraction": {
        "intersectWithWalls": "true"
    }
}

Construction objects

Door arches

In the Roomle Room Planner door arches (opening arches) get drawn in the 2D view for doors and windows. The sizes of these arches are calculated via the size of the object they belong to. The default opening direction is clockwise to the left, that means to the bottom left (left hinged) when you look on the component from above and have not rotated or flipped it.

It is possible to modify these arches by flipping it on the x or y axis. For this there internal parameters available: rml_flipX and rml_flipY. By setting these to true or false you can flip the door arch of the object.

It is also possible to define door arches yourself inside the geometry script via the AddDoorArch(DOOR_CENTER, DOOR_WIDTH, OPENING_DIRECTION) function:

Functionname	Parameters	Description
AddDoorArch	doorCenter: float, doorWidth: float, *openingDirection: enum	Adds a door arch to the component

The doorCenter property defines the X-position of the door arch center and so affects where the door arch should be placed. The doorWidth defines the width (size) of the door arch. The openingDirection is an enum value and defines the opening direction (and hinge position) of the door arch. This property is optional and defaults to LEFT_CLOCKWISE if not provided.

The available enum values for the opening direction are:

• LEFT_CLOCKWISE

• LEFT_COUNTERCLOCKWISE

• RIGHT_CLOCKWISE

• RIGHT_COUNTERCLOCKWISE

Opening direction enum values for door arches

Keep in mind that these opening directions are also affected by the flip properties. So if you have for example a door arch that has an opening direction of LEFT_CLOCKWISE, so it opens to the bottom left (left hinged), and you set rml_flipX to true, the opening direction for this arch changes to RIGHT_COUNTERCLOCKWISE, so it opens to the bottom right (right hinged). Flip properties always apply to ALL door arches of the component.

If an object consists of mulitple components, like sub components or docked componenents, all door arches of all components get collected and combined in the object.

All geometry functions, like moveMatrixBy(...) and all this stuff also works on door arches. The arches basically behave like if they are a geometry like a cube or similar and so also work exactly the same. You can also put them in object groups and do all the fancy stuff, like already mentioned, they basically behave like all geometries but with the difference that they are only shown inside the planner in 2D view.

A complete configuration could look like this:

{
    "id": "catalog_id:normal_door",
    "geometry": "
        AddCube(Vector3f{400, 10, 2000});
         SetObjSurface('isdt:yellow');
        AddDoorArch(100, 200, LEFT_CLOCKWISE);
        AddDoorArch(300, 200, RIGHT_COUNTERCLOCKWISE);
    "
}

This creates a cube with two door arches in the planner 2D view.

Construction object position

By default, a construction object is positioned in the wall so that the center of the bounding box of the geometry is on the wall axis. The position of the object can be changed by defining the bounding box for measurement. If this is defined, the construction object is positioned so that the center of the bounding box for measurement is on the wall axis.

construction object position

The bounding box for the measurement is not aligned with one side of the wall, but the center of the bounding box for the measurement is placed on the wall axis. It may seem like it would be more logical to align the box on the side of the wall. However, it is not possible to define on which side of the wall. What appears logical to the human eye cannot be easily recognized by the system on the basis of a geometry divided into triangles.

Flip object

Example - flip-x, flip-y

Flip able window template:

{
    "id": "roomle_script_documentation:construction_window_1",
     "parameters": [
        { "key": "width", "type": "Decimal", "defaultValue": 600 },
        { "key": "height", "type": "Decimal", "defaultValue": 800 },
        {
            "key": "rml_flipX", "type": "Boolean", "defaultValue": false,
            "valueObjects": [ { "value": false }, { "value": true } ],
            "visible": true, "visibleInPartList": true, "global": true, "visibleAsGlobal": true, "visibleInPlanner": true
        },
        {
            "key": "rml_flipY", "type": "Boolean", "defaultValue": false,
            "valueObjects": [ { "value": false }, { "value": true } ],
            "visible": true, "visibleInPartList": true, "global": true, "visibleAsGlobal": true, "visibleInPlanner": true
        }
    ],
    "onUpdate": "
        setBoxForMeasurement({width, 120, height},{rml_flipX ? -width : 0, -60, 0});
    ",
    "geometry": "
        BeginObjGroup('window');
        /* ... */
        EndObjGroup();
        ScaleMatrixBy({rml_flipX ? -1 : 1, rml_flipY ? -1 : 1 , 1});
    "
}

Wall thickness

If the window is attached to a wall, the thickness of the wall can be queried using the getObjectProperty function, passing the wallThickness argument. If the window is not attached to a wall, the returned wall thickness is 0 or the default value.

_.wallThicknessOrZero = getObjectProperty('wallThickness');
_.wallThicknessOr120 = getObjectProperty('wallThickness', 120);

Example - wall thickness

Template for flip able window considering wall thickness:

{
    "id": "roomle_script_documentation:window_flip_x_flip_y",
    "parameters": [
        { "key": "width", "type": "Decimal", "defaultValue": 600 },
        { "key": "height", "type": "Decimal", "defaultValue": 800 },
        { "key": "depth", "type": "Decimal", "defaultValue": 60 },
        {
            "key": "rml_flipX", "type": "Boolean", "defaultValue": false,
            "valueObjects": [ { "value": false }, { "value": true } ],
            "visible": true, "visibleInPartList": true, "global": true, "visibleAsGlobal": true, "visibleInPlanner": true
        },
        {
            "key": "rml_flipY", "type": "Boolean", "defaultValue": false,
            "valueObjects": [ { "value": false }, { "value": true } ],
            "visible": true, "visibleInPartList": true, "global": true, "visibleAsGlobal": true, "visibleInPlanner": true
        }
    ],
    "onUpdate": "
        _.wallThickness = getObjectProperty('wallThickness', 120);
        setBoxForMeasurement({width, _.wallThickness, height},{(rml_flipX ? -width : 0), (depth/2-_.wallThickness), 0});
    ",
    "geometry": "
        BeginObjGroup('window');
        /* ... */
        EndObjGroup();
        MoveMatrixBy({0, -depth/2, 0});
        ScaleMatrixBy({rml_flipX ? -1 : 1, rml_flipY ? -1 : 1 , 1});
    "
}

Bounding geometry

With the boundary geometry, the cut-out shape of the wall can be defined.

construction object bounding geometry

The boundary geometry must be a prism with the outline contour of the construction object and must be thicker than the wall.

Example - construction object with bounding geometry

{
    "id": "roomle_script_documentation:window_with_bounding_geometry",
    "parameters": [
        {
            "key": "shape", "type": "String", "defaultValue": "rhomb", 
            "validValues": [ "rhomb", "circle" ]
        },
        {
            "key": "width", "type": "Decimal", "defaultValue": 1200 
        }
    ],
    "geometry": "
        if (shape == 'rhomb') {
            AddPrism(40, [{ -width/2, 0}, {0, -width/2}, {width/2, 0}, {0, width/2}]);
            MoveMatrixBy({-width/2, -width/2, -20});
        } else if (shape == 'circle') {
            AddCylinder(width/2, width/2, 40, 64);
            MoveMatrixBy({0, 0, -20});
        }
        RotateMatrixBy({1, 0, 0}, {0, 0, 0}, -90);
        SetObjSurface('roomle_script_documentation:gray_transparent');
    ",
    "boundingGeometry": "
        if (shape == 'rhomb') {
            AddPrism(1000, [{ -width/2, 0}, {0, -width/2}, {width/2, 0}, {0, width/2}]);
            MoveMatrixBy({-width/2, -width/2, -500});
        } else if (shape == 'circle') {
            AddCylinder(width/2, width/2, 1000, 64);
            MoveMatrixBy({0, 0, -500});
        }
        RotateMatrixBy({1, 0, 0}, {0, 0, 0}, -90);
    "
}

By combining bounding geometry and box for measurement, it is even possible to create wall niches.

Example - construction object with bounding geometry

{
    "id": "roomle_script_documentation:niche_shelf",
    "parameters": [
        { "key": "material", "type": "Material", "defaultValue": "roomle_script_documentation:wood_oak_veneer" },
        { "key": "width", "type": "Decimal", "defaultValue": 600 },
        { "key": "height", "type": "Decimal", "defaultValue": 800 },
        { "key": "depth", "type": "Decimal", "defaultValue": 60 },
        { "key": "shelves", "type": "Integer", "defaultValue": 2 }
    ],
    "onUpdate": "
        _.wallThickness = getObjectProperty('wallThickness', 120);
        setBoxForMeasurement({width, _.wallThickness, height},{0, (depth-_.wallThickness), 0});
    ",
    "geometry": "
        for (_.i = 0; _.i < shelves; _.i++) {
            AddCube({width, depth, 30});
            MoveMatrixBy({0, 0, height * (_.i + 1) / (shelves + 1) - 15});
            SetObjSurface(material);
        }
    ",
    "boundingGeometry": "
        _.wallThickness = getObjectProperty('wallThickness', 120);
        AddPlainCube({width, 1000, height});
        "
}