README.md

metadata

title: 🧜‍♀️Streamlit🧠CV📚Scroller
emoji: 🧜‍♀️📚🧜‍♂️
colorFrom: gray
colorTo: pink
sdk: streamlit
sdk_version: 1.45.0
app_file: app.py
pinned: false
license: mit
short_description: 🧠CV Scroller🧜‍♀️🧜‍♂️🧜3D Graphs

📂 File Cast & Roles

• app.py — 🧑‍✈️ The Conductor
  Orchestrates Streamlit:

  • Loads per‑plot CSVs (your saved “tiles”)
  • Fetches the GameState vault
  • Injects everything into the browser
  • Listens for your “💾 Save” click and hands new objects off to both the plot‑file writer and the GameState vault

• gamestate.py — 💼 The Vault
  A thread‑safe singleton that:

  • On startup, reads world_state.csv → world_state[]
  • On update, merges in new objects by obj_id and writes back to world_state.csv
  • Serves as the shared truth for everyone who joins

• index.html — 🎭 The Stage
  Three.js world where:

  • Injected arrays (ALL_INITIAL_OBJECTS, PLOTS_METADATA, GAME_STATE) arrive as window… variables
  • Ground tiles and objects are rendered from those arrays
  • Local clicks spawn new objects into a sessionStorage “back‑pocket” until you hit Save
  • A tiny 5 s timer peeks at window.GAME_STATE so you can see others’ updates in near‑real time

• requirements.txt — 🛠️ The Toolbox
  Lists exactly the small helper you need (streamlit_js_eval) to bridge JS ↔️ Python

---

🔄 How State Sticks

1. Persistent CSVs

   • Per‑plot files (plot_X3_Z2.csv) hold each tile’s snapshot
   • Global file (world_state.csv) holds the universal list of all objects

2. In‑Memory Caching

   • @st.cache_data for plot metadata (avoids re‑reading disk for 1 h)
   • @st.cache_resource for the GameState singleton (one vault, never re‑instantiated)

3. Browser Session Storage

   • Unsaved objects live in sessionStorage so you don’t lose placements on refresh
   • Cleared only when you “Reset” or after a successful Save

4. JS ↔️ Python Bridge

   • JS getSaveDataAndPosition() → returns your new objects + player coords as JSON
   • Streamlit parses that, writes CSV, merges vault, clears caches, and reruns to inject the fresh state back into the Stage

---

🌊 Flow of Play (Intuition)

1. Boot Up

   • Conductor (app.py) reads all the saved chunks → tells the Stage (index.html) “Here’s what’s out there!”

2. Explore & Build

   • You walk around (WASD) and click to place “House🌳Rock🏠Tree”
   • New pieces go into your back pocket (sessionStorage)—invisible until saved

3. Save the Day

   • Hit “💾 Save” → Conductor grabs your pocket’s contents
   • Vault (GameState) merges them into the master record
   • Plot files get updated so new visitors see your work

4. Collaborate in Near‑Real Time

   • Every 5 s the Stage peeks at window.GAME_STATE
   • You see newcomers’ additions pop in without a full reload

✨ a tiny toolbox keep a persistent, shared, interactive 3D world humming! 🎉```

• 🐍 Python Startup

  • 📂 load_plot_metadata() → scan saved_worlds/ for plot_X…_Z…csv (cached)
  • 📑 load_plot_objects() → read CSV → build ALL_INITIAL_OBJECTS
  • 🔒 get_game_state() → singleton GameState → load/hold world_state.csv
  • 🚀 Inject → ALL_INITIAL_OBJECTS, PLOTS_METADATA, GAME_STATE into index.html

• 💾 Save Flow

  • 🖱️ User clicks “💾 Save” → JS getSaveDataAndPosition() → returns JSON payload
  • 🔄 Py parses → computes plot_X…_Z….csv → save_plot_data() writes per‑plot file
  • ➕ game_state.update_state() merges into world_state.csv
  • 🔁 load_plot_metadata.clear() + st.rerun() → refreshed state

• 🌐 Three.js Init

  • 🌟 init() → scene, camera, lights
  • 🛤️ setupInitialGround() → one plane per saved plot (or at 0,0)
  • 👤 setupPlayer() → capsule mesh at center
  • 📦 loadInitialObjects() → instantiate all persisted objects

• 🎮 Interaction & Local State

  • 🖱️ onDocumentClick() → raycast → spawn House/Tree/Rock… → add to newlyPlacedObjects
  • 💾 saveUnsavedState() → persist newlyPlacedObjects to sessionStorage
  • 🔄 restoreUnsavedState() on reload → rehydrate unsaved objects
  • 🗑️ resetNewlyPlacedObjects() → clear sessionStorage

• ⏩ Game Loop

  • 🔑 onKeyDown/onKeyUp → track WASD/Arrows
  • 🚶 updatePlayerMovement() → camera‑relative walk + checkAndExpandGround()
  • 🌱 checkAndExpandGround() → add placeholder planes around player
  • 📽️ animate() → movement, camera lerp, renderer.render()

• 🔄 Collab Sync

  • ⏲️ setInterval(pollGameState, 5000) → logs or applies updated window.GAME_STATE

✨ All set! end‑to‑end state protocol.