Apoculus

Apoculus - MIT License Copyright (c) 2025 NQR 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.

---

THIRD-PARTY COMPONENTS This software includes third-party libraries: • Depth Anything V2 (Apache License 2.0) AI depth estimation model https://github.com/DepthAnything/Depth-Anything-V2 • ONNX Runtime Web (MIT License) WebGPU/WebAssembly inference engine https://github.com/microsoft/onnxruntime • JSZip (MIT License, dual-licensed MIT OR GPL-3.0) ZIP file creation library https://github.com/Stuk/jszip See LICENSES-THIRD-PARTY.md and NOTICE for complete attribution.

There are several ways to prepare images for depth mapping in Apoculus. Choose the method that works best for your workflow:

🤖 AI-Powered (Easiest)

Depth Anything V2 (Built-in)

Upload any photo and let the AI predict depth automatically. Works great for portraits, landscapes, and complex scenes. Just select "Depth Anything V2 (AI)" from the Depth Algorithm dropdown.

✓ Best for photos and natural scenes
✓ No preparation needed
✓ Model loads automatically on first use (~97MB)

🎨 Manual Grayscale Depth Maps

Simple Silhouettes

Create a grayscale image where white = foreground (near) and black = background (far). Works great for logos, icons, and simple graphics.

Layered Depth with GIMP/Photoshop

Create complex multi-depth scenes:

1. Separate your image into layers (foreground, midground, background)
2. Create silhouettes of each layer
3. Assign different grayscale values:
   • Closest objects: White (255)
   • Middle distance: Mid-gray (128)
   • Far background: Dark gray (64)
   • Sky/background: Black (0)
4. Flatten to a single grayscale image
5. Optional: Use Gaussian blur to smooth transitions between layers

3D Software Export

If you're working with 3D models in Blender, Maya, or similar tools, you can render a depth pass (Z-depth) and export it as a grayscale image. This gives you precise control over depth based on actual 3D geometry.

📱 Mobile Apps & Web Tools

Mobile Apps

DepthMaker - iOS/Android app that generates depth maps from photos using portrait mode or AI

Web-Based Tools

Depth Map Extractor - Extract depth data from images with depth information

Depthy - Create depth maps from photos with interactive painting tools

3D Photo Inpainting - AI-based depth estimation from single photos

💡 Tips for Best Results

• High Contrast: Images with clear brightness differences produce better 3D effects
• Smooth Gradients: Use Gaussian blur on depth transitions to avoid "sparkle" artifacts
• PNG Transparency: Transparent backgrounds automatically stay at depth 0 (far)
• Depth Gamma: Adjust 0.6-1.4 to control how midtones map to depth
• Invert Depth: Use for white-on-black images or reversed depth perception
• Shadow-Aware Algorithm: Use for photos with strong shadows or uneven lighting

🎯 Quick Workflow Recommendations

For photos: Use Depth Anything V2 (AI)

For logos/graphics: Create simple grayscale silhouettes

For layered scenes: Use GIMP/Photoshop with multiple gray levels

For 3D projects: Export Z-depth pass from your 3D software

For mobile workflow: Use DepthMaker app, then upload here

Remember: Depth maps are just grayscale images where brightness = distance from viewer. White = close, black = far. Everything else is creative freedom!

What is an Autostereogram?

An autostereogram (also called a "Magic Eye" image) is a 2D pattern that reveals a hidden 3D scene when viewed with the right technique. By crossing or diverging your eyes, you can see text, images, and shapes floating at different depths. Perfect for hiding clues in ARGs!

👀 How to View Stereograms

Cross-Eye Method (Easier):

1. Hold image at arm's length
2. Cross your eyes slightly until you see three overlapping images
3. Focus on the middle image - the 3D will appear with depth inverted

Parallel Method (Wall-Eye):

1. Hold image close, then slowly move it away
2. Look "through" the image as if staring at something far behind it
3. The 3D scene will snap into focus

⚠️ For ARG Creators: About 5-10% of people cannot see stereograms due to vision conditions. Always provide an alternative way to access hidden content! Consider linking to Apochron (digital autostereogram viewer) as a backup, or include hints that the content is 3D.

🎯 Creating Better Still Image Stereograms

Avoid Horizontal Stratification (Critical!):

• Problem: Long horizontal strings can create visible horizontal bands that break the illusion
• Solution: Rotate text, mix upper and lowercase letters, break long words across multiple lines, or use shorter phrases
• Example: Instead of "PASSWORD IS HIDDEN", use "Password\nIs\nHidden" rotated 45 degrees

Pattern Settings for Quality:

• Pattern Width: Use prime numbers (53, 59, 61, 67, 71, 73, 79, 83, 89, 97) to minimize tiling artifacts. Default 73px is optimal.
• Pattern Density: 4-5 dots per strip balances detail vs. viewability. Higher = more detail but harder to see.
• 3D Effect Strength: 0.6-0.8 is easiest to view. Higher values create dramatic depth but may cause eye strain.

Text Depth Tips:

• Keep text depth between 10-30 for comfortable viewing
• Space multiple text layers 10-15 depth units apart for clear separation
• Use bold, thick fonts (Arial Black, Impact) for better visibility
• Larger font sizes (100-200px) work best for 3D pop-out

🤖 Using Depth Anything V2 (AI) for Photos

Smoother Depth (Avoid "Sliced Layers"):

By default, AI-generated depth maps can look "sliced" into distinct layers. To create smoother, more natural depth:

• Lower the Depth Gamma: Set to 0.7-0.8 to compress depth differences
• Reduce 3D Effect Strength: Set to 0.5-0.6 for subtler, smoother transitions
• Increase Depth Level: Set to 60 for more depth resolution
• Pre-process the depth map: Open the exported depth map in an image editor and manually fix layers or trasparent objects like glasses, then upload as a manual depth map
• Use Shadow-Aware algorithm: For photos with dramatic lighting, this can produce smoother results than AI

What to Avoid:

• Very high depth values (>40) with complex images - creates extreme pop-out that's hard to focus on
• Low-contrast images - auto-level helps, but starting with good contrast is better
• Images with very fine details - they may create "sparkle" noise in the pattern

🎬 Creating Video Stereograms (Animated)

Workflow:

1. Add a + Video layer in Apoculus
2. Use the frame controls to scrub through your video
3. Click ⬇ Export Video Frames to download all frames as PNGs in a ZIP file
4. Extract the ZIP and use ffmpeg to compile frames into a video

FFmpeg Commands:

Recommended Software:

• FFmpeg: ffmpeg.org/download.html - Command-line video processing
• HandBrake: handbrake.fr - GUI video encoder (can import image sequences)
• DaVinci Resolve: Free video editor - Import PNGs as image sequence

🎭 ARG Use Cases & Ideas

• Hidden Passwords/Codes: Embed text at depth 20-30, surround with noise patterns at depth 0
• Layered Clues: Multiple text strings at different depths reveal a sequence or cipher key
• Photo Puzzles: Use AI depth on a significant photo - players must view it stereoscopically to see hidden elements
• Video Messages: Animated stereogram reveals a message only when viewed correctly while playing
• Gatekeeper Puzzle: "Can you see in 3D?" as skill check - code visible only to those who can view stereograms
• Red Herring Misdirection: Surface pattern looks meaningful but real clue is in the 3D depth

💡 Pro Tip: Always test your stereograms with multiple people before deploying in an ARG. What's easy for you to see might be impossible for others. Provide hints like "cross your eyes" or "look for the 3D message" to guide players.

🔗 Related NQR Tools

• Apochron - Animated autostereogram viewer for players who struggle with static images
• SpectroGhost - Hide messages in audio spectrograms
• Ghostmark - Hide images inside other images (steganography)
• Inknigma - Multi-layer invisible ink and steganography

Made with 💙 by NQR Labs | Join Discord