BeeAR is a virtual try-on stack for glasses and accessories — frame catalog, full 3D person + glasses GLB studio, pupil-distance (PD) fit, multi-frame compare, plus web / desktop / Android clients on shared libraries.
Product: mergeos-bounties/BeeAR · Live demo: mergeos-bounties.github.io/BeeAR
Static, minified browser demo — no Python server required:
| Page | URL |
|---|---|
| Camera / 2D try-on | https://mergeos-bounties.github.io/BeeAR/ |
| 3D person studio | https://mergeos-bounties.github.io/BeeAR/studio3d.html |
- Catalog + SVG + GLB assets are shipped as static files (
site/catalog/). - API calls are shimmed by
static-api.js(sessions/wishlist soft-mocked). - Build locally:
node scripts/build-pages.mjs→ opensite/with any static server. - Deploy: GitHub Actions workflow pages (push to
masteror workflow_dispatch). - On library release (
node scripts/release-libs.mjs), try-on IIFE is emitted as.min.jsand the Pages site is rebuilt with minified JS/CSS.
# preview static demo
node scripts/build-pages.mjs
npx --yes serve site -p 4173
# → http://127.0.0.1:4173/- Live demo (GitHub Pages)
- 3D person try-on (new)
- Demo video
- Monorepo packages
- Libraries (web + Android)
- Highlights
- Screenshots
- Quick start (server)
- CLI reference
- Catalog, fit & 3D assets
- Diagrams
- Repository layout
- Privacy
- Development
- Android
- MergeOS bounties
- License
BeeAR ships full-body Meshy characters (female + male) plus a low-poly bust, and multiple glasses GLB meshes. In the WebGL studio you can switch person, orbit, fit scale, auto-rotate, and snapshot. v0.4.4 fixes 3D AR parenting (glasses stay locked on the face when the person reloads), face-anchor fit for Meshy bodies, and composites camera/demo GLB overlays onto the main canvas so snapshots match what you see.
| Asset | Path |
|---|---|
| Female character | packages/catalog/glb/person_female.glb (Meshy) |
| Male character | packages/catalog/glb/person_male.glb (Meshy) |
| Studio bust (fallback) | packages/catalog/glb/person_bust.glb |
| Glasses GLBs | Meshy ellipse / square / studio + aviator, wayfarer, round, cat-eye, sport, … |
| Studio UI | packages/web/studio3d.html → /studio3d.html (person dropdown + frames) |
| 2D + camera | / (canvas try-on; GLB overlay when WebGL available) |
cd packages\server
pip install -e ".[dev]"
beear serve --port 8860
# open:
# http://127.0.0.1:8860/studio3d.html ← 3D person + glasses
# http://127.0.0.1:8860/ ← camera / demo photoRegenerate meshes (offline, no network):
python packages\catalog\scripts\generate_3d_assets.py
3D person bust + Aviator Gold GLB (offline mesh render used for docs)
Full rotation of the 3D person with glasses GLB try-on:
https://github.com/mergeos-bounties/BeeAR/raw/master/docs/videos/beear-3d-tryon.mp4
Click the poster or open docs/videos/beear-3d-tryon.mp4
Rebuild the video after asset changes:
python scripts\render_3d_demo_video.py| Package | Path | Role |
|---|---|---|
| @beear/tryon | packages/tryon-js |
Shared JS try-on lib (fit, overlay) for web + Android WebView |
| BeeAR Server | packages/server |
Catalog API, try-on helpers, FastAPI, CLI (beear) |
| BeeAR Web | packages/web |
Browser host + 3D Studio |
| BeeAR Desktop | packages/desktop |
Electron shell wrapping the web app |
| beear-webview | packages/android/beear-webview |
Android library (AAR) — reusable WebView try-on |
| BeeAR Android app | packages/android/app |
Demo host embedding the AAR |
| Catalog | packages/catalog |
SVG + GLB frames + person models |
Primary offline path: server (beear demo · beear serve).
BeeAR try-on ships as reusable libraries — download prebuilt artifacts from GitHub Releases:
| Lib | Artifact | Consumers |
|---|---|---|
@beear/tryon (npm) |
beear-tryon-0.4.0.min.js · full JS · npm tgz |
Web host, Android WebView, desktop |
com.beear:beear-webview (AAR) |
beear-webview-0.4.0.aar · POM |
Any Android app embedding try-on |
<script src="https://github.com/mergeos-bounties/BeeAR/releases/download/libs-v0.4.0/beear-tryon-0.4.0.js"></script>
<script>
console.log(BeeARTryOn.VERSION); // 0.4.0
</script># npm install from GitHub Release tarball (no npmjs login required)
npm install https://github.com/mergeos-bounties/BeeAR/releases/download/libs-v0.4.0/beear-tryon-0.4.0.tgz
# after public registry publish: npm install @beear/tryon// app/libs/beear-webview-0.4.0.aar
implementation(files("libs/beear-webview-0.4.0.aar"))
val view = BeeARWebView(this)
view.attach(this, BeeARConfig.loopback()) // or BeeARConfig.offlineAssets()
view.loadTryOn()cd packages/tryon-js && npm test && npm run build
node packages/android/scripts/sync-web-assets.mjs
cd packages/android && ./gradlew :beear-webview:assembleRelease
node scripts/release-libs.mjs
node scripts/release-libs.mjs --publish
# optional: --npm (needs NPM_TOKEN for registry.npmjs.org)
# optional: --npm-github --maven (needs GITHUB_TOKEN with write:packages)Docs: packages/tryon-js/README.md · packages/android/README.md
| Capability | Description |
|---|---|
| 3D person | Low-poly person_bust.glb with face anchor for glasses |
| GLB glasses | Multiple styles (aviator, wayfarer, round, cat-eye, sport, …) |
| 3D Studio | Orbit / zoom / auto-rotate try-on at /studio3d.html |
| Frame catalog | Glasses + accessories with SVG + GLB |
| PD fit | Pupil distance (mm) + landmark box |
| Compare | Side-by-side frame metrics |
| Offline demo | Catalog + fit + compare without a camera |
| Clients | Web, desktop, Android over shared libs |
|
 |
| Person + aviator GLB | Alternate orbit |
 |
 |
| Aviator on demo face | Wayfarer Black |
 |
 |
| Cat-eye Rose | Sport · PD 70 |
 |
 |
| Compare frames | VI UI |
cd packages\server
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
beear version
beear demo
beear catalog list
beear tryon fit aviator_gold --pd 64
beear serve --port 8860Then open:
- 3D person try-on: http://127.0.0.1:8860/studio3d.html
- Camera / demo photo: http://127.0.0.1:8860/
| Command | Purpose |
|---|---|
beear version |
Package version (0.4.0) |
beear demo |
Catalog + PD fit + compare + 3D person/GLB smoke |
beear catalog list [-c category] |
List frames |
beear catalog show <id> |
Frame detail |
beear catalog search <q> |
Search frames |
beear tryon fit <id> --pd 64 |
Fit estimate |
beear tryon compare <a> <b> |
Compare two frames |
beear serve |
FastAPI + web + studio3d |
- Frames: id, name, category, style, price, SVG, optional GLB.
- Person models: listed under
person_modelsinpackages/catalog/frames.json. - Fit uses PD (mm) and landmark box (synthetic when offline).
- API:
GET /api/catalog,GET /api/catalog/meta,GET /catalog/glb/{file}.
beear catalog list -c glasses
beear tryon compare aviator_gold wayfarer_black --pd 64
python packages\catalog\scripts\generate_3d_assets.pySystem architecture and workflow — full width. Open the HTML files for dark/light theme and export (PNG/SVG).
Generated with archify.
packages/
catalog/
glb/ # person_bust + glasses meshes
svg/ # 2D frame icons
frames.json # catalog + person_models
scripts/generate_3d_assets.py
server/src/beear/ # CLI, API, catalog, tryon
web/
index.html # camera / demo face try-on
studio3d.html # 3D person + GLB studio
assets/
tryon-js/ desktop/ android/
docs/
videos/beear-3d-tryon.mp4
screenshots/
diagrams/
scripts/render_3d_demo_video.py
- Prefer synthetic / consented demo faces in docs and CI.
- Do not commit real user camera captures without consent.
- Camera video stays in the browser; it is not uploaded by the default server.
- See docs/PRIVACY.md.
cd packages\server
pytest -q
ruff check src tests
beear demo
# assets + docs media
python ..\..\packages\catalog\scripts\generate_3d_assets.py
python ..\..\scripts\render_3d_demo_video.pyDemo app and AAR library live under packages/android/.
See packages/android/README.md for Gradle sync, camera consent, and WebView loopback.
Star → claim a bounty issue → PR to master → MRG 25–200.
See mergeos and docs/BOUNTY.md.