prism-mosaic
Marcelino Justo1. Executive Summary This program builds a web product that compiles a licensed raster artwork into a manufacturable, wall-mounted, 3D relief LEGO mosaic using only official elements and colors from versioned catalog snapshots, constrained by a fixed MVP part whitelist (Appendix A) and three exact stud-grid tiers: 32×32, 48×48, 64×64 studs. The core technical stance is a constrained compiler pipeline: semantic and perceptual analysis → relief and palette-constrained quantization → primitive and bounded-SNOT proposal → global discrete optimization → physical legality and assembly validation → ranked candidate designs → export bundle (placement, depth, BOM, steps, validation, renders, manifests). Primary success measure: visual fidelity under hard physical and catalog constraints, with cost and rarity as secondary penalties. Reproducibility is a first-class requirement: every export must be rebuildable from pinned catalog snapshots, model weights, solver configs, and scoring rules. MVP delivery path: (1) deterministic compiler + validators on synthetic and fixture inputs, (2) catalog enforcement + backplane specs, (3) solver + ranking, (4) ML-assisted prioritization trained on synthetic data plus a small expert-labeled set, (5) website job lifecycle and export, (6) observability and acceptance hardening. 1. Problem Framing and Invariants Primary optimization objective Maximize perceptual fidelity of the visible assembled mosaic to the normalized source artwork under: • official discrete color palette (from ColorPaletteSnapshot) • stud-grid resolution per tier • bounded relief depth and backplane structural rules • whitelist-only parts Operationalized as a scalarized score (see §13): weighted sum of perceptual loss (e.g., LPIPS-like, SSIM, edge/structure terms) plus semantic saliency-weighted regions (faces, type, logo contours). Secondary optimization objectives • Minimize instruction complexity (step count, ambiguous attachments, reorientation count). cope In scope (MVP) • Web upload of licensed artwork (with provenance gate). • Tier selection: 32×32, 48×48, 64×64. • Pipeline: analysis → compilation → validation → ranked candidates → human/operator review option → export. • Artifacts: placement map, per-cell depth map, BOM, assembly steps, validation report, review renders, run manifest, config bundle. • Official elements only via snapshots + whitelist. • Bounded SNOT via template patches. • Synthetic pretraining + small expert labels for ranking/prior modules. • Standardized wall-mount backplane per tier. Out of scope for MVP (see §4) 1. Non-Goals • Arbitrary resolution or non-square grids. • Non-LEGO or custom 3D-printed elements. • Unlimited palette (e.g., RGB free optimization). • Primary optimization for minimal cost or minimal piece count. • Guaranteed photographic match in all regions regardless of brick vocabulary (soft failures become ranked or needs_review). • Full AR “build in your room” (could be future). • Retail/partner automatic inventory ordering (export is BOM; purchasing is external). 1. Assumptions ID Assumption If false A1 A curated catalog snapshot format can be ingested (BrickLink-like part/color IDs or internal normalized IDs with stable mapping). Lock import adapter and ID scheme in Gate 2. A2 Physical legality can be approximated by a connection graph + collision model validated against simplified LEGO geometry (not necessarily full CAD for MVP). Increase validation fidelity in later phase; gate “first physical build” with real build. A3 MVP whitelist in Appendix A is the sole allowed superset of parts at runtime. Enforcement is fatal on violation. A4 Expert labelers can provide 100–500 high-quality examples (order-of-magnitude; exact N is a parameter). Reduce ML scope to ranking only; more synthetic. A5 Users possess rights to upload artwork; product does not substitute legal review—workflow records attestations. Legal review external; system stores metadata only. A6 Renders are indicative; final fidelity ground truth is physical build spot checks. Label render vs photo discrepancy as known risk. 1. System Architecture Logical architecture [Web Client] <-> [API Gateway / BFF] | v [Job Orchestrator + State Store] | +———––+———––+ v v v [Artifact Store] [Queue/Workers] [Auth/Billing - future] | +———––+———––+ v v v [Ingest/Normalize] [Analysis ML] [Compiler+Solver] | | | v v v [Provenance svc] [Feature maps] [Validators] | v [Export/Render] Subsystem boundaries Subsystem Responsibility Client Upload, tier selection, review UI, download export. API Auth, job CRUD, signed URLs, idempotent job creation. Orchestrator State machine, retries, pinning manifests. Workers CPU/GPU jobs: analysis, compile, validate, render. Artifact store Versioned blobs + content-addressed hashes. Catalog service Read-only snapshots; no runtime edits. Technology stance (non-prescriptive) • API: HTTP + JSON (or gRPC internally); jobs async. • Workers: Containerized; GPU optional for analysis/inference. • Storage: Object store for artifacts; relational DB for job metadata.
Comments (0)
Sign in to leave a comment
System Requirements
System Requirements Document (SRD)
Project Name: prism-mosaic
1. Introduction
The prism-mosaic project aims to deliver a web-based platform for creating professional-grade, wall-mounted, 3D relief LEGO mosaics. Designed for anyone who desires professional-grade results, the system enables the transformation of licensed raster artwork into manufacturable designs using official LEGO elements and constrained stud-grid tiers.
This document outlines the system requirements for prism-mosaic, ensuring reproducibility, visual fidelity, and adherence to strict physical and catalog constraints. The platform will provide an intuitive user experience with guided recommendations, making professional-grade mosaic creation accessible to all users, regardless of their expertise level.
2. System Overview
The prism-mosaic system is built around a deterministic compiler pipeline that processes raster artwork through semantic and perceptual analysis, relief quantization, and optimization under catalog constraints. The pipeline ensures manufacturable outputs by validating physical legality and assembly rules.
Key features include:
- Uploading licensed artwork with provenance verification.
- Selecting stud-grid tiers (32×32, 48×48, 64×64).
- Generating ranked candidate designs based on perceptual fidelity and structural constraints.
- Exporting artifacts such as placement maps, depth maps, BOMs, assembly steps, validation reports, and renders.
- Providing contextual tooltips and guided recommendations during tier selection and review stages.
The system architecture is modular, with subsystems for ingestion, analysis, compilation, validation, and export. Observability and reproducibility are first-class requirements, ensuring every export is rebuildable from pinned catalog snapshots, model weights, solver configurations, and scoring rules.
3. Functional Requirements
As User:
- I should be able to upload licensed artwork for mosaic creation.
- I should be able to select from three stud-grid tiers: 32×32, 48×48, and 64×64.
- I should receive ranked candidate designs based on visual fidelity and manufacturability.
- I should be guided through the review process with tooltips and recommendations.
- I should be able to download export bundles containing placement maps, depth maps, BOMs, assembly steps, validation reports, and renders.
As Admin:
- I should be able to manage catalog snapshots and enforce whitelist constraints.
- I should be able to monitor system observability and acceptance metrics.
4. User Personas
Hobbyist:
Casual users interested in creating LEGO mosaics for personal projects or gifts. They value ease of use and guided recommendations during the design process.
Professional Designer:
Users with advanced design knowledge who require high-fidelity outputs for exhibitions, commissions, or commercial purposes. They value precision, reproducibility, and detailed export artifacts.
Business User:
Organizations or teams creating mosaics for branding, marketing, or large-scale installations. They value scalability, cost-effectiveness, and structured workflows.
General User:
Anyone who wants to create professional-grade 3D mosaics, regardless of their prior experience. They value intuitive guidance and high-quality results.
5. Visuals Colors and Theme
Color Palette:
The prism-mosaic platform will feature a vibrant yet professional color scheme inspired by LEGO’s playful yet structured aesthetic:
- Background:
#E8F0F7(soft pastel blue for a calming workspace) - Surface:
#FFFFFF(clean white for clarity and focus) - Text:
#2C3E50(deep navy for high readability) - Accent:
#FF5733(vivid orange-red for interactive elements and highlights) - Muted Tones:
#95A5A6(cool gray for secondary elements and tooltips)
6. Signature Design Concept
The prism-mosaic homepage will feature an immersive mosaic creation experience.
Concept Details:
- Dynamic Artwork Upload: Users can drag-and-drop their artwork into a large, central upload zone that animates with a ripple effect upon interaction.
- Live Mosaic Preview: As users upload artwork, the homepage dynamically generates a low-resolution mosaic preview that updates in real-time as users adjust tier settings.
- Interactive Tier Selector: A slider control allows users to toggle between 32×32, 48×48, and 64×64 grids, with the preview adapting instantly to reflect changes.
- Guided Recommendations: Contextual tooltips appear as users interact with settings, offering suggestions like "This tier works best for high-detail images."
- Playful LEGO Aesthetic: The background subtly mimics LEGO studs, with animations that resemble bricks snapping into place as users navigate the interface.
- Interactive Assembly Animation: The homepage features a mesmerizing animation of LEGO bricks assembling into a mosaic, giving users a visual cue of the platform’s capabilities.
This bold, interactive design ensures users are immediately engaged and excited about the mosaic creation process.
7. Non-Functional Requirements
- Performance: The system must process uploads and generate previews within 5 seconds for images up to 10MB.
- Scalability: Support concurrent job processing for up to 100 users.
- Security: Ensure artwork uploads are encrypted and provenance metadata is securely stored.
- Reproducibility: All outputs must be rebuildable from pinned catalog snapshots and configuration bundles.
- Accessibility: The UI must meet WCAG 2.1 AA standards for accessibility.
8. Tech Stack
Frontend:
- React for Web
Backend:
- Python
- FastAPI
Database:
- MySQL or MariaDB (using Alembic for migrations)
AI Models:
- GPT 5.4 for user-friendly responses
- Claude 4.6 Opas for academic or coding work
- Google Nano Banana for image generation
AI Tools:
- Litellm for LLM Routing
- Langchain
Local Orchestration:
- Docker
- docker-compose
Server-Side Orchestration:
- Kubernetes
9. Assumptions and Constraints
Assumptions:
- Users possess rights to upload artwork; the system will store metadata but not perform legal reviews.
- Physical legality can be approximated using simplified LEGO geometry models.
- The MVP whitelist in Appendix A is the sole allowed superset of parts at runtime.
Constraints:
- Only official LEGO elements from versioned catalog snapshots are allowed.
- Mosaic designs are constrained to square grids of fixed resolutions (32×32, 48×48, 64×64).
- The system does not optimize for minimal cost or piece count.
10. Glossary
- MVP: Minimum Viable Product
- SNOT: Studs Not On Top, a LEGO building technique
- BOM: Bill of Materials
- LPIPS: Learned Perceptual Image Patch Similarity, a metric for visual fidelity
- WCAG: Web Content Accessibility Guidelines
This document ensures that the prism-mosaic platform is designed to meet the needs of its diverse user base while adhering to strict technical and physical constraints.
Transform Your Art Into 3D LEGO Mosaics
From licensed artwork to professional-grade relief designs in minutes. Upload, customize, and export manufacturable mosaic blueprints.
See Your Mosaic Come to Life
Upload your licensed artwork and watch as prism-mosaic transforms it into a manufacturable LEGO relief design in real time.
Choose Your Stud-Grid Tier
Select the resolution that matches your project scope — from compact personal pieces to large-scale installations.
Perfect for small displays, gifts, and personal projects. Ideal for hobbyists getting started with mosaic design.
Learn More→Balanced detail and scale for exhibitions, commissions, and high-fidelity reproductions.
Learn More→Maximum resolution for large-scale installations, branding, and commercial-grade mosaic walls.
Learn More→Everything You Need to Create Professional Mosaics
From upload to export, prism-mosaic handles the entire pipeline with precision, reproducibility, and visual fidelity.
Upload Licensed Artwork
Drag and drop your licensed raster artwork with built-in provenance verification for secure, authorized mosaic creation.
Instant Mosaic Generation
Our deterministic compiler pipeline transforms your artwork into a manufacturable LEGO mosaic design in seconds.
Multiple Tier Options
Choose from three stud-grid resolutions — 32×32, 48×48, or 64×64 — to match your project scope and detail needs.
Ranked Design Candidates
Receive multiple candidate designs scored by perceptual fidelity and structural integrity, so you always pick the best output.
Detailed Export Artifacts
Download complete bundles with placement maps, depth maps, BOMs, validation reports, and high-fidelity renders.
Assembly Step Guides
Follow clear, step-by-step assembly instructions generated for every design to build your mosaic with confidence.
Reproducible Builds
Every export is fully rebuildable from pinned catalog snapshots, model weights, and solver configurations.
Professional Validation
Automated structural and catalog constraint checks ensure your design is physically legal and manufacturable.
Built for Every Creator
Whether you are a weekend hobbyist or managing enterprise installations, prism-mosaic adapts to your workflow.
Hobbyist
Casual creators making LEGO mosaics for personal projects, gifts, or weekend fun. Values simplicity and guided recommendations.
- Guided step-by-step creation
- Beginner-friendly tier selection
- Quick preview and export
- Tooltip recommendations
Workflow Highlight
Upload artwork → Pick a tier → Preview → Download your mosaic bundle in minutes
Professional Designer
Advanced users requiring high-fidelity outputs for exhibitions, commissions, or commercial use. Demands precision and reproducibility.
- High-resolution 64×64 grids
- Ranked candidate comparison
- Detailed export artifacts
- Reproducible builds
Workflow Highlight
Fine-tune candidates → Compare fidelity scores → Export placement maps, BOMs, and renders
Business User
Teams and organizations creating mosaics for branding, marketing campaigns, or large-scale installations at scale.
- Scalable batch workflows
- Cost-effective BOM planning
- Structured team collaboration
- Assembly step guides
Workflow Highlight
Upload brand assets → Select tier for installation size → Review → Distribute assembly guides
Admin
Platform administrators managing catalog snapshots, whitelist constraints, and system-wide observability metrics.
- Catalog snapshot management
- Whitelist constraint enforcement
- Observability dashboards
- Acceptance metric monitoring
Workflow Highlight
Monitor pipeline health → Manage catalogs → Enforce validation rules → Review metrics
How It Works
Five simple steps from artwork to a professional-grade LEGO mosaic export bundle.
What Our Creators Say
Join thousands of creators building professional LEGO mosaics with prism-mosaic
“prism-mosaic transformed my favorite photo into a stunning 3D LEGO mosaic. The guided recommendations made the whole process effortless, even for a first-timer.”
“The 64×64 tier delivers incredible fidelity. I use the detailed export artifacts and assembly steps for every commission now. Reproducibility is flawless.”
“We created branded LEGO mosaics for our office installations. The ranked candidate system let us pick the perfect design every time. Our team loves it.”
Ready to Create Your Mosaic?
Join thousands of creators building professional LEGO mosaics with our deterministic compiler pipeline.
No comments yet. Be the first!