# Spatial UI Sample

[English](README.md) | [简体中文](README_zh.md)

A reference application for PICO OS 6 demonstrating the usage of various UI components and features of the PICO Spatial SDK. It showcases how to evolve traditional 2D UI into a 3D spatial UI interface with a sense of space and strong interactivity.

## Overview

Spatial UI Sample is a comprehensive reference for building rich, multi-window spatial applications using Jetpack Compose. It guides developers through the core concepts of spatial windowing, navigation, and rendering glassmorphism materials in a 3D environment.

What you'll learn:

- Initialize a spatial application and integrate Compose content using declarative UI
- Manage spatial windows, including creating independent subwindows, toolbars, and popups
- Implement spatial navigation patterns like side navigation and gaze-following tab bars
- Utilize PICO Spatial UI design system materials, such as glassmorphism effects (Vibrant Materials), to blend UI seamlessly with the physical environment

## Features

Spatial UI Sample highlights the following core capabilities of the PICO Spatial SDK:

### 1. Basic Framework & Initialization

- **App Launch**: Demonstrates how to initialize a spatial application using `launch(::mainApp)` and integrate Compose content.
- **Scope Management**: Showcases the basic usage of `SpatialAppScope` and `DefaultWindowContainer`.

### 2. Windowing System

- **Subwindow**: Demonstrates creating independent, interactive subwindows (e.g., user detail popups) supporting multi-tasking collaboration.
- **Toolbar**: Showcases the global operation bar attached to the window edge.
- **SpatialPopup**: Lightweight spatially positioned popups.
- **TitleBar**: Standard window top configuration supporting custom titles and back logic.

### 3. Spatial Navigation

- **TabBar**: Supports side navigation mode (`TabBarPlacement.Left`).
- **Gaze-following**: Demonstrates the `followViewpoints` feature, allowing the navigation bar to move with the user's gaze, enhancing the spatial interaction experience.
- **SideNavigation**: Standard vertical navigation suitable for complex hierarchical pages.

### 4. Guidance & Feedback

- **Coachmark**: Demonstrates the usage of `RichCoachmark`, supporting titles, images, and directional guidance.
- **Snackbar**: Showcases the `SnackbarHost` spatial message notification system.
- **Progress Indicators**: Demonstrates circular and linear progress bars.

### 5. Rich Basic Components

- **Interactive Controls**: `Button`, `IconButton`, `Switch`, `Slider`, `SegmentControl`, etc.
- **Input Components**: `TextField`, `TextArea`, `SearchField`, `NumberField`.
- **Tag System**: `Badge`, `ButtonChip`, `RemovableChip`, `ToggleableChip`.
- **Menu System**: `Menu` and `MenuItem`, combined with `rememberMenuPositionProvider` for precise spatial positioning popups.

### 6. Design System & Materials

- **PicoTheme**: Global spatial visual theme.
- **Vibrant Materials**: Showcases the glassmorphism effects unique to Spatial UI (e.g., `Vibrant.Light`, `Vibrant.Darkest`), enhancing the fusion of UI with the physical environment.

## Requirements

To build and run this project, configure your development environment by following the official PICO Spatial SDK setup guide:

- [PICO Spatial SDK Setup Guide (Outside Chinese Mainland)](https://developer.picoxr.com/document/spatial-sdk/set-up-development-environment/)
- [PICO Spatial SDK Setup Guide (Chinese Mainland)](https://developer-cn.picoxr.com/document/spatial-sdk/set-up-development-environment/)

## Getting Started

### 1. Clone the Repository

```bash
git clone <repository-url>
cd SpatialUI
```

### 2. Open in Android Studio

Launch Android Studio, select **Open an Existing Project**, and choose the `SpatialUI` directory.

### 3. Run the App

#### On Emulator

1. Open **Device Manager** (toolbar or **Tools > Device Manager**)
2. Click **Add a new device** > **Create a PICO Emulator**
3. Start the emulator from **Device Manager**
4. Click **Run 'app'** to launch the app

#### On Physical Device

1. Connect your PICO device to your development machine
2. Enable **USB Debugging** on the device
3. Click **Run 'app'** to deploy directly to your device

## Project Structure

Spatial UI Sample follows a modular architecture to separate application logic from UI components:

```txt
SpatialUI/
├── app/                                  # Main application module
│   └── src/main/
│       ├── java/com/pico/spatialui/sample/ # Kotlin source files
│       │   ├── app/                        # Platform-specific implementations
│       │   │   ├── LaunchActivity.kt       # Android launcher activity
│       │   │   └── SpatialApplication.kt   # App initialization
│       │   ├── model/                      # Data models
│       │   │   └── DataModel.kt            # Application data models
│       │   ├── pages/                      # Implementation demos of various functional pages
│       │   │   ├── userpage/               # User center related pages and contents
│       │   │   ├── ContentDetailPage.kt    # Content detail page implementation
│       │   │   ├── FeedsPage.kt            # Content feeds page implementation
│       │   │   ├── HomePage.kt             # Main home page implementation
│       │   │   └── SearchPage.kt           # Search page implementation
│       │   ├── router/                     # Application routing configuration
│       │   │   └── AppGraphRouter.kt       # Navigation graph and routing definitions
│       │   ├── viewmodel/                  # Business logic and data management
│       │   │   ├── CoachMarkManager.kt     # Coachmark/tutorial state management
│       │   │   ├── FeedsViewModel.kt       # Feeds page business logic
│       │   │   ├── RelationshipViewModel.kt # Relationship page business logic
│       │   │   └── SearchViewModel.kt      # Search page business logic
│       │   └── Main.kt                     # Entry point: sets up the spatial UI container and starts the main app
│       ├── res/                            # Android resources
│       └── AndroidManifest.xml             # App manifest with Spatial component declarations
├── gradle/                               # Gradle dependencies and scripts
├── build.gradle.kts                      # Root build configuration
└── settings.gradle.kts                   # Project settings and SDK configuration
```

## Learning Resources

To deepen your understanding of spatial app development, explore the resources on our official developer websites:

- [PICO Developer Website (Outside Chinese Mainland)](https://developer.picoxr.com/)
- [PICO Developer Website (Chinese Mainland)](https://developer-cn.picoxr.com/)

## License

© 2026 PICO. The project's source code is licensed under the [Apache 2.0 License](LICENSE.txt). All assets, including textures, 3D models, audio, and others, are licensed via [Creative Commons BY 4.0](https://creativecommons.org/licenses/by/4.0/).

## Support

For questions, issues, or feature requests, please contact us through the [PICO Developer Support Portal](https://picodevsupport.freshdesk.com/support/home) and submit a ticket.

---

Developed as a reference for spatial application developers
