Skip to content

Commit 072771f

Browse files
drduhedrduhe
committed
chore: update readme and REGION setting
1 parent 3105e30 commit 072771f

File tree

2 files changed

+224
-44
lines changed

2 files changed

+224
-44
lines changed

‎README.md‎

Lines changed: 199 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,232 @@
11
# OSML Cesium Globe
22

3-
This project was bootstrapped with [ViteJs](https://vitejs.dev/). Build a way to visualize and display results from our image
4-
processing workflow.
3+
A desktop application for visualizing and interacting with geospatial image processing results from the [OversightML](https://github.com/aws-solutions-library-samples/osml-model-runner) ecosystem. Built with CesiumJS, React, and Electron.
4+
5+
Submit image processing requests to SageMaker endpoints, monitor job status in real-time, and explore detected features on a 3D globe with rich property inspection.
6+
7+
## Table of Contents
8+
9+
- [Features](#features)
10+
- [Architecture](#architecture)
11+
- [Getting Started](#getting-started)
12+
- [Prerequisites](#prerequisites)
13+
- [Installation](#installation)
14+
- [Running the Application](#running-the-application)
15+
- [Usage](#usage)
16+
- [Submitting an Image Request](#submitting-an-image-request)
17+
- [Loading GeoJSON Data](#loading-geojson-data)
18+
- [Loading Imagery](#loading-imagery)
19+
- [Inspecting Features](#inspecting-features)
20+
- [Project Structure](#project-structure)
21+
- [Configuration](#configuration)
22+
- [Scripts](#scripts)
23+
- [Support & Feedback](#support--feedback)
24+
- [Resources](#resources)
25+
- [License](#license)
26+
27+
## Features
28+
29+
- **3D Globe Visualization** -- CesiumJS-powered globe with ArcGIS World Imagery (automatic offline fallback to Natural Earth II), atmosphere effects, dynamic sun lighting, and distance fog.
30+
- **Image Processing Requests** -- Submit images from S3 to SageMaker endpoints for object detection with configurable tiling, compression, and feature distillation parameters.
31+
- **Real-Time Job Monitoring** -- Track request status (pending, in-progress, success, error) through SQS polling with animated status indicators.
32+
- **GeoJSON & Imagery Loading** -- Import feature collections and imagery from S3 buckets or local files with full layer management (visibility toggle, zoom-to, remove).
33+
- **Feature Inspection** -- Click any detected feature on the globe to view a rich popup with grouped, hierarchical properties (classification, location, metadata) that tracks the feature's position as the camera moves.
34+
- **Dark Glass-Morphism UI** -- Custom-built component system with backdrop blur, smooth animations, and a cinematic viewport vignette.
35+
- **Electron Desktop App** -- Runs as a native desktop application with access to local filesystem and AWS credentials.
36+
37+
## Architecture
38+
39+
| Layer | Technology |
40+
|-------|-----------|
41+
| Desktop shell | Electron 40 |
42+
| UI framework | React 19, TypeScript 5 |
43+
| 3D globe | CesiumJS 1.137, Resium |
44+
| Build tool | Vite 7, vite-plugin-cesium, vite-plugin-electron |
45+
| AWS services | S3, SageMaker, STS, SQS, DynamoDB (via AWS SDK v3) |
46+
| Tile generation | Docker (`tumgis/ctb-quantized-mesh:alpine`) |
547

6-
### Table of Contents
7-
1. [Getting Started](#getting-started)
8-
1. [Prerequisites](#prerequisites)
9-
2. [Installation Guide](#installation-guide)
10-
3. [Run OSML Cesium Globe](#run-osml-cesium-globe)
11-
2. [Support & Feedback](#support--feedback)
12-
3. [Resources](#resources)
13-
4. [License](#license)
48+
## Getting Started
1449

50+
### Prerequisites
1551

16-
## Getting Started
17-
### Prerequisites:
52+
Ensure the following are installed locally:
53+
54+
| Tool | Purpose |
55+
|------|---------|
56+
| [Node.js](https://nodejs.org/) >= 22.12.0 | Runtime & package manager |
57+
| [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) | Credential management |
58+
| [Docker](https://docs.docker.com/desktop/install/) | Image-to-tile conversion |
1859

19-
First, ensure you have installed the following tools locally
60+
You will also need:
2061

21-
- [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
22-
- [node](https://nodejs.org/en)
23-
- [docker](https://docs.docker.com/desktop/install/)
24-
- [osml model runner](https://github.com/aws-solutions-library-samples/osml-model-runner) service is running in your aws account
62+
- Active AWS credentials configured under the `default` profile in `~/.aws/credentials`
63+
- An [OSML Model Runner](https://github.com/aws-solutions-library-samples/osml-model-runner) deployment running in your AWS account (for image processing requests)
2564

26-
### Installation Guide
65+
### Installation
2766

67+
1. **Clone the repository:**
2868

29-
1. Then pull in the `cesium-globe` package:
3069
```sh
3170
git clone https://github.com/aws-solutions-library-samples/osml-cesium-globe.git
71+
cd osml-cesium-globe
3272
```
33-
or if you don't have a GitHub SSH key configured:
73+
74+
2. **Install dependencies:**
75+
3476
```sh
35-
git clone https://github.com/aws-solutions-library-samples/osml-cesium-globe.git
77+
npm install
3678
```
37-
2. Install all the packages that is listed in `package.json` (or anytime you make changes to `package.json` file)
38-
```sh
39-
npm install
40-
```
41-
3. Pull `tumgis/ctb-quantized-mesh:alpine` Docker container for Cesium Terrain Builder with quantized-mesh format support.
42-
```sh
43-
docker pull tumgis/ctb-quantized-mesh:alpine
44-
```
45-
46-
### Run OSML Cesium Globe
47-
1. Load up your AWS credentials into your terminal by using this [guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
48-
2. To deploy, execute:
79+
80+
3. **Pull the tile generation Docker image:**
81+
82+
```sh
83+
docker pull tumgis/ctb-quantized-mesh:alpine
84+
```
85+
86+
### Running the Application
87+
88+
1. **Load AWS credentials** into your terminal session using your preferred method ([guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)).
89+
90+
2. **Start the development server:**
91+
4992
```sh
5093
npm run dev
5194
```
5295

53-
**Note** If you want to clean up the builds, node_modules, etc... execute:
96+
This launches both the Vite dev server and the Electron window.
97+
98+
3. **Build for production:**
99+
100+
```sh
101+
npm run build
102+
```
103+
104+
4. **Clean build artifacts:**
105+
54106
```sh
55107
npm run clean
56108
```
57109

110+
## Usage
111+
112+
### Submitting an Image Request
113+
114+
1. Open the side panel (hamburger menu, top-left)
115+
2. Click **Submit Request**
116+
3. Select an S3 bucket, image, and SageMaker endpoint
117+
4. Configure tiling and feature distillation parameters (optional -- sensible defaults are provided)
118+
5. Choose a results color and submit
119+
6. Monitor progress via the status toast (bottom-right) and the pulsing indicator on the panel toggle
120+
121+
### Loading GeoJSON Data
122+
123+
1. Open the side panel and click **Load GeoJSON**
124+
2. Choose **From S3** or **From Local** tab
125+
3. Select a bucket and `.geojson`/`.json` file, or pick a local file from `src/data/geojson/`
126+
4. The features are loaded onto the globe and appear in the Layers list
127+
128+
### Loading Imagery
129+
130+
1. Open the side panel and click **Load Image**
131+
2. Select an S3 bucket and image file (GeoTIFF)
132+
3. The image is downloaded, converted to Cesium tiles via Docker, and displayed on the globe
133+
134+
### Inspecting Features
135+
136+
Click any loaded feature on the globe to open the feature popup:
137+
138+
- **Grouped properties** -- Classification (IRI, score, confidence), Location, Metadata, and Details sections
139+
- **Nested data** -- Object properties expand into collapsible sub-entries with chevron toggles
140+
- **Position tracking** -- The popup follows the feature as you rotate/zoom the globe
141+
- **Dismiss** -- Close button, Escape key, or click empty space
142+
143+
## Project Structure
144+
145+
```
146+
osml-cesium-globe/
147+
├── electron/ # Electron main & preload processes
148+
├── scripts/ # Python/shell scripts for image processing
149+
│ ├── calculate_extents.py
150+
│ ├── generate_cesium_terrain.py
151+
│ └── convert_data.sh
152+
├── src/
153+
│ ├── components/
154+
│ │ ├── modal/ # DarkModal, ImageRequestModal, LoadDataModal, LoadImageModal
155+
│ │ ├── ui/ # FormControls (DarkInput, DarkSelect, DarkAutosuggest, etc.)
156+
│ │ ├── alert/ # CredsExpiredAlert
157+
│ │ ├── OsmlMenu.tsx # Main side panel with actions & layer management
158+
│ │ ├── FeaturePopup.tsx # Feature click popup overlay
159+
│ │ ├── ImageRequestStatus.tsx
160+
│ │ ├── Logo.tsx
161+
│ │ └── StatusDisplay.tsx
162+
│ ├── context/
163+
│ │ └── ResourceContext.tsx # Global state for loaded layers/resources
164+
│ ├── util/
165+
│ │ ├── cesiumHelper.ts # GeoJSON/imagery loading, feature click handling
166+
│ │ ├── s3Helper.ts # S3 bucket/object operations
167+
│ │ ├── smHelper.ts # SageMaker endpoint discovery
168+
│ │ └── mrHelper.ts # Model Runner request submission & polling
169+
│ ├── config.ts # AWS config, defaults, constants
170+
│ ├── App.tsx # Root component (Viewer, base layer, atmosphere)
171+
│ ├── main.tsx # Entry point
172+
│ └── styles.css # Global styles & vignette
173+
├── vite.config.ts
174+
├── tsconfig.json
175+
└── package.json
176+
```
177+
178+
## Configuration
179+
180+
Key defaults are defined in `src/config.ts`:
181+
182+
| Setting | Default | Description |
183+
|---------|---------|-------------|
184+
| `REGION` | auto-detected | AWS region for all service calls (see below) |
185+
| `DEFAULT_TILE_SIZE` | `512` | Tile size for image processing |
186+
| `DEFAULT_TILE_OVERLAP` | `128` | Tile overlap in pixels |
187+
| `DEFAULT_FEATURE_DISTILLATION_ALGORITHM` | `NMS` | Non-Maximum Suppression |
188+
| `DEFAULT_RESULTS_COLOR_OPTION` | Yellow | Default color for detected features |
189+
| `ZOOM_MAX` / `ZOOM_MIN` | `18` / `7` | Imagery tile zoom range |
190+
191+
**AWS Region** is resolved automatically using the standard AWS precedence chain -- no source code edits required:
192+
193+
1. `AWS_REGION` environment variable
194+
2. `AWS_DEFAULT_REGION` environment variable
195+
3. `region` in `~/.aws/config` under the `[default]` profile
196+
4. Falls back to `us-west-2` if none of the above are set
197+
198+
Local data directories:
199+
200+
| Path | Purpose |
201+
|------|---------|
202+
| `src/data/geojson/` | Local GeoJSON files for import |
203+
| `src/data/images/` | Downloaded/local images for tile conversion |
204+
| `src/data/tiles/imagery/` | Generated Cesium imagery tiles |
205+
206+
## Scripts
207+
208+
| Script | Description |
209+
|--------|-------------|
210+
| `npm run dev` | Start Vite dev server + Electron |
211+
| `npm run build` | TypeScript compile, Vite build, Electron package |
212+
| `npm run preview` | Preview the Vite production build |
213+
| `npm run clean` | Remove `node_modules` and `dist-electron` |
214+
58215
## Support & Feedback
59216

60-
OSML Cesium Globe is maintained by AWS Solution Architects. It is not part of an AWS service and support is provided
61-
best-effort by the OSML community.
217+
OSML Cesium Globe is maintained by AWS Solution Architects. It is not part of an AWS service and support is provided best-effort by the OSML community.
62218

63-
To post feedback, submit feature ideas, or report bugs, please use the Issues section of this GitHub repo.
219+
To post feedback, submit feature ideas, or report bugs, please use the [Issues](https://github.com/aws-solutions-library-samples/osml-cesium-globe/issues) section of this GitHub repo.
64220

65-
If you are interested in contributing to OSML Cesium Globe, see the [CONTRIBUTING](CONTRIBUTING.md) guide.
221+
If you are interested in contributing, see the [CONTRIBUTING](CONTRIBUTING.md) guide.
66222

67223
## Resources
68224

69-
- [Amazon CloudScape UI](https://cloudscape.design/)
70-
- [Cesium](https://cesium.com/platform/cesiumjs/)
71-
- [AWS SDK V3](https://github.com/aws/aws-sdk-js-v3)
225+
- [CesiumJS](https://cesium.com/platform/cesiumjs/) -- 3D globe engine
226+
- [Resium](https://resium.reearth.io/) -- React bindings for CesiumJS
227+
- [Electron](https://www.electronjs.org/) -- Desktop application framework
228+
- [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3)
229+
- [OSML Model Runner](https://github.com/aws-solutions-library-samples/osml-model-runner)
72230

73231
## License
74232

‎src/config.ts‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2023-2025 Amazon.com, Inc. or its affiliates.
1+
// Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
22

33
import { join } from "node:path";
44

@@ -26,8 +26,30 @@ export const S3_RESULTS_BUCKET_PREFIX: string = "mr-bucket-sink";
2626
// stream name prefixes
2727
export const KINESIS_RESULTS_STREAM_PREFIX: string = "mr-stream-sink";
2828

29-
// deployment info
30-
export const REGION: string = "us-west-2";
29+
// deployment info — resolved from standard AWS sources, falls back to us-west-2
30+
function resolveRegion(): string {
31+
// 1. Environment variables (same precedence the AWS SDK uses)
32+
if (process.env.AWS_REGION) return process.env.AWS_REGION;
33+
if (process.env.AWS_DEFAULT_REGION) return process.env.AWS_DEFAULT_REGION;
34+
35+
// 2. ~/.aws/config [default] profile
36+
try {
37+
const configPath = join(homedir(), ".aws", "config");
38+
const configContents = readFileSync(configPath, "utf-8");
39+
const parser = new ConfigIniParser();
40+
parser.parse(configContents);
41+
const region = parser.get("default", "region", undefined) as
42+
| string
43+
| undefined;
44+
if (region) return region.trim();
45+
} catch {
46+
// Config file missing or unreadable — fall through to default
47+
}
48+
49+
return "us-west-2";
50+
}
51+
52+
export const REGION: string = resolveRegion();
3153

3254
// grab the aws credentials
3355
interface Credentials {

0 commit comments

Comments
 (0)