26.06 Local Scene Module

#todo

Local Scene are mini scene lives inside of the scene which its self are also represented by the Form object. Local Scene Module provided user an easier way to arrange their space.

26.06.01 Definition of Local Space in the Scene

We will first define a plane. As in 21-Scene, the scene is a three-dimensional vector space $\mathbb R^3$. A plane can therefore defined by three vector:

• the origin of the plane $\vec o$,
• the horizontal direction unit vector $\hat u$,
• vertical direction unit vector $\hat v$ where the later two are required to be orthornomal therefore form a basis of the plane, and the plane are therefore defined as the set of all point that can be written as $\vec o + u\, \hat u + v\, \hat v$, where $u$ and $v$ are real numbers.

A plane can be represented by fellowing data

interface Plane {
	origin: Coordinate
	horizontalDirection: Coordinate
	verticalDirection: Coordinate
}

where each data is REQUIRED, and MUST be of Coordinate type, which represent a vector in the scene. horizontalDirection and verticalDirection MUST be orthornormal to eahc otehr.

Such plane also defines a coordinate transforamtion by the linear transformation that rotates $\hat x$ to $\hat u$ and $\hat y$ to $\hat v$ with a translation of $\vec o$ as defined in 21-Scene. The origional coordnate is refering as the global scene, the main scene, the full scene, or the world scene.

One can then use this new plane as the "ground plane" and have another "scene" defined with respect to the "ground plane". This ground plane are therefore named local ground plane. Together with a Form with respect to this local coordinate, they defines a local scene. The local scene are also right-handed orientation, therefore the basis of the local scene are $\hat u$, $\hat v$, and $\hat n = \hat u \times \hat v$. A point in the scene can be expressed as a 3-tuple $(u,v,n) = u\,\hat u+ v\,\hat v + n\,\hat n$ in the local coordnate.

Form object for local space CAN content data like FormMetadata and FormProperities, but they MUST NOT be used for the global scene.

If a Boundary or Tile modoule, or both are used, The artifact in the Form object of a local space MUST respect the boundary of the full space. This can be done by founding the global coordinate of the artifact by preform the coordinate transformation from the local scene to global scene and remove any artifact lies outside.

When working with Layout Mode Module, In freeform, it is NOT RECOMMENDED to use local space as it is usually more easy and less computational intense to directly place the item in the scene using the world scene coordinate.

A local scene, when explicitly stated, can be present by fellowing data

interface LocalSpace<TBase> {
	base: TBase
	form: Form
}

where data of base and form are required, and

• base MUST content at least the information of the ground plane, and
• form MUST be of type Form.

For example, the simplest local space can be LocalSpace<Plane>, or of fellowing shape

interface PlaneLocalSpace {
	base: Plane
	form: Form
}

where base is just the local ground plane.

26.06.02 Transformation of coordinate between the world scene and the local scene

A coordinate $(x,y,z)_\text{world}$ in world scene can be translate to a coordinate in the local scene $(u,v,n)_\text{local}$, where we have use the subscript to indicate which basis of the scene we are using.

// TODO some linear algebra states how to calculate xyz from uvn and from uvn to xyz.

26.06.03 Define Local Scene with Category Module

To define a local scene, one can have predefined local ground plane and any artifact belong to the predefined category are placed in the the local space. When this is done, these artifact MUST NOT play the stacking logic of the full scene and MUST only play the stacking logic in the local scene, if the local space use stacking logic.

It is RECOMMENDED for impmentation to explecetely specified which category are been used for local subspace.

it is typically not nesseary to explectely state the Form object for the local space, as it can be reconstract from the information of the Form object of the full space. If Form cannot content enough information to determate a unique Form object for the local space, please consider define local space using artifact.

There are two predefined local space, the ceiling and the wall, and it is RECOMMENDED to impmented them. If the impmentation does not impmentating these local space, artifact with thoese category MUST be ignored from the layout.

Ceiling local space

A ceiling local space is a local space with its local ground plane at the spaceHeight and use the flat version of the full space. Category of ceiling belong to this local space. If this subspace is not impmented, ceiling category artifact MUST be ignored from the layout. The local ground plane are defined with the $\hat o = h \,\hat z$, $\hat u = \hat x$, $\hat v = \hat y$, where $h$ is spaceHeight.

Althought no boundary is defined for ceiling local space, all ceiling artifact that are not within the space will be removed, therefore the boundary is effective the boundary of the full space.

The Form object representing this local space are

interface Form {
    version: string
    layoutMode: LayoutMode 
    layout: Embedding[]
}

where

• version MUST be align with the version of the full space
• layoutMode MUST be the flat version of the full space
• layout MUST content only Embedding using ceiling category artifact.

Tips for implementation

Implementation does not need to explecetely constract above Form object as all the information is store in the full space Form object. But it is typical easy to impmenting ceiling local space by cellecting ceiling artifact from the full space layout into above Form object and reuse code for reconstract the scene.

Wall local space

The wall local space are defined by artifact with category wall, and the artifact with category wallmounted belong to this local space. If this subspace is not impmented, wallmounted category artifact MUST be ignored from the layout.

The local ground planes are plane form by the side surface of volume box of the wall artifact, with the boundary coincide with the edge of the volume box of the wall artifact.

The Form object representing each local space are

interface Form {
    version: string
    layoutMode: LayoutMode 
    layout: Embedding[]
    properties: {
	    boundary: OBB[]
    }
}

where

• version MUST be align with the version of the full space
• layoutMode MUST be the flat version of the full space
• layout MUST content only Embedding using wallmounted category artifact.
• boundary MUST presenting the surface of the wall

Tips for implementation

Implementation does not need to explicitly construct above Form object as all the information is store in the full space Form object. But it is typical easy to preform coordinate transformation (with rotation) for each wall-mounted artifact to each local space to found which artifact belong to which local space and construct the above Form object and reuse the code for reconstruction of the scene.

26.06.04 Define Local Scene by Artifact

Please refering to 27.05-Local-Scene-Module-for-Artifact.

reconstruction logic and local scene

One then needs to preform to reconstract the local space by first derive the local ground plane and relevnet local space Form data, and preform above stpes for its layout with respect to the local ground plane and local space Form.