Printful DTG Binary Alpha (Bitmapping)

PreviousNext

Matte semi-transparent pixels onto garment bgColor so Printful underbase has no grey halo (ZLY-1512)

Overview

Printful DTG binary alpha (ZLY-1512, often called “bitmapping”) fixes a print defect on garments fulfilled by Printful’s direct-to-garment (DTG) process.

Printful keeps our PNG transparency and lays down a white underbase only where there is ink. That underbase opacity follows pixel coverage — so pixels with partial alpha get a partial underbase and print as a white/grey halo or blurry fade along soft edges.

The fix is not a plain 1-bit threshold (which makes jagged edges). Instead we matte only semi-transparent pixels onto the product’s known garment color (bgColor), then force alpha to fully transparent or fully opaque. Soft edges stay smooth because antialiasing is baked into the RGB color.

This applies to apparel / DTG (transparency + underbase). It does not help posters on white paper — there is no fabric underbase problem there.

The Problem

flowchart LR subgraph before [Before ZLY-1512] A[PNG with soft alpha edges] --> B[Printful underbase from coverage] B --> C[Partial alpha → partial underbase] C --> D[White / grey halo on fabric] end
ApproachWhy we rejected / limited it
Flatten entire image onto garment colorPrints a full opaque rectangle — silhouette lost
Plain 1-bit alpha thresholdJagged edges; throws away antialiasing
Same treatment for postersNot needed — white paper, no DTG underbase

The Solution

Core helper: binarizeAlpha in packages/merch/img-gen/src/img-processing/binarize-alpha.ts.

For each pixel (alpha 0–255), with defaults lowerEpsilon = 3, upperEpsilon = 252:

AlphaResult
α ≤ 3Fully transparent (α = 0) — fabric shows, no ink
3 < α < 252Blend out = α·C + (1-α)·bg, then α = 255
α ≥ 252Fully opaque (α = 255) — RGB unchanged

If bgColor is missing/empty, or the image has no alpha channel, the function no-ops (returns the buffer unchanged). Guessing a background would bake a wrong fringe into the print.

flowchart TD In[RGBA image + product bgColor] --> Check{bgColor set and has alpha?} Check -->|no| OutSame[Return unchanged] Check -->|yes| Loop[Per pixel] Loop --> Low{α ≤ 3} Low -->|yes| Clear[α = 0] Low -->|no| High{α ≥ 252} High -->|yes| Opaque[α = 255] High -->|no| Matte[Blend RGB onto bgColor, α = 255] Clear --> Done[PNG with binary alpha] Opaque --> Done Matte --> Done

Where It Runs

Binarization is wired at the source of soft alpha and again on the print file:

StageHooklogLabel
After the design mask (generation)applyTemplateMask(..., bgColor?) → applyMaskToImageafter-alpha-mask
After logo/text overlaycompositeOverlay(..., bgColor?)after-overlay
Final print file (before DPI / upload)upscalePrintArt → binarizeAlphaprint-file

Call sites that pass catalog bgColor (or flattenBgColor on generation):

  • AI generation overlay path (process-ai-image / generate-ai-art)
  • Storefront / admin render (render route, render-garment, seller-store, admin render-preview)
  • Print upscale + fulfillment dispatch (upscale-print-art, admin upscale, dispatch)

Not wired (no catalog garment color / not a print path): benchmark, simulation, design-request.

Pre-generation template flatten (ensureOpaqueImage / flattenBgColor on the AI template) already existed and is unchanged — that is a different step (make the template opaque before the model runs).

Product bgColor Requirement

Apparel catalog products need a correct background / garment color in admin (catalog product bgColor). That value is the fabric color used for matting.

  • Set in merch admin on the catalog product (same field used historically for flatten defaults).
  • If missing on a print path, binarize is skipped and soft alpha may still reach Printful → halo risk.
  • Color may be any string Sharp accepts (hex, rgb(), named).

Key Code Paths

Package / fileRole
@zooly/merch-img-gen → binarize-alpha.tsCore matte + binary alpha
remove-background-corners.tsCalls binarize after mask
composite-overlay.tsCalls binarize after overlay
packages/merch/srv/src/upscale-print-art.tsFinal print-file pass
packages/merch-fulfillment/srv/src/dispatch.tsPasses catalogProduct.bgColor into upscale before Printful

Verification Notes

  • Soft edges on dark garments should look smooth on-screen and on DTG prints, without a white/grey fringe.
  • Fully transparent areas outside the design must stay transparent (no solid printed rectangle).
  • Products without bgColor should log / no-op rather than invent a color.
  • Posters: behavior unchanged; binary alpha is harmless but not the poster quality lever.