Enrich demo with examples and documentation

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mingze Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -12,42 +12,201 @@ license: mit
 short_description: Street image segmentation with SegFormer.
 ---
 
-# Street Scene Segmentation
+<div align="center">
 
-A small Hugging Face Space for uploading street-view imagery and generating:
+# 🚦 Street Scene Semantic Segmentation
 
-- a semantic-segmentation overlay;
-- a Cityscapes color mask;
-- per-class pixel coverage;
-- downloadable overlay, mask, raw class-ID PNG, and CSV files.
+### Pixel-level urban scene understanding with SegFormer and Cityscapes
 
-The app uses
-[`nvidia/segformer-b0-finetuned-cityscapes-1024-1024`](https://huggingface.co/nvidia/segformer-b0-finetuned-cityscapes-1024-1024).
-It is intentionally small enough to run on a free CPU Space, while automatically
-using CUDA when a GPU is available. The inference function is also decorated for
-Hugging Face ZeroGPU, allowing eligible free personal accounts to host the app
-without creating a paid CPU Space.
+[![Hugging Face Space](https://img.shields.io/badge/🤗_Hugging_Face-Live_Demo-FFD21E)](https://huggingface.co/spaces/Mingze/StreetSceneSegmentation)
+[![Model](https://img.shields.io/badge/Model-SegFormer--B0-6366F1)](https://huggingface.co/nvidia/segformer-b0-finetuned-cityscapes-1024-1024)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB)](https://www.python.org/)
+[![Gradio](https://img.shields.io/badge/UI-Gradio-FF7C00)](https://www.gradio.app/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-## Deploy
+**Upload a street image and turn every pixel into an interpretable map of the urban environment.**
 
-Create a new **Gradio Space**. If your account offers **ZeroGPU**, select it in
-the hardware picker. Then push these files to the Space repository:
+[**🚀 Launch the live app**](https://huggingface.co/spaces/Mingze/StreetSceneSegmentation) ·
+[**🧠 View the model**](https://huggingface.co/nvidia/segformer-b0-finetuned-cityscapes-1024-1024) ·
+[**💻 Source code**](https://github.com/LabMingzeChen/StreetSceneSegmentation)
+
+</div>
+
+---
+
+## Live demo
+
+The public [Hugging Face Space](https://huggingface.co/spaces/Mingze/StreetSceneSegmentation)
+runs entirely in the browser interface. Students can upload an image, choose a
+built-in example, inspect the results, and download the outputs without installing
+Python or providing an API key.
+
+| Sample street image | Example segmentation result |
+|---|---|
+| ![Sample street scene](https://raw.githubusercontent.com/LabMingzeChen/HNIVision/main/space/examples/140546.jpg) | ![Example semantic segmentation](https://raw.githubusercontent.com/LabMingzeChen/HNIVision/main/space/examples/140546_segmentation.png) |
+
+## What the project does
+
+The application uses
+[`nvidia/segformer-b0-finetuned-cityscapes-1024-1024`](https://huggingface.co/nvidia/segformer-b0-finetuned-cityscapes-1024-1024)
+to perform semantic segmentation. Unlike object detection, which draws one box
+around an object, semantic segmentation assigns a class to **every image pixel**.
+
+For each image, the app produces:
+
+| Output | Purpose |
+|---|---|
+| Segmentation overlay | Keeps the original scene visible beneath the predicted classes |
+| Cityscapes color mask | Shows a clean, standardized categorical map |
+| Class coverage table | Reports class ID, pixel count, area share, and color |
+| Raw class-ID PNG | Preserves the numeric prediction for later analysis |
+| CSV summary | Supports statistics, plotting, and classroom exercises |
+
+## The 19 Cityscapes classes
+
+| Group | Classes | Example questions |
+|---|---|---|
+| Travel surfaces | `road`, `sidewalk` | How much of the view supports vehicle or pedestrian movement? |
+| Built environment | `building`, `wall`, `fence`, `pole`, `traffic light`, `traffic sign` | Which fixed urban elements dominate the scene? |
+| Nature and sky | `vegetation`, `terrain`, `sky` | How visually green or open is the street? |
+| People | `person`, `rider` | Where are active street users visible? |
+| Transport | `car`, `truck`, `bus`, `train`, `motorcycle`, `bicycle` | Which transport modes appear in the image? |
+
+The reported area share is the percentage of **image pixels** assigned to a
+class. It is a measure of visual coverage, not physical land area.
+
+## How it works
+
+```text
+Street image
+    ↓ resize and normalize
+SegFormer-B0 image processor
+    ↓ transformer-based semantic segmentation
+19-class pixel map
+    ├── original-image overlay
+    ├── Cityscapes color mask
+    ├── raw class-ID image
+    └── per-class CSV summary
+```
+
+The model is downloaded from Hugging Face on the first request and then reused
+from the container cache. CUDA is selected when available; local execution also
+works on CPU. Images larger than 2048 pixels on their longest side are resized
+to limit memory use while preserving aspect ratio.
+
+## Classroom and research examples
+
+- **Urban greenery:** compare the visible share of vegetation across streets.
+- **Street design:** examine how roads, sidewalks, buildings, and terrain divide the view.
+- **Mobility:** compare the presence of cars, bicycles, buses, riders, and pedestrians.
+- **Model literacy:** inspect boundary errors and discuss why predictions differ from human interpretation.
+- **Change over time:** process repeat photographs of a location and compare their CSV summaries.
+
+Four sample street scenes are loaded from the
+[HNIVision example collection](https://github.com/LabMingzeChen/HNIVision/tree/main/space/examples)
+and appear directly beneath the upload panel in the live app. Hosting samples
+through GitHub Raw follows the same lightweight pattern as HNI-VLM and avoids
+duplicating binary assets in the Space repository.
+
+## Run locally
+
+```bash
+git clone https://github.com/LabMingzeChen/StreetSceneSegmentation.git
+cd StreetSceneSegmentation
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+Open the local URL printed by Gradio. The first prediction downloads the public
+model weights; no application secret is required.
+
+## Use the API
+
+Every deployed Gradio Space also exposes an endpoint named `segment`:
+
+```python
+from gradio_client import Client, handle_file
+
+client = Client("Mingze/StreetSceneSegmentation")
+result = client.predict(
+    handle_file("street.jpg"),
+    0.55,  # overlay opacity
+    0.10,  # minimum table share (%)
+    api_name="/segment",
+)
+```
+
+The Space's **Use via API** panel generates additional Python, JavaScript, and
+command-line examples for the current deployment.
+
+## Deploy your own Hugging Face Space
+
+1. Create a new **Gradio Space**.
+2. Select ZeroGPU when it is available for your account, or choose another supported hardware tier.
+3. Clone this repository and add the Space as a second remote.
+4. Push the same `main` branch to Hugging Face.
 
 ```bash
 git remote add space https://huggingface.co/spaces/<USERNAME>/<SPACE_NAME>
-git push space main
+git push -u space main
 ```
 
-No API key or Space secret is required because the model is public.
+The YAML block at the top of this README is the Space configuration. Keep
+`app_file: app.py` and the declared Gradio version aligned with
+[`requirements.txt`](requirements.txt).
 
-## API
+## Project structure
 
-After deployment, the Gradio endpoint is exposed as `segment`. The Space's
-**Use via API** panel provides a generated Python and JavaScript example.
+```text
+StreetSceneSegmentation/
+├── app.py                  Gradio interface and model inference
+├── segmentation_utils.py  Palette, rendering, resizing, and CSV helpers
+├── tests/                  Lightweight image-processing tests
+└── requirements.txt        Reproducible runtime dependencies
+```
 
-## Notes
+## Limitations and responsible use
 
-- The model predicts the 19 Cityscapes street-scene classes.
-- Images larger than 2048 pixels on their longest side are resized before output.
+- The model was trained for road-driving scenes and may perform poorly on unusual
+  viewpoints, night images, severe weather, indoor scenes, or locations unlike
+  the training data.
+- Thin structures and object boundaries are common sources of pixel-level error.
+- Results are estimates, not ground truth. Do not use them for navigation,
+  safety-critical decisions, legal judgments, or identifying individuals.
+- Uploaded images are processed by the selected Hugging Face Space runtime.
+  Avoid submitting private or sensitive imagery to a public service.
 - Model-license and dataset terms remain governed by the linked model card and
-  Cityscapes terms.
+  [Cityscapes](https://www.cityscapes-dataset.com/) terms.
+
+## References
+
+- Enze Xie et al., [“SegFormer: Simple and Efficient Design for Semantic Segmentation with Transformers”](https://arxiv.org/abs/2105.15203), NeurIPS 2021.
+- Marius Cordts et al., [“The Cityscapes Dataset for Semantic Urban Scene Understanding”](https://arxiv.org/abs/1604.01685), CVPR 2016.
+- NVIDIA, [SegFormer-B0 Cityscapes model card](https://huggingface.co/nvidia/segformer-b0-finetuned-cityscapes-1024-1024).
+
+## Citation
+
+If this software supports your teaching or research, cite the repository:
+
+```bibtex
+@software{chen2026streetscenesegmentation,
+  author = {Chen, Mingze},
+  title  = {Street Scene Semantic Segmentation},
+  year   = {2026},
+  url    = {https://github.com/LabMingzeChen/StreetSceneSegmentation}
+}
+```
+
+## License
+
+Released under the [MIT License](LICENSE).
+
+---
+
+<div align="center">
+
+**If this project is useful, please star the GitHub repository and share the live Space with your students.**
+
+</div>

app.py

@@ -37,6 +37,14 @@ from segmentation_utils import (
 
 MODEL_ID = "nvidia/segformer-b0-finetuned-cityscapes-1024-1024"
 OUTPUT_ROOT = Path("/tmp/street-scene-segmentation")
+SAMPLE_ROOT = (
+    "https://raw.githubusercontent.com/"
+    "LabMingzeChen/HNIVision/main/space/examples"
+)
+SAMPLE_IMAGES = [
+    f"{SAMPLE_ROOT}/{filename}"
+    for filename in ("140546.jpg", "145541.jpg", "148831.jpg", "160710.jpg")
+]
 
 
 @lru_cache(maxsize=1)
@@ -128,6 +136,18 @@ CSS = """
 .hero {text-align: center; margin: 0 auto 1rem;}
 .hero h1 {font-size: 2.1rem; margin-bottom: .3rem;}
 .muted {color: #64748b;}
+.project-links {display: flex; justify-content: center; gap: .55rem; flex-wrap: wrap; margin-top: .75rem;}
+.project-link {
+  display: inline-block; padding: .42rem .78rem; border: 1px solid #d7deea;
+  border-radius: 999px; color: inherit !important; text-decoration: none !important;
+  background: white; font-size: .92rem; font-weight: 600;
+}
+.project-link:hover {border-color: #6366f1; box-shadow: 0 2px 8px rgba(99, 102, 241, .12);}
+.guide-grid {display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: .8rem; margin: .8rem 0;}
+.guide-card {border: 1px solid #e2e8f0; border-radius: 12px; padding: .85rem 1rem; background: rgba(255,255,255,.55);}
+.guide-card h3 {margin: 0 0 .35rem; font-size: 1rem;}
+.guide-card p {margin: 0; color: #475569; font-size: .93rem; line-height: 1.45;}
+@media (max-width: 760px) {.guide-grid {grid-template-columns: 1fr;}}
 """
 
 
@@ -136,8 +156,13 @@ with gr.Blocks(title="Street Scene Segmentation", theme=gr.themes.Soft(), css=CS
         """
         <div class="hero">
           <h1>🚦 Street Scene Semantic Segmentation</h1>
-          <p>Upload a road or urban street image to identify Cityscapes classes such as roads, sidewalks, buildings, vegetation, vehicles, and people.</p>
-          <p class="muted">SegFormer-B0 · 19 street-scene classes · CPU/GPU adaptive</p>
+          <p>Turn a street image into a pixel-level map of roads, sidewalks, buildings, vegetation, vehicles, people, and more.</p>
+          <p class="muted">SegFormer-B0 · 19 Cityscapes classes · browser-based · no API key required</p>
+          <div class="project-links">
+            <a class="project-link" href="https://huggingface.co/spaces/Mingze/StreetSceneSegmentation" target="_blank">🤗 Hugging Face Space</a>
+            <a class="project-link" href="https://huggingface.co/nvidia/segformer-b0-finetuned-cityscapes-1024-1024" target="_blank">🧠 Model card</a>
+            <a class="project-link" href="https://github.com/LabMingzeChen/StreetSceneSegmentation" target="_blank">⭐ GitHub source</a>
+          </div>
         </div>
         """
     )
@@ -150,6 +175,13 @@ with gr.Blocks(title="Street Scene Segmentation", theme=gr.themes.Soft(), css=CS
                 height=470,
                 sources=["upload", "clipboard", "webcam"],
             )
+            if SAMPLE_IMAGES:
+                gr.Examples(
+                    examples=SAMPLE_IMAGES,
+                    inputs=image_input,
+                    label="Or try a sample street scene",
+                    examples_per_page=4,
+                )
             with gr.Accordion("Display settings", open=False):
                 opacity_input = gr.Slider(
                     0.15,
@@ -191,9 +223,41 @@ with gr.Blocks(title="Street Scene Segmentation", theme=gr.themes.Soft(), css=CS
 
     gr.Markdown(
         """
-        > The model is downloaded from Hugging Face on the first run and then reused from the container cache.
-        > Images are resized to a maximum side length of 2048 px to prevent memory issues.
-        > This Cityscapes model is intended for street scenes, not medical, remote-sensing, or indoor imagery.
+        ## How to use the app
+
+        <div class="guide-grid">
+          <div class="guide-card"><h3>1 · Choose an image</h3><p>Upload, paste, use a webcam, or select one of the sample street scenes above.</p></div>
+          <div class="guide-card"><h3>2 · Run segmentation</h3><p>The model assigns one Cityscapes class to every pixel. The first run may take longer while the model loads.</p></div>
+          <div class="guide-card"><h3>3 · Explore and download</h3><p>Compare the overlay and mask, review area shares, and download reusable PNG and CSV outputs.</p></div>
+        </div>
+
+        ## What the results mean
+
+        - **Overlay** blends the prediction with the original photograph. White lines mark boundaries between predicted classes.
+        - **Color mask** shows only the standard Cityscapes colors, making classes easier to compare across images.
+        - **Area share** is the percentage of image pixels assigned to each class. It describes visual coverage, not physical land area.
+        - **Class-ID PNG** stores the numeric class at each pixel; the CSV summarizes visible classes and their colors.
+
+        | Scene layer | Classes |
+        |---|---|
+        | Travel surfaces | road, sidewalk |
+        | Built environment | building, wall, fence, pole, traffic light, traffic sign |
+        | Nature and sky | vegetation, terrain, sky |
+        | People | person, rider |
+        | Transport | car, truck, bus, train, motorcycle, bicycle |
+
+        ## Classroom and research ideas
+
+        - Compare vegetation and built-environment shares across several streets.
+        - Discuss why a pixel classifier can confuse terrain, sidewalk, wall, or fence at object boundaries.
+        - Export the CSV files and create a class-coverage chart for an urban-design exercise.
+        - Compare the same location across seasons, weather conditions, or camera viewpoints.
+
+        > **Important:** predictions are model estimates, not ground truth. The model was trained for road-driving imagery and can be less reliable for unusual viewpoints, severe weather, night scenes, indoor images, or places unlike the training data. Do not use it for safety-critical decisions or to identify individuals.
+
+        [Read the SegFormer paper](https://arxiv.org/abs/2105.15203) ·
+        [Explore the Cityscapes dataset](https://www.cityscapes-dataset.com/) ·
+        [View the source on GitHub](https://github.com/LabMingzeChen/StreetSceneSegmentation)
         """
     )