26.05.03 Stacking Logic

The idea of the stacking logic is to provide an intuitive way to organize the space for general users. The intuition behind the stacking logic is to airdrop artifacts from above, one by one, so that each newly dropped artifact stacks on top of the existing artifacts.

The stacking logic makes use of the volume of the artifact, as defined in 26.05.02-Artifact-Volume.

26.05.03.01 Requirements of the Stacking Logic

The artifact itself, i.e., the Artifact object, that participates in the stacking logic MUST have volume, as defined in 26.05.02-Artifact-Volume.

Artifact objects MAY have additional data, evenPlacement and stackable, to alter their behavior in the stacking logic. If these data are not provided, default behavior applies, corresponding to the specified default values.

Form objects MAY have additional data in FormProperties, such as spaceHeight, evenBandTolerance, coverageThreshold, and coverageThresholdEven, to alter the behavior of the stacking logic. If these data are not provided, default behavior applies, corresponding to the specified default values.

26.05.03.02 Alter the Scene Level Stacking Logic

The Layout Mode module introduces a few new members in FormProperties to adjust the behavior of the stacking logic. The new members in FormProperties are defined as

interface FormProperties {
    spaceHeight: number // OPTIONAL
    evenBandTolerance: number // OPTIONAL
    coverageThreshold: number // OPTIONAL
    coverageThresholdEven: number // OPTIONAL
    // ...
}

where

• spaceHeight, evenBandTolerance, coverageThreshold, and coverageThresholdEven are all OPTIONAL and their values MUST all be of type number. They are parameters that can be specified to alter the default behavior of the stacking logic. When not specified, the implementation MUST use their default values in the stacking logic.

The default values for these parameters are given in the following table.

26.05.03.03 Alter the Artifact Level Stacking Logic

The Layout Mode module introduces a few new members in ArtifactProperties to adjust the behavior of the stacking logic. The new members in ArtifactProperties are defined as

interface ArtifactProperties {
	evenPlacement: boolean // OPTIONAL
	stackable: boolean // OPTIONAL
	stacking: boolean // OPTIONAL
	// ...
}

where evenPlacement, stackable, and stacking are all OPTIONAL and their values MUST all be of type boolean. They are parameters that can be specified to alter the default behavior of the stacking logic. When not specified, the implementation MUST use their default values in the stacking logic if no other module alters the default value. The default value for evenPlacement is false, for stackable is true, and for stacking is true. When working with the Category module, the default values MUST follow the default values defined for each category.

An artifact with stacking set to false will not participate in the stacking logic.

26.05.03.04 The Input and Result of the Stacking Logic

The stacking logic takes an input layout from Form and produces a resulting layout in which each element, if it participates in the stacking logic, follows the stacking logic.

For artifact $i$, its original placement can be written as $(x_i', y_i', z_i')$ before performing the stacking logic, where $i$ indexes artifacts in the input layout that participate in the stacking logic. The resulting placement can be written as $(x_i, y_i, z_i)$ after performing the stacking logic.

For artifact $i$, its original rotation can be written as the Euler angle $(\alpha_i', \beta_i', \gamma_i')$ before performing the stacking logic, where $i$ indexes artifacts in the input layout that participate in the stacking logic. The resulting rotation can be written as $(\alpha_i, \beta_i, \gamma_i)$ after performing the stacking logic.

The stacking logic alters the height of the artifact and the rotations around the $x$- and $y$-axes. The ground plane coordinate and the rotation around the $z$-axis are left unchanged.

26.05.03.05 Stacking Index

A stacking index can be intuitively understood as the order in which artifacts are air-dropped into the scene.

Given a list of Embedding objects, i.e., the Embeddings in the layout of the Form object that are participating in the stacking logic, one can order them by their height, i.e., $z_i'$ as defined in 26.05.03-Stacking-Logic#26.05.03.04 The Input and Result of the Stacking Logic, from smallest to largest. For artifacts at the same height, the smaller $y_i'$ goes first; for artifacts at the same height and the same $y_i'$, the smaller $x_i'$ goes first. If the input position values are exactly the same, the outcome of the stacking logic is degenerate.

The stacking index of an Embedding in the list is then defined by the position of the Embedding in the ordered list. In the following sections, this stacking index obtained from the layout with artifacts participating in the stacking logic will be referred to as stackIndex.

26.05.03.06 Performing the Stacking Logic

Conceptually, the stacking logic models each artifact as a box according to its volume and airdrops the to-be-placed artifact $i$ in ascending order of its stackIndex at the ground plane coordinate $(x_i', y_i')$, placing it on top of the already placed artifacts. The height of the top of the supporting artifact is therefore the $z_i$ of the to-be-placed artifact $i$, and the ground plane coordinate is unchanged, i.e., $(x_i, y_i) = (x_i', y_i')$. Each artifact has only $z$-axis rotation and rotations around other axes are ignored. Therefore the resulting rotation is $(\alpha_i, \beta_i, \gamma_i) = (0, 0, \gamma_i')$.

If the placed artifact that directly supports the to-be-placed artifact is not stackable, the airdrop fails, the to-be-placed artifact is withdrawn, and the process moves on to airdrop the next artifact.

If the to-be-placed artifact would be supported by multiple artifacts that do not form an even surface, and the to-be-placed artifact requires evenPlacement, the airdrop fails, the to-be-placed artifact is withdrawn, and the process moves on to airdrop the next artifact.

Algorithm

This process of performing stacking logic can be operated by the following steps. The $z_i$ of the placed artifact $i$ in the scene MUST be able to be reproduced by these steps regardless of the implementation of the stacking logic.

Definitions

• Footprint of an Embedding: the oriented rectangle on the ground plane obtained from its ground plane coordinate and the $z$-axis rotation at the beginning of the stacking logic, and the artifact’s volume.width and volume.length. Mesh geometry is not consulted. At 0 $z$-axis rotation, width aligns with $x$, length with $y$.
• Top of a support: the support’s base height $z$ plus its volume.height.
• Positive-area overlap: two ground rectangles “overlap” only if their intersection has non-zero area; touching along an edge or at a point does not count.

Algorithm

0. Preparing for the Stacking Logic For each artifact in the input layout, identify only those participating in the stacking logic and set their $x$- and $y$-axis rotations to zero. To focus only on the relevant data in the stacking logic, in the following steps, rotation refers to the $z$-axis rotation, position refers to the ground plane coordinate, and layout refers to the input layout with only participating artifacts. Artifacts that do not participate in the stacking logic are output as-is.
1. Order to place.
   Order all embeddings in layout by ascending stackIndex. Process them in that order. Let the already processed ones be the “placed set.”
2. For each to-be-placed artifact $i$: build its ground context.
   1. Compute its footprint from its position, rotation, and volume.
   2. Create an initial list of supports consisting of:
      1. the floor at height 0 with the same footprint, treated as stackable = true; and
      2. every embedding already in the placed set whose footprint has positive-area overlap with $i$’s footprint.
   3. For each such support, record its footprint, its top (base $z$ plus volume.height), and whether its artifact is stackable.
3. Find the highest resting level.
   Let $H$ be the maximum top among all supports gathered in step 2 (including the floor’s top at 0). Intuitively, this is the height where $i$ would first make contact from above.
4. Respect the form’s height cap.
   1. Let $h_i$ be $i$’s volume.height, and let $Z_{\max}$ be the form’s spaceHeight.
   2. If $H + h_i$ exceeds $Z_{\max}$, the placement of $i$ is invalid (it would protrude past the allowed space height). Do not place $i$; continue with the next artifact from step 2.
5. Select which supports “count” at the contact level.
   Collect the band supports: those supports whose top lies at and within this band.
   • If $i$’s artifact has evenPlacement = true, then the support band is the vertical interval from $H - \texttt{evenBandTolerance}$ up to $H$.
   • Otherwise, the support band collapses to the single level $H$.
6. Enforce the stackable rule at the band.
   Every band support must be stackable.
   • If any band support is not stackable, the placement of $i$ is invalid. Do not place $i$; continue with the next artifact from step 2.
7. Require sufficient supporting area at the band.
   Compute how much of $i$’s footprint is covered by the union of the band supports’ footprints (on the ground plane). The coverage is the ratio of the covered area to the total area of $i$’s footprint, a value between 0 and 1.
   • If $i$ has evenPlacement = true, this coverage MUST be at least coverageThresholdEven.
   • Otherwise, the coverage MUST be at least coverageThreshold. If the required coverage is not met, the placement of $i$ is invalid. Do not place $i$; continue with the next artifact from step 2.
8. Assign the height.
   If steps 4–7 all pass, set $z_i = H$. The artifact $i$ is considered placed at $(x_i, y_i, z_i)$, where $(x_i, y_i)$ comes from its original position. Add $i$ to the placed set and proceed to the next artifact from step 2.

After iterating through the ordered layout, each successfully placed artifact $i$ has a determined height $z_i$. Artifacts that violated the height cap, stackability, or area-coverage requirements at their contact level are not placed.

26.05.03.07 The Stacking Logic in the Flat Layout Mode

In the flat layout mode, the stacking logic is applied with spaceHeight set to zero and volume.height overridden to zero. This forbids overlapping footprints. If a to-be-placed artifact’s footprint overlaps an existing one, do not place it. Effectively, when any overlap occurs, the artifact with the smaller stackIndex prevails.