Assemblies

 

Fundamentals

Components

An Assembly is a collection of Components. The assembly manages several aspects of the relationship between itself and its components, noticeably:

• The Assembly’s geometry is the geometric combination of all its Components, taking into account their position (translation and rotation), and optional kinematics,
• The Assembly’s price is the sum of the price of components,
• The Assembly orchestrates the valuation of parameters.

Components are instances of either

• Products with a final geometry, represented by BM3 resources (“leaves”),
• Assemblies represented by BMA resources (“sub-assemblies”),
• In some modelling edge cases, the designer might model some assembly components without geometries.

Designing complex products as assemblies (opposed to monolithic BM3 resources) brings several advantages :

• Reuse of subcomponents across several assemblies ;
• Configurability of the product, cascading to components ;
• Pricing automatically computed as the sum of parts.

Assemblies are created and modified in Assembly Editor. Please refer to the Assembly Editor documentation 🔗 for reference.

Instances and References

The Components of the Assembly are instances referencing ByMe Products (by their ID).

An instance has the following attributes:

• Product reference (Product ID),
• Relative position (x, y z) and orientation (yx, yy, yz, zx, zy, zz) - see below,
• Activation status (boolean),
• Parameter overloads (see below).

This diagram exemplifies the difference between instance and reference : the 4 legs of this assembly are 4 different instances of the same reference. These different instances have different positions, and possibly orientations.

The result is a tree called Product Structure:

• Whose nodes are BMA components
• Whose leaves are BM3 components
• Whose branches are instances
• Whose root is a node and a commercial product,

Orientation, rotation

This section describes how to setup the (yx, yy, yz, zx, zy, zz) instance attributes to define the component orientation relative to its parent.

Component scaling is not managed through a transformation matrix, but instead by overload of width, depth, height parameters.

Cheat sheet

Attribute	yx	yy	yz	zx	zy	zz
Identity (no rotation)	0	1	0	0	0	1
Θ around X axis	0	cos θ	sin θ	0	-sin θ	cos θ
90° around X axis	0	0	1	0	-1	0
-90° around X axis	0	0	-1	0	1	0
Θ around Y axis	0	1	0	sin θ	0	cos θ
90° around Y axis	0	1	0	1	0	0
-90° around Y axis	0	1	0	-1	0	0
Θ around Z axis	-sin θ	cos θ	0	0	0	1
90° around Z axis	-1	0	0	0	0	1
-90° around Z axis	1	0	0	0	0	1

General case We refer to the standard expression of the rotation matrix:

xx	yx	zx
xy	yy	zy
xz	yz	zz

The (yx, yy, yz, zx, zy, zz) values are the coordinates of the component axes Y (yx, yy, yz), Z (zx, zy, zz) in the assembly axes.

X(xx, xy, xz) does not need to be provided as it is implied by X, Y, Z being a orthonormal, direct axis system.

The provided (yx, yy, yz, zx, zy, zz) values must enforce the following constraints:

• || Y || = sqrt (yx^2 + yy^2 + yz^2) = 1 (no scaling)
• || Z || = sqrt (zx^2 + zy^2 + zz^2) = 1 (no scaling)
• Y.Z = yx.zx + yy.zy + yz+zz = 0 (orthogonality)

The general formula for a combination of yaw, pitch and roll is the following :

Background: https://en.wikipedia.org/wiki/Rotation_matrix 🔗

Parametric Product Structure

The recommended design of a ByMe Product Structure is parametric.

This means that the reference link between an instance within an assembly (eg. BoxAssembly.BMA), and the product representing this component (eg. @Box) should not be stored as a fixed reference in the BMA, but should instead be represented as a parameter of the @BoxAssembly product.

When this convention is used, the conceptual diagram of the Product Structure has direct Product-Product reference links. This chapter details how this design can be achieved.

Assembly parameters

An Assembly declares a list of parameters representing its “degrees of freedom”. The structure is slightly different from Product Parameters. Each parameter declares

• A name - same guidelines as Product Parameter names,
• A type - same types as Product Parameters,
• A value, which is the default value when the Assembly is considered outside of the scope of a Product (eg in Assembly Editor), or that the Product does not set its value. The parameter can take any value - unlike Product Parameters which have a defined set of possible values.

Automatic Binding of Product Parameters to Assembly Parameters

When an Assembly is used as the representation of a Product, there is an automatic, unidirectional binding of parameter values from the Product to the Assembly.

Example :

Parameter	Value in Product declaration	Value in Assembly declaration	Initial runtime value in Assembly
width	600	400	600
depth	600	580	600
height	787	800	787
finish	Matte	Not declared	-
drawerGap	Not declared	3	3*

• Please note that we recommend against setting constants in resources. As any developer knows, constants change, hence they should be exposed as Product Parameters. This is especially useful to make BMA resources reusable across products now and in the future.

Assembly relations

Definition

In an assembly, relations are expressions used to compute dynamic values.

These expressions can use the following inputs :

• Assembly parameter values
• Parameter values of sub-components
• Other relations
• Any number and any standard JS operator

Relations CANNOT use the following inputs:

• Parameter values of parent components
• Sub-component references

The result of the evaluation of the expression can be assigned to :

• Instance attributes (placement, orientation, activation, but NOT reference, which should be set directly by an Assembly parameter value, binded to a Product parameter),
• Output set properties,
• Anchor points properties,
• BUT NOT to the attributes or parameters of the containing Product.

Naming guidelines

Same guidelines as for the parameters.

Type

Supported types for expression result are : number, integer, string, boolean.

Available symbols

Expressions reference available symbols as inputs:

• Current Assembly parameters : xLeftLegOffset
• Current Assembly relation results : calcThick - only for for previously declared relations,
• Component parameter value : Component.parameter
  • example : the expression “Front.depth” fetches the “depth” parameter value of the component named “Front” in the assembly.
• Constants :
  • Numerals : 2, 600, 0.5…
  • Predefined values : Pi, mPi (=-π), Pi_2 (=π/2), mPi_2 (=-π/2), Pi_4 (=π/4)
  • Real-world constants, such as mentioning 18 for wood thickness, are generally discouraged since they tend to prevent reuse and resilience to change. As in software, constants should be externalized, exposed as parameter default values which can be overloaded, or top-level parameters.

⚠️ When using a component parameter value, always test the value of the corresponding parameter (with a ternary operator typically). For example, if there is a parameter "handle" and an associated component "Handle", here is how to access Handle.depth: “handle !== null ? Handle.depth : 0”.
If you do not do that:

• the relation can crash if handle is set to null, which can happen depending on the catalog
• there is no explicit default value
• the relation will not update its value automatically when the component reference changes

Expression operations reference

Unary operators

Operator	Comment
-	The unary negation operator converts its operand to Number type and then negates it
!	Logical NOT operator, for booleans

Arithmetic operators

Arithmetic operators take numerical values (either literals or variables) as their operands and return a single numerical value.

Operator	Comment
+	Addition operator
-	Subtraction operator
/	Division operator
*	Multiplication operator
%	Remainder operator

Relational operators

A comparison operator compares its operands and returns a Boolean value based on whether the comparison is true.

Operator	Comment
<	Less than operator
>	Greater than operator
<=	Less than or equal operator
>=	Greater than or equal operator

Equality operators

The result of evaluating an equality operator is always of type Boolean based on whether the comparison is true.

Operator	Comment
===	Identity operator for product references, Equality operator for numbers, strings and booleans (without auto coercition, avoiding unforeseen implicits)
!==	Nonidentity operator for product references. Inequality operator for numbers, strings and booleans (without auto coercition, avoiding unforeseen implicits)

Binary logical operators

Logical operators are typically used with boolean (logical) values, and when they are, they return a boolean value.

Operator	Comment
&&	Logical AND
||	Logical OR

Conditional (ternary) operator

Operator	Comment
(condition ? valueIfTrue : valueIfFalse)	The conditional operator returns one of two values based on the logical value of the condition

Math Operators

The ByMe expression language is based on the Math Javascript Library : https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math The functions typically used in the ByMe context are:

Operator	Comment
Math.sin(x)	Returns the sine of x
Math.cos(x)	Returns the cosine of x
Math.abs(x)	Returns the absolute value of x
Math.floor(x)	Returns the largest integer less than or equal to x

Expressions examples

• simple operations, such as addition, subtraction, multiplication, division, … etc.
  • example : (width / 2) + xLeftLegOffset.
• math operations, by using the “Math” javaScript global Object.
  • example : -Math.cos(angleRad-Pi_2).
• ternary expressions,
  • example n°1 : (width > 600) ? true : false
  • example n°2 : (handlePosition == 0) ? handleOffset : height - handleOffset.

Parametric Instances, Overloads

Assembly Parameters and Relations’ significant role in parametric product structures originates from the ability for Assembly Instances to reference them, which, coupled with Product->Assembly parameter binding, makes it possible to cascade values and behaviors top-down in the Product Structure.

Component Instance valuation:

Instance Attribute	Possible origination
name	fixed value
reference	fixed value(1), or Assembly parameter
activated	fixed value, Assembly parameter or Assembly relation
x, y, z	fixed values, Assembly parameters or Assembly relation
yx, yy, yz, zx, zy, zz	fixed values, Assembly parameters or Assembly relations
overloads	no overload, fixed values, Assembly parameters or Assembly relations

(1) Not recommended

Downwards vs. upwards

Overloads, as declared in the Assembly instance, allow setting a Component Parameter from an Assembly Parameter, or relation (“downwards”).

Assembly relations allow to reference the value of a component parameter in an Assembly (“upwards”).

This is a modelling choice depending on the desired effect. Obviously a given component parameter can not be referenced both ways. This would produce unpredictable results.

Schoolcase : Configurable Assemblies and Parametric Product Structure

In this end-to-end schoolcase we illustrate the Parametric Assembly fundamentals:

• Product and Product Representation
• Product Structure
• Product Parameter,
• Assembly Parameter and binding
• Assembly Relations
• Assembly Instances, Instance attributes, References,
• Overloads

The complete step by step tutorial to create this schoolcase can be found here.

Summary : Parametric Assembly design patterns

Resource Instanciation	A Product setting parameter values on its geometric representation (BMA or BM3 resource) reducing its “degrees of freedom”. In some cases Range Managers use existing resource libraries, whose documentation specify the expected parameters.
Smart assembly	A BMA leveraging parameter values from its enclosing product, its components, and implementing geometry and behaviors through relations
User configurability	A Product describing the configurability space and binding it to its representation
Component properties	Components, especially leaves of the product structure such as door handles, expose Product Parameters, such as dimensions or type, which are used in enclosing assemblies relations for component placement. Examples: Handle width, handle type
Application parameters	Some ByMe applications, like HomeByMe for Kitchen Retailers, make sense of the value of some Product parameters. These parameters are not used in the geometric representation (and thus not binded to the BMA/BM3 resource). Examples: - Commercial description displayed in the Product panel, - Commercial width used as a catalog filter, - Plinth option, edge compatibility, triggering Kitchen behaviors. The full specification of such application parameters can be found the documentation of each application.

More BMA files fundamentals

Anchor points

Anchor points are defined by Range Managers within assemblies, so that end-users can use Cabinet Editor to move and replace components within the assembly within defined contraints.

This scenario is described in detail for the Kitchen Application here.

Each anchor point represents one possible position and orientation of a guest component within the assembly, and links with the possible products that might be positioned at this point. Further filtering of possible products and positions is performed by the application based on collision analysis.

A receiving anchor point is defined by the following attributes:

• Position (x, y, z)
• Rotation (yx, yy, yz, zx, zy, zz) - same conventions as for components,
• One or several receive tags, each defined by
  • A set of tags, such as “Drawer_100, Drawer_200, Drawer_400”, which are mapped against the guest components’ tags,
  • An additional rotation rx, ry, rz. These attributes can each be valued by a fixed value, an Assembly parameter or an Assembly relation.

The products that can be used as guests are assemblies that define one anchor point, whose ‘tag’ attribute creates the link to the compatible receiving anchor points ‘receive tags’.

Of course not all the anchor points defined in the assembly need to have guests. For instance a large 400mm height drawer can occupy the space of 4 anchor points that otherwise could each be occupied by a 100mm height drawer.

Instructions for settinp up Anchor Points in Assembly Editor 🔗

Output sets

A BMA file can define plane 1D paths called “output sets”.

Example usage scenarios for linear sections : here.

Worktop cutouts examples : here.

The following output set types are defined:

• Polyline : a set of segments (x1, y1, x2, y2, x3, y3…)
• Polyedge : a set of segments and circle arcs (x1, y1, r12, o12, x2, y2, r23, o23, x3, y3…), r representing the circle radius and o the circle orientation between each pair of points. Each of these attributes can be valued by a fixed value, an Assembly parameter or an Assembly relation.

Instructions for settinp up Output Sets in Assembly Editor 🔗

Animations

Animations make it possible for the user to open a drawer or a cabinet door. Animations defined within a BMA describe the motion of the full BMA relative to its parent.

Instructions for settinp up Animations in Assembly Editor 🔗