353 ·GitHub
What is this?
Paper Aquarium turns a hand-colored paper fish into a swimming 3D fish on a big screen: a child colors a printed sheet, photographs it with a phone, and the fish appears swimming in a web-based aquarium scene built with three.js.
Paper Aquarium turns a hand-colored paper fish into a swimming 3D fish on a big screen: a child colors a printed sheet, photographs it with a phone, and the fish appears swimming in a web-based aquarium scene built with three.js.Is this an app I install, or a website I host myself?It is a self-hosted web app: a plain Node.js server with zero dependencies serves the pages and a three.js scene, and you run it yourself to open it from a phone and a TV on the same network, or deploy it publicly behind a reverse proxy.
It is a self-hosted web app: a plain Node.js server with zero dependencies serves the pages and a three.js scene, and you run it yourself to open it from a phone and a TV on the same network, or deploy it publicly behind a reverse proxy.How do I get it running?Install Node 18+, run 'node server.js' — there is nothing else to install since it has zero dependencies and three.js is vendored in; set PORT, and the server prints the addresses of every network interface so you can open it from a phone or TV.
Install Node 18+, run 'node server.js' — there is nothing else to install since it has zero dependencies and three.js is vendored in; set PORT, and the server prints the addresses of every network interface so you can open it from a phone or TV.Do I need to buy anything to get fish swimming?Yes — the fish models aren't included in the repo; you buy the 'Coral Reef Fish Collection animated' pack on CGTrader, convert the FBX files to glTF with the provided PowerShell script, which yields about 12 colorable species (roughly 15 minutes including the download).
Yes — the fish models aren't included in the repo; you buy the 'Coral Reef Fish Collection animated' pack on CGTrader, convert the FBX files to glTF with the provided PowerShell script, which yields about 12 colorable species (roughly 15 minutes including the download).Does the photo-to-fish capture always work?It relies on four black markers printed in the corners of the sheet to locate it in the photo and undo the perspective; the markers must stay uncoloured, and a built-in capture test checks every sheet against skew, rotation and noise before you rely on it in the wild.
It relies on four black markers printed in the corners of the sheet to locate it in the photo and undo the perspective; the markers must stay uncoloured, and a built-in capture test checks every sheet against skew, rotation and noise before you rely on it in the wild.How do I put it online for others to use?Ship it as a single Docker container using the included Dockerfile and docker-compose.prod.yml; it has no proxy of its own, so HTTPS, the domain and the certificate are handled by Traefik through an external web network, while the purchased fish-model pack is mounted as a volume rather than baked into the image.
Ship it as a single Docker container using the included Dockerfile and docker-compose.prod.yml; it has no proxy of its own, so HTTPS, the domain and the certificate are handled by Traefik through an external web network, while the purchased fish-model pack is mounted as a volume rather than baked into the image.Who can see or delete an aquarium?There are no accounts: a 10-character code/link lets anyone watch the tank or add fish, while deleting or renaming needs a separate password; that password travels in a plain-text header, so HTTPS through a reverse proxy is mandatory for any public deployment.
There are no accounts: a 10-character code/link lets anyone watch the tank or add fish, while deleting or renaming needs a separate password; that password travels in a plain-text header, so HTTPS through a reverse proxy is mandatory for any public deployment.What's covered by the MIT license and what isn't?The code and the author's own backgrounds are MIT, but the fish models themselves are excluded — they come from a separately purchased, non-redistributable pack, and the traced silhouettes used for the coloring sheets are derived 2D contours, not the models.
The code and the author's own backgrounds are MIT, but the fish models themselves are excluded — they come from a separately purchased, non-redistributable pack, and the traced silhouettes used for the coloring sheets are derived 2D contours, not the models.How does the aquarium keep fish from bunching up at the screen edges?The swimming volume follows the camera frustum instead of a fixed box, so fish near the far wall don't crowd toward the center of the screen the way they would in a box.
The swimming volume follows the camera frustum instead of a fixed box, so fish near the far wall don't crowd toward the center of the screen the way they would in a box.What happens when a drawing gets deleted?Deleted fish and aquariums move to a trash folder instead of being erased immediately, and are only permanently removed after 30 days (AQUATRASHDAYS) so an accidental delete can still be recovered.
Deleted fish and aquariums move to a trash folder instead of being erased immediately, and are only permanently removed after 30 days (AQUATRASHDAYS) so an accidental delete can still be recovered.Can I show the aquarium on a TV while a kid drives it from a phone?Yes — 'Open on another screen' in the menu generates a temporary 5-digit code valid for 5 minutes for the TV; a screen opened that way never pops the menu itself, keeping the phone as the only control.
Yes — 'Open on another screen' in the menu generates a temporary 5-digit code valid for 5 minutes for the TV; a screen opened that way never pops the menu itself, keeping the phone as the only control.What languages does it support?Russian, English and Polish, switching automatically to the device's language on first visit; the printable coloring sheets are also trilingual, though the corner markers stay identical across all versions.
Russian, English and Polish, switching automatically to the device's language on first visit; the printable coloring sheets are also trilingual, though the corner markers stay identical across all versions.What are similar projects?clay-safari, scam-with-your-friends-web, image-to-3d-pipeline, Jelly-Baby, Stronghold-Protocol, floorplan-3d, Hermes3D, empire
clay-safari, scam-with-your-friends-web, image-to-3d-pipeline, Jelly-Baby, Stronghold-Protocol, floorplan-3d, Hermes3D, empire