[NT-0] doc: Physical and Digital Realities (#565)

This change introduces a new module to the CSP documentation site: 'Physical and Digital Realities'.

The module covers the following topics:

Cross-Reality Applications (and digital twins)
Anchoring (with a focus on how to use CSP and Google Cloud Anchors)
Fiducial Markers

Library/docs/RegenerateDocumentation.bat

@@ -1,5 +1,5 @@
 rem Ensure Python prerequisites are met
-pip install --user -r requirements.txt
+python -m pip install --user -r requirements.txt
 
 rem Remove existing documentation and intermediate files
 @RD /S /Q "build"

Library/docs/source/learn/learn.md

@@ -132,3 +132,19 @@ You will learn how spaces are structured, how content relates to them, and gain
    spaces/management
    spaces/entities
 ```
+
+## Physical and Digital Realities
+
+This module will teach you how to bridge the physical and digital divide through augmented reality, digital twinning, and precise anchoring methods.
+
+By the end of this module, you will learn how to use various tools for spatial positioning, including digital twinning for asset alignment, anchor management using Google Cloud Anchors (GCA), and fiducial markers. You will also understand how to establish and manage Points of Interest (POIs) in CSP, enhancing user experience by pinpointing significant locations within both physical and digital environments.
+
+```eval_rst
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   physical_digital_realities/cross_reality_applications
+   physical_digital_realities/anchoring
+   physical_digital_realities/fiducial_markers
+```

Library/docs/source/learn/physical_digital_realities/cross_reality_applications.md

@@ -0,0 +1,111 @@
+# Cross-Reality Applications
+
+Physical reality refers to the tangible world where users interact with their environment in real-time. Digital reality, in contrast, is a simulated version of physical reality recreated digitally through 3D models, textures, and spatial dimensions. Bridging these two realities is essential in creating applications that seamlessly blend digital content into physical spaces, enhancing user interactions and experiences.
+
+In connected applications, where users experience both realities, ensuring alignment between physical and digital spaces becomes crucial. This alignment allows users to interact with digital objects in physical environments with spatial accuracy, maintaining a coherent, shared experience.
+
+### The Significance of Spatial Coherence 
+
+Spatial coherence is the consistency between digital content's position in digital and physical spaces. When spatial coherence is maintained, digital content appears to occupy the exact spot in the physical space, even when viewed from different angles or by multiple users. This shared perception is essential for collaborative experiences, allowing users to consistently see and interact with digital elements across both physical and digital perspectives.
+
+### Importance of Cross-Reality Applications
+
+Cross-reality applications merge physical and digital realities, enabling users to experience and interact with digital content as though it exists in the physical world. These applications are enabled by CSP, allowing users to move seamlessly between real and virtual environments. Cross-reality applications enhance how users experience digital spaces by blurring the line with the physical world.
+
+### Use Cases of Cross-Reality Applications
+
+Cross-reality applications find value across diverse fields, enhancing collaborative, immersive, and interactive experiences. Examples include:
+
+* **Virtual Collaboration** 
+  Users in different physical locations can meet in a shared digital environment, interacting with digital twins of spaces or objects. This is particularly useful for remote work, where teams can inspect and discuss digital replicas of real-world items.
+
+* **Augmented Reality (AR) Navigation**
+  In large venues or campuses, AR overlays digital directions onto physical spaces, guiding users through real environments. This alignment provides real-time guidance, improving user experience by blending information into physical contexts.
+
+* **Training and Simulation**
+  In fields like healthcare or manufacturing, digital replicas of real-world tools or environments offer immersive training. Learners interact with these digital tools as if they were physical, enabling practice in a safe, controlled digital environment.
+
+## Understanding Digital Twins
+
+A digital twin is a precise virtual replica of a physical environment, mirroring its structures, spatial layout, and physical properties. In CSP, digital twins serve as virtual proxies for real-world spaces, facilitating cross-reality interactions. They enable users to interact with a digital version of a physical location as if they were present there, regardless of where they are physically located.
+
+###  Components of a Digital Twin
+
+A digital twin comprises several key elements:
+
+* **3D Models:** These models recreate the physical structures of an environment, including buildings, rooms, and objects, in accurate digital formats.
+
+* **Materials and Textures:** To closely resemble the real-world space, materials and textures match those found in the physical environment, enhancing realism.
+
+* **Spatial Dimensions and Scale:** Precise dimensions and spatial accuracy are crucial for maintaining a true-to-life experience. The digital twin must mirror the physical environment in size, scale, and layout.
+
+Creating a digital twin requires a high level of accuracy, as any inconsistencies can disrupt user immersion and spatial coherence. The fidelity of these components ensures that the digital twin aligns closely with the real world, which is critical for cross-reality applications.
+
+### Benefits of Digital Twins in Cross-Reality Applications
+
+Digital twins play a vital role in cross-reality applications by bridging physical and digital spaces. They enable users in different physical locations to access and interact with the 'same' environment. For instance, a user in the physical space can interact with digital elements anchored to real-world locations. In contrast, another user in the digital twin experiences the same elements at the same location. This alignment creates seamless, shared experiences across both realities, fostering real-time engagement and collaboration.
+
+### Practical Application of Digital Twins
+
+Digital twins have diverse applications that highlight their ability to enhance user interaction and collaboration:
+
+* **Virtual Tourism:** Digital twins of popular tourist locations allow users to explore these spaces remotely. Through a virtual tour, they can interact with points of interest and gain a near-real experience without being physically present.
+
+* **Real-Time Collaboration:** Teams in different locations can interact within a shared digital twin for tasks like design reviews or space planning. For example, architects and clients can meet in a digital replica of a new building, inspecting and discussing specific design elements as if they were physically present.
+
+* **Training and Simulation:** Digital twins allow users to train within realistic environments without the risks associated with a physical setting. Industries such as healthcare, manufacturing, and emergency response use digital twins to simulate real-world scenarios, providing safe, controlled practice environments.
+
+### Relating the Physical and Digital Worlds
+
+In CSP, an asset represents a digital file that can be used within a space, such as models, textures, or gaussian splats. Assets are integral to creating a digital twin, enabling the replication of real-world elements within a virtual environment. When used to represent a digital twin, assets enable users to interact with a space that accurately mirrors the physical world and individual objects and materials.
+
+### Process for Recreating the Physical
+Creating a digital twin requires precise spatial alignment to ensure an immersive experience. Here's an overview of the process:
+
+1. **Identify and Digitize The Physical World:** Select key physical items to be represented within the digital twin. These items are recreated in the digital space through photogrammetry, 3D modeling and texturing.
+
+2. **Align Assets with Digital Twin Coordinates:** Each digital asset is placed in its corresponding location within the digital twin, ensuring it aligns with its physical position. This process relies on accurate coordinates and scaling.
+
+3. **Validate Spatial Alignment:** Check that digital assets are spatially coherent with their physical counterparts. Any misalignment can impact user experience, making this validation step critical.
+
+## Mapping Digital Twins onto Physical Reality via AR and Anchoring
+
+Augmented Reality (AR) allows users to view and interact with digital content directly overlaid with the physical world. Through AR, digital elements such as 3D models, objects, or points of interest appear in real-world locations, allowing users to experience a blended view of both realities.
+
+When combined with CSP, AR provides a spatial framework where digital content can align precisely with physical locations. CSP uses coordinates and spatial data to map the digital coordinate system with a physical coordinate system, ensuring each digital element aligns accurately. This spatial positioning is fundamental for cross-reality applications, where users expect digital content to behave and appear as if it exists within their physical space.
+
+### Anchoring Digital Twins to Real-World Locations
+
+Anchoring is the process of establishing fixed digital reference points within the physical world, ensuring that digital twins and content remain stable and spatially accurate in AR. Anchors are essential for maintaining alignment, as they allow digital elements to be 'anchored' to specific locations in physical space. This alignment is critical for preserving spatial coherence, where digital content appears precisely where it should in the physical environment.
+
+### Role of Google Cloud Anchors (GCA) in CSP
+
+In CSP, Google Cloud Anchors (GCA) play a key role in precise alignment between digital and physical assets. CSP handles the digital coordinate transform for a given anchor, and GCA handles the physical.
+
+In this way, CSP and GCA allow applications to store and retrieve digital-to-physical spatial coordinate mappings, tied to real-world locations, so that digital content is accurately placed, at the centimetre level, even across multiple devices. By using GCA, CSP can achieve a high degree of alignment between digital twins and their physical counterparts, enabling users to experience seamless, location-based AR interactions.
+
+### Ensuring Spatiotemporal Coherence
+
+1. **Maintaining Perfect Alignment Across Digital and Physical Perspectives**  
+   Anchors are instrumental in ensuring spatiotemporal coherence, where users experience digital content aligned perfectly with physical objects and spaces.
+   This coherence is essential in connected applications, where users across different devices or locations interact with the same digital content. Anchors enable these digital elements to occupy the same spatial position and orientation, regardless of the user's perspective, promoting a consistent shared experience.
+
+2. **Anchor Transformations: Position, Rotation, and Scale**  
+   The transform properties of an anchor - its position, rotation, and scale - define its alignment within the physical space. Position determines the anchor's location, rotation controls its orientation, and scale ensures size consistency. By defining these transforms, CSP can accurately place digital content within physical space, maintaining the correct alignment and scale. As a result, users experience digital twins and other AR elements as if they were naturally part of the physical world, enhancing immersion and usability in CSP-enabled applications.  
+
+
+## Summary
+
+In this module, you explored the essential components of spatial positioning in CSP. By understanding cross-reality applications, digital twins, asset association, and AR-based anchoring, you have the foundational knowledge to create immersive, spatially coherent experiences.
+
+**Cross-Reality Applications**  
+Cross-reality applications bridge the physical and digital worlds, allowing users to engage with digital content in real-world settings. This concept is at the core of spatial positioning in CSP, where users interact with digital elements that align seamlessly with their physical surroundings.
+
+**Digital Twins**  
+A digital twin is a one-to-one digital replica of a physical environment, built with high accuracy in 3D models, materials, and spatial dimensions. Digital twins allow users to interact with a virtual space that mirrors reality, creating immersive and consistent experiences across both digital and physical environments.
+
+**Asset Association with Digital Twins**  
+Associating assets with digital twins ensures that specific objects and features of a real-world environment are represented accurately in digital form. This alignment is key to maintaining spatial coherence, as it lets users interact with familiar objects in both physical and digital spaces. Consistent asset updates across realities are essential to preserve the reliability and accuracy of digital twins.
+
+**Augmented Reality and Anchoring**  
+Augmented Reality (AR) is a tool that allows users to view and interact with digital twins that are overlaid with physical spaces. Anchoring, supported by Google Cloud Anchors (GCA) in CSP, is crucial for maintaining alignment. Anchors fix digital content in specific real-world locations, ensuring that digital and physical perspectives remain coherent. The anchor's position, rotation, and scale ensure that content is consistently and accurately placed in the physical environment, enhancing the immersive quality of cross-reality applications.