3dboxes [TOOL] box3d — Automatic 3D box art generator

[raffaelsilva]

Hey everyone,

 

Time to come clean about something.

Over the past few weeks I've been dropping box art images in various threads — Red Earth, a few other titles — without really explaining what I was doing. Some of them had weird issues: the spine would bleed slightly outside the box edge, logos weren't sitting right, the colors felt off. A few of you pointed things out and I was vague about where the images were coming from. Sorry about that.

Those were all test outputs. I was building a tool, and this community's sharp eyes were genuinely helping me catch things I stopped seeing after staring at the same pixels for too long. So thank you for that, even if you didn't know you were helping.

The tool is called box3d, and it's almost ready. Here's what it actually is.

 

What it does

box3d takes a flat piece of arcade or game cover art and automatically wraps it into a 3D box image — the kind you'd use in a frontend like ES-DE, LaunchBox, or just for display purposes. It handles the front face, the spine, logos, shading, everything. You drop your covers in a folder, run one command, and come back to a folder full of finished boxes.

No Photoshop. No manual layer work per game. The whole point is that once you've set it up for a system, you just feed it covers and it does the rest.

 

The three box shapes (profiles)

This is probably the most important thing to explain. Different arcade and retro systems had very different physical shapes. A Neo Geo MVS cartridge looks nothing like a generic arcade PCB box, which looks nothing like a DVD case. So the tool has a profile system — each profile is a different box shape, with its own 3D template and geometry.

Right now there are three:

---

mvs — Neo Geo MVS cartridge

This is the one most of you have seen in my test posts. The MVS shell has that very distinctive look — the black plastic top tab, the side connector rails with the SNK text, the slightly tapered front face. It's immediately recognizable to anyone who's handled real MVS carts.

The geometry on this one was the trickiest to dial in because the front face isn't a clean rectangle in the template — it has a slight lean to it that had to be matched exactly in the perspective mapping. The Red Earth test was running on this profile.

Template dimensions: 703 × 1000 px

---

arcade — Generic arcade PCB box

A thicker, squarer box — the kind you'd use for general arcade board art, PCB collections, or any game that doesn't have a natural home in the MVS or DVD shape. The spine on this one is slightly wider than the MVS, which gives you more room for logos and marquee art. The shading on the edges is subtler, which works well with bold flyer art that already has a lot going on.

This is probably the most versatile profile — I've been using it for anything that doesn't belong to a specific system.

Template dimensions: 665 × 907 px

---

dvd — DVD/media case

A slimmer profile, closer to a standard DVD jewel case shape. The spine is noticeably narrower than the other two (about 30% thinner than the arcade profile), so the logo sizing is adjusted down automatically. Useful if you want a more "collection shelf" look rather than hardware-accurate arcade style. Also works surprisingly well for console game art.

Template dimensions: 633 × 907 px

 

How the spine works — the part I'm most proud of

Every box needs a spine, and painting one manually for each game in a collection of hundreds is not realistic. So box3d generates the spine automatically from the cover art itself.

It takes the left edge of your cover (about 20% of the width), blurs it heavily, darkens it, and uses that as the spine background. The result is a spine that always feels visually connected to the front — same color temperature, same mood — without you having to touch anything. Dark blue cover gives you a dark blue spine. Warm orange cover gives you a warm spine. It just works.

On top of that generated background, it places up to three logos on the spine:

• Top logo — a fixed image you put in data/inputs/logos/top/. One file, used on every box for that run. Perfect for a system badge, publisher mark, whatever you want anchoring the top of the spine.
• Game marquee — the game's own logo art, automatically matched by filename to the cover. If you have redearth.webp as your cover, it looks for redearth.png (or any image format) in the marquees folder.
• Bottom logo — same idea as the top, but for the rodapé. Studio seal, "Classics" badge, platform label — your call.

All three are completely optional. If the file isn't there, that slot is just empty. No errors, no placeholders.

 

Running it

The simplest possible run, from the project folder:

bash

./run.sh

That picks up the default profile (mvs) and processes everything in your covers folder. To specify a profile:

bash

./run.sh --profile arcade
./run.sh --profile dvd
./run.sh --profile mvs

You can also tune the spine appearance per run:

bash

# Softer spine — less blur, lighter darkening
./run.sh --blur-radius 12 --darken 100

# More aggressive darkening for covers with busy left edges
./run.sh --darken 220

# Color correction if your covers are scanning warm
./run.sh --rgb 0.95,1.0,1.05

# Process faster on a machine with more cores
./run.sh --workers 8

# Test a run without writing any files
./run.sh --dry-run --verbose

The --verbose flag shows you every step in the log, which is useful when you're dialing in a new batch or debugging a cover that came out wrong.

 

What you need to run it

• Python 3.11 or newer
• ImageMagick 7 (the magick command — standard on most Linux distros, available on macOS and Windows too)
• Pillow and NumPy (pip install pillow numpy)

On Fedora/Bazzite: sudo dnf install ImageMagick On Debian/Ubuntu: sudo apt install imagemagick

 

Folder structure

data/
├── inputs/
│   ├── covers/           ← your cover art goes here (jpg, png, webp, anything)
│   ├── marquees/         ← game logos, named the same as the cover file
│   ├── logos/
│   │   ├── top/
│   │   │   └── logo.png  ← top spine logo (optional, one per run)
│   │   └── bottom/
│   │       └── logo.png  ← bottom spine logo (optional, one per run)
│   └── templates/
│       ├── mvs.png       ← MVS shell template
│       ├── arcade.png    ← arcade box template
│       └── dvd.png       ← DVD case template
└── output/
    └── converted/        ← finished .webp files land here

 

What's still being worked on

The core pipeline is solid. What's left is mostly polish:

• A few edge cases with covers that have very bright or white left edges (the auto-spine can wash out — working on a detection and correction for that)
• Possibly a per-game config override for the rare cover that needs manual adjustment
• More template shapes