DEV Community: virse

How to convert product photo to line art without tracing cast shadows or glare in Python

virse — Thu, 15 Oct 2026 17:26:57 +0000

AI-generated illustration: A glossy black coffee grinder beside an unshaded contour drawing on white vellum paper and steel calipers.

To convert product photo to line art without tracing cast shadows or surface glare, you must isolate and flatten illumination gradients in the lightness channel before running any gradient or contour detector. When you feed an unconditioned studio packshot straight into cv2.Canny or a grayscale color-dodge filter, the algorithm treats every bright softbox reflection and tabletop shadow boundary as a physical edge of the product.

This article was drafted with AI assistance, every Python snippet and metric below was executed locally with OpenCV and NumPy, and the author is affiliated with Virse, whose line art tool is referenced once below; product hardware scenarios in the text are hypothetical examples.

Why do standard scripts fail when you convert product photo to line art?

Standard edge-detection scripts fail when you convert product photo to line art because pixel-gradient operators measure local luminance contrast (dI/dx and dI/dy) without knowing whether a brightness jump comes from a physical housing seam or a studio lamp reflection. In a real product photograph, lighting artifacts often produce steeper pixel gradients than the actual part geometry you want to draw.

AI-generated illustration: Specular rim glare on brushed aluminum and a soft tabletop shadow that standard edge detectors misread as physical seams.

As the OpenCV Canny Edge Detection documentation explains, the Canny pipeline smooths the image with a Gaussian filter, computes Sobel gradient magnitudes in the horizontal and vertical directions, thins those gradients with non-maximum suppression, and links surviving pixels using lower and upper hysteresis thresholds. That pipeline works well when you photograph flat matte objects under diffuse shadowless domes. It breaks down as soon as you point a camera at consumer hardware made of brushed aluminum, glossy ABS plastic, glazed ceramic, or glass.

Consider what happens across three common surface zones on a tabletop product shot:

Specular reflection islands on bevels and curves: A softbox reflecting off a chamfered aluminum rim or a curved ceramic body creates a localized region where luminance clips near 255 and color saturation drops near 0. The boundary between that blown-out highlight and the surrounding midtone metal has a massive Sobel gradient. Standard Canny traces a closed oval ring around the highlight, leaving your drawing with what looks like a physical sticker or dent in the middle of a smooth panel.
Tabletop cast shadows and contact penumbras: Where the product rests on an acrylic sweep or wooden table, directional key lights cast a shadow with a soft penumbra. If the shadow gradient is steep enough to cross Canny's lower hysteresis threshold, the output drawing gets a jagged double baseline underneath the feet of the device.
Low-contrast internal seams in recessed areas: While glare produces false-positive lines, recessed button wells, rubber gaskets, or dark-on-dark parting lines often sit at low pixel contrast. If you raise Canny's upper threshold (maxVal) to suppress the shadow and glare noise, you simultaneously erase the fine internal seams that make a technical drawing useful for assembly guides or spec sheets.

The same flaw affects the popular "pencil sketch" snippet that inverts a grayscale image, blurs it with a Gaussian kernel, and divides the original grayscale values by the inverted blur. Because color-dodge division amplifies contrast wherever luminance shifts rapidly, it turns brushed-metal grain into stipple noise and outlines every specular hot spot.

How do you audit specular glare and shadow gradients in Python before tracing?

You audit specular glare and shadow gradients in Python by converting the BGR image into CIE LAB and HSV color spaces, flagging high-lightness low-saturation islands (L > 240 and S < 20), measuring gradient density across the bottom tabletop strip, and dividing the lightness channel by a large morphological closing envelope before calling Canny. Running this pre-flight audit tells you in milliseconds whether a photo can be cleaned with local morphological math or needs an object-aware pass.

Let's build a self-contained script using opencv-python (cv2) and numpy. Instead of blindly tuning Canny thresholds by hand, the function audit_and_extract_lines performs four deterministic steps:

Glare island segmentation: It converts the image to LAB and HSV. Specular reflections on dielectric and metallic surfaces spike the LAB lightness channel (L) while washing out HSV saturation (S). We build a binary mask where L > 240 and S < 20, then run cv2.connectedComponentsWithStats to count distinct glare islands between 25 and 15,000 pixels in area.
Telea glare inpainting: Before computing any edge gradients, we pass the glare mask into cv2.inpaint with cv2.INPAINT_TELEA so the clipped white boundary is smoothly filled from the surrounding midtone surface.
Morphological illumination division: To flatten broad cast shadows across the tabletop and housing faces, we apply a morphological closing operation (cv2.MORPH_CLOSE) with a 45x45 elliptical structuring element on the inpainted L channel. Dividing the L channel by that morphological background envelope normalizes slow lighting ramps while keeping tight physical crevices intact.
Edge-preserving bilateral smoothing: As documented in the OpenCV filtering guide, cv2.bilateralFilter weights neighbor pixels by both spatial distance and radiometric intensity difference. Applying a bilateral filter (d=9, sigmaColor=55, sigmaSpace=55) smooths out brushed-metal surface texture without blurring sharp cabinet corners.

Here is the complete, runnable script:

import cv2
import numpy as np


def audit_and_extract_lines(img_bgr: np.ndarray) -> tuple[dict, np.ndarray]:
    """Audit glare islands and shadow ramps, then extract normalized line art."""
    lab = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2LAB)
    hsv = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2HSV)
    l_chan = lab[:, :, 0]
    s_chan = hsv[:, :, 1]

    # 1. Detect specular glare islands (high L, low S)
    glare_mask = ((l_chan > 240) & (s_chan < 20)).astype(np.uint8) * 255
    num_labels, _, stats, _ = cv2.connectedComponentsWithStats(glare_mask)
    glare_islands = sum(
        1 for i in range(1, num_labels)
        if 25 <= stats[i, cv2.CC_STAT_AREA] <= 15000
    )

    # 2. Measure shadow gradient density in the bottom 22% floor strip
    h, w = l_chan.shape
    floor_strip = l_chan[int(h * 0.78):, :]
    gx = cv2.Sobel(floor_strip, cv2.CV_32F, 1, 0, ksize=3)
    gy = cv2.Sobel(floor_strip, cv2.CV_32F, 0, 1, ksize=3)
    grad_mag = np.sqrt(gx ** 2 + gy ** 2)
    shadow_ramp_ratio = float(np.mean(grad_mag > 12.0))

    # Baseline unconditioned Canny edge count
    raw_edges = cv2.Canny(l_chan, 60, 150)

    # 3. Inpaint glare boundaries + normalize slow shadow envelopes
    inpainted_l = cv2.inpaint(
        l_chan, glare_mask, inpaintRadius=5, flags=cv2.INPAINT_TELEA
    )
    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (45, 45))
    bg_envelope = cv2.morphologyEx(inpainted_l, cv2.MORPH_CLOSE, kernel)
    norm_l = cv2.divide(inpainted_l, bg_envelope, scale=255)

    # 4. Bilateral smoothing + Canny contour extraction (black lines on white)
    smooth_l = cv2.bilateralFilter(norm_l, d=9, sigmaColor=55, sigmaSpace=55)
    clean_edges = cv2.Canny(smooth_l, 60, 150)
    line_art = 255 - clean_edges

    raw_px = int(np.count_nonzero(raw_edges))
    clean_px = int(np.count_nonzero(clean_edges))
    reduction_pct = round((1.0 - clean_px / max(1, raw_px)) * 100.0, 1)

    report = {
        "glare_islands": glare_islands,
        "shadow_ramp_ratio": round(shadow_ramp_ratio, 4),
        "raw_edge_pixels": raw_px,
        "clean_edge_pixels": clean_px,
        "false_edge_reduction_pct": reduction_pct,
    }
    return report, line_art


if __name__ == "__main__":
    sample = cv2.imread("02-glare-shadow-setup.png")
    metrics, output_drawing = audit_and_extract_lines(sample)
    print(metrics)
    cv2.imwrite("speaker_line_art_cleaned.png", output_drawing)

When we run this script against our 1536x1024 brushed-aluminum speaker test image (02-glare-shadow-setup.png), it prints the following diagnostic dictionary:

{'glare_islands': 4, 'shadow_ramp_ratio': 0.0381, 'raw_edge_pixels': 37540, 'clean_edge_pixels': 26290, 'false_edge_reduction_pct': 30.0}

Those numbers show what happens inside the image array. The script caught 4 specular glare islands along the bevelled aluminum edge and measured a 0.0381 shadow gradient ratio across the tabletop. By inpainting the four highlight boundaries, dividing out the 45x45 closing envelope, and running bilateral smoothing before Canny, total edge pixels dropped from 37,540 to 26,290, stripping 30.0% of the false-positive noise while keeping the cone surround and socket screws intact.

Pipeline stage	What it targets	Failure mode if skipped	Parameter to tune for studio packshots
`L > 240` & `S < 20` mask + `cv2.inpaint`	Clipped softbox highlights on chamfered metal or glazed ceramic	Double oval contour rings floating inside smooth surfaces	Lower `L` threshold to `230` if the studio photo was exported with compressed highlight roll-off
`cv2.MORPH_CLOSE` (`45x45`) + `cv2.divide`	Gradual illumination falloff and soft tabletop cast shadows	Stray floor lines and uneven threshold sensitivity across dark sides	Scale kernel size to roughly `3%` of image width (`45` px for a `1536` px wide photo)
`cv2.bilateralFilter` (`d=9, 55, 55`)	Fine brushed-metal grain, anodized speckle, or paper texture	Dense stipple clutter inside flat panels	Increase `sigmaColor` to `75` for heavily textured cast iron or woven fabric
`cv2.Canny(smooth_l, 60, 150)`	Physical silhouette boundaries, recess grooves, and screw heads	Broken outer contours if `minVal` is too high	Keep `maxVal:minVal` between `2:1` and `3:1` as recommended by Canny's original hysteresis design

When should you switch from pixel-gradient scripts to object-aware line art generation?

You should switch from pixel-gradient scripts to object-aware line art generation when your product photo contains dark horizon reflections on curved chrome, busy lifestyle backgrounds, or printed surface graphics that local pixel math cannot separate from physical seams. No matter how carefully you tune morphological kernels in OpenCV, a local filter only sees pixel neighborhoods; it does not understand which lines belong to the 3D form of the object.

Public tool page of Virse's AI Line Art Generator (currently titled Line Art Extractor on the page header), showing the source upload slot, the Detailed line art, Clean line art, and Bold outline buttons, the extraction notes field, and the Generate line art button.

For example, if you photograph a stainless steel espresso machine or a vintage amplifier with a brass faceplate, the metal reflects dark room shapes alongside bright softboxes. A dark reflection has low lightness (L < 60), so a glare mask (L > 240) ignores it, and its sharp edge survives bilateral filtering just like a real panel gap. Similarly, as the scikit-image Canny edge detector example demonstrates, local gradient detectors always trade off noise suppression against structural completeness when signal-to-noise varies across the frame.

When you need a drawing that holds the object's true form and proportions without hand-masking every reflection in Python, you can use a clean black-on-white line art generator on Virse (whose public tool page header currently displays the title Line Art Extractor). Instead of running a pixel edge filter, Virse's AI Line Art Generator identifies the product first, removes the background automatically, and traces a black-line drawing on a pure white background where surface glare, cast shadows, and studio backdrops do not turn into stray lines.

On the public tool page, the workflow takes three inputs before opening the workspace canvas:

Source image: Upload a single product photo (JPG, PNG, WebP, GIF, BMP, AVIF, or HEIC). The tool requires a source photo and cannot generate line art from text alone.
Line style (optional): Pick one of the three line style buttons depending on where the drawing will live:
- Detailed line art (full structure study): Keeps internal seams, knurled knobs, grille patterns, and small fastener details for assembly guides or technical callout sheets.
- Clean line art (presentation outline): Simplifies fine surface texture while holding the main housing panels and primary controls for onboarding cards or catalog spot illustrations.
- Bold outline (silhouette-focused): Emphasizes the outer contour and major form breaks with heavier stroke weight for small icons or packaging inserts.
Extraction notes (optional): Add a short plain-language instruction specifying what to keep or omit, such as keeping only one object in the frame, preferring a specific line weight, or omitting printed brand logos and surface reflections.

Clicking Generate line art brings your uploaded product photo and selected parameters into a new Virse canvas with the tool pre-filled. Nothing runs and no credits are spent until you press Start inside the canvas. When the pass finishes, the black-on-white line drawing lands on the canvas beside your original photo so you can inspect proportions side by side, adjust extraction notes, or send the drawing into the Line Art Renderer on the same board.

Keep two technical boundaries in mind when choosing between a Python script, Virse's canvas tool, and CAD software:

Raster output, not CAD or SVG vectors: Both the OpenCV pipeline above and Virse's AI Line Art Generator output raster pixel images (PNG/WebP black lines on a white background, not a transparent background). Neither produces a measured engineering blueprint with dimensional tolerances or an editable SVG/DXF file. If your print vendor requires vector paths, run an automated bitmap-to-vector pass (such as Potrace or Illustrator Image Trace) on the cleaned raster output.
Proportional fidelity vs orthographic projection: A line drawing extracted from a camera photo preserves the perspective of that camera angle rather than converting a 3/4 packshot into a flat orthographic CAD projection.

How do you inspect and clean raster line drawings before putting them into docs?

You inspect and clean raster line drawings before putting them into documentation by checking four structural criteria: outer silhouette closure, internal seam continuity, zero residual reflection rings, and pure white (255) background floors.

AI-generated illustration: Checking seam continuity and fastener hole outlines under an optical loupe against the physical machined housing.

Run this four-point verification before dropping the file into your layout tool:

Check outer silhouette closure at 200% zoom: If a bright rim highlight caused a 4-pixel gap along the top edge, any subsequent flood-fill or vector trace will leak into the background. Close tiny perimeter gaps in Python with cv2.morphologyEx(clean_edges, cv2.MORPH_CLOSE, np.ones((3, 3), np.uint8)) before inverting.
Verify fastener and port symmetry: Pixel edge detectors often break small circular ports or screws into crescent fragments under directional light. Either lower minVal in Canny or use an object-aware pass with an extraction note preserving front-panel ports.
Confirm zero floating reflection loops: Scan the largest panels of the product. Any closed loop that does not match a real seam, button, or vent slot is a surviving reflection artifact and should be masked out.
Clip the white floor to pure 255: Even a 252 off-white background prints as a visible gray box on paper. Run a final levels clip (line_art[line_art > 240] = 255) so the background merges cleanly with the page.

By auditing glare_islands and shadow_ramp_ratio up front in Python, you can batch-process matte packshots automatically in OpenCV and route reflective hardware shots to an object-aware line art pass without erasing shadow lines by hand.

Delta E 2000 Python Tutorial: Score Color Consistency Across a Product Photo Set

virse — Thu, 24 Sep 2026 14:50:40 +0000

This Delta E 2000 Python script gives every photo in a product set one number: how far its neutral tones sit from the rest of the set, measured in CIEDE2000 units, with a non-zero exit code when any photo drifts past your limit. On a six-photo test listing it passed the re-saved copy (0.40) and failed the warm, cool, green and underexposed versions, which a plain average RGB comparison ranks in the wrong order.

AI helped draft this post. I ran every code block below on Python 3.13 and pasted the printed output from those runs. Virse, whose photo color tool is mentioned once as a fix step, has a business relationship with this post.

TL;DR

Reduce each photo to a neutral signature: the median Lab value of its least colorful lit pixels.
Score each signature with scikit-image's deltaE_ciede2000 against the set median or a hero photo, twice: plain ΔE00, and a cast score with L* equalized.
Fail the batch when a cast passes 2.0. The script exits with 1, so it can sit in front of an upload step.

This is written for developers who maintain product image pipelines. It measures consistency inside a set of photos, not absolute color accuracy against the physical product.

What does a Delta E 2000 Python score tell you about a photo set?

It tells you how visible the color difference between two photos is likely to be, on a scale where 1.0 is roughly the smallest difference a viewer can see. Techkon puts it this way: "Generally, a 1 DE00 is deemed the threshold, indicating that any value below it signifies an imperceptible difference" (Techkon). Konica Minolta's guide reads 1 to 2 as "barely noticeable under close inspection" and 3 or more as a "clearly visible difference, often unacceptable" (Konica Minolta).

Delta E 2000 (also written ΔE00 or CIEDE2000) compares two colors, not two images. To score a set, you need three decisions:

Which single Lab color represents each photo.
What you compare against: the set's median, or one hero photo.
Which limit fails the batch.

For a product listing, the thing that should match is rarely the product. A red mug and a blue mug are supposed to differ. What should match is the backdrop, the white of the sweep, the wall behind a sofa: the neutral parts of the frame, where a warm or green cast is easy to see next to the other listing images. The script below scores those.

Which Python library should compute CIEDE2000?

For arrays of colors, scikit-image's skimage.color.deltaE_ciede2000 is the practical choice: it is vectorized, and scikit-image also gives you rgb2lab, which converts sRGB to CIELAB under the D65 illuminant by default (scikit-image docs). The pure-Python packages that rank for this query, such as deltae and python-colormath, are built around comparing individual colors, which suits a swatch check better than a photo's worth of pixels.

CIEDE2000 came after the CIE76 and CIE94 formulas. scikit-image's docs call it "a major revision of CIDE94" and add that "the perceptual calibration is largely based on experience with automotive paint on smooth surfaces." Keep that second sentence in mind when you borrow its thresholds for photos.

Before trusting any implementation, check it against the test pairs published with Sharma, Wu and Dalal's implementation notes (Color Research & Application, 2005, DOI 10.1002/col.20070). The spreadsheet is on Gaurav Sharma's CIEDE2000 page; I converted its 34 rows to JSON.

pip install numpy pillow scikit-image colour-science xlrd

# xls_to_json.py  (pip install xlrd)
import json
import xlrd

sheet = xlrd.open_workbook("CIEDE2000.xls").sheet_by_index(0)
rows = [r[:6] + [r[38]] for r in map(sheet.row_values, range(sheet.nrows)) if isinstance(r[0], float)]
json.dump(rows, open("sharma_pairs.json", "w"))
print(len(rows), "pairs")

# check_sharma.py
import json
import numpy as np
import colour
from skimage.color import deltaE_ciede2000

rows = np.array(json.load(open("sharma_pairs.json")))   # L1 a1 b1 L2 a2 b2 dE00
lab1, lab2, expected = rows[:, 0:3], rows[:, 3:6], rows[:, 6]

sk = deltaE_ciede2000(lab1, lab2)
co = colour.delta_E(lab1, lab2, method="CIE 2000")
print(f"pairs: {len(rows)}")
print(f"scikit-image max abs error: {np.abs(sk - expected).max():.1e}")
print(f"colour-science max abs error: {np.abs(co - expected).max():.1e}")
print(f"swap arguments, max change: {np.abs(deltaE_ciede2000(lab2, lab1) - sk).max():.1e}")

pairs: 34
scikit-image max abs error: 3.1e-14
colour-science max abs error: 1.3e-15
swap arguments, max change: 0.0e+00

Both libraries match the reference values to floating-point noise. I tested with numpy 2.4.1, scikit-image 0.26.0, Pillow 12.2.0 and colour-science 0.4.7.

How do you turn a whole photo into one Lab color?

Take the median Lab value of the least colorful pixels that are neither in shadow nor clipped. That is the "neutral signature" of the photo.

The obvious alternative, the mean of the whole frame, mostly measures content. A photo with more wood floor in it looks "warmer" than one with more white wall, even if both were shot under the same light. The neutral pixels are where a white-balance problem shows up and where the content matters least.

def neutral_signature(lab, share=0.2, l_min=40, l_max=95):
    """Median Lab of the least colorful lit pixels: backdrop, walls, white goods."""
    lit = lab[(lab[:, 0] > l_min) & (lab[:, 0] < l_max)]   # drop shadows, clipped whites
    if len(lit) < 500:
        lit = lab
    chroma = np.hypot(lit[:, 1], lit[:, 2])
    return np.median(lit[chroma <= np.quantile(chroma, share)], axis=0)

Parameter	Default	What it controls
`share`	0.2	Fraction of lit pixels, lowest chroma first, that form the signature
`l_min`	40	Pixels darker than this L* are ignored (shadows carry noise and cast from bounce light)
`l_max`	95	Pixels brighter than this are ignored (clipped whites have no color left to measure)
`max_side`	512	Resize before conversion so large camera files stay fast

The median matters here. A few saturated pixels that slip into the 20% cannot drag a median the way they drag a mean.

How do you separate exposure drift from a color cast?

Score each photo twice. The first score is plain ΔE00 between the photo's signature and the reference. The second copies the reference's L* into the photo's signature before comparing, so only the a*/b* difference is left. I call that the cast score.

def score(sigs, ref):
    total = de00(ref, sigs)                        # lightness + cast
    flat = np.array(sigs, dtype=np.float64)
    flat[:, 0] = ref[0]                            # same L*: only the cast is left
    cast = de00(ref, flat)
    return total, cast

The split matters because the two failures need different fixes. A photo that is a third of a stop dark needs an exposure change. A photo with a green tint needs a white-balance change. Both produce a similar-sized plain ΔE00, so one number alone does not tell whoever fixes the photo what to do.

What does the full script look like?

Here is score_set.py in full. It takes a list of photos, scores them against the set median (or --ref), prints a table and exits with 1 if anything fails.

"""Score how consistent the color of a photo set is, using Delta E 2000.

usage: python score_set.py photos/*.jpg [--cast 2.0] [--total 4.0] [--ref hero.jpg]
exit code 1 when any photo is over the limit, so it can gate a batch.
"""
import argparse
import sys
import numpy as np
from PIL import Image
from skimage.color import rgb2lab, deltaE_ciede2000


def load_lab(path, max_side=512):
    img = Image.open(path).convert("RGB")
    img.thumbnail((max_side, max_side))           # keeps big camera files fast
    rgb = np.asarray(img, dtype=np.float64) / 255.0
    return rgb2lab(rgb).reshape(-1, 3)            # sRGB -> CIELAB (D65)


def neutral_signature(lab, share=0.2, l_min=40, l_max=95):
    """Median Lab of the least colorful lit pixels: backdrop, walls, white goods."""
    lit = lab[(lab[:, 0] > l_min) & (lab[:, 0] < l_max)]   # drop shadows, clipped whites
    if len(lit) < 500:
        lit = lab
    chroma = np.hypot(lit[:, 1], lit[:, 2])
    return np.median(lit[chroma <= np.quantile(chroma, share)], axis=0)


def de00(ref, sigs):
    sigs = np.asarray(sigs, dtype=np.float64)
    ref = np.broadcast_to(np.asarray(ref, dtype=np.float64), sigs.shape)
    return deltaE_ciede2000(ref, sigs)


def score(sigs, ref):
    total = de00(ref, sigs)                        # lightness + cast
    flat = np.array(sigs, dtype=np.float64)
    flat[:, 0] = ref[0]                            # same L*: only the cast is left
    cast = de00(ref, flat)
    return total, cast


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("photos", nargs="+")
    ap.add_argument("--cast", type=float, default=2.0, help="max cast dE00")
    ap.add_argument("--total", type=float, help="max full dE00 (off by default)")
    ap.add_argument("--ref", help="score against this photo, not the set median")
    a = ap.parse_args()

    sigs = np.array([neutral_signature(load_lab(p)) for p in a.photos])
    ref = neutral_signature(load_lab(a.ref)) if a.ref else np.median(sigs, axis=0)
    total, cast = score(sigs, ref)

    print(f"reference L*a*b*: {ref[0]:.1f} {ref[1]:.1f} {ref[2]:.1f}")
    print(f"{'photo':<18}{'L*':>6}{'a*':>6}{'b*':>6}{'dE00':>8}{'cast':>8}")
    fail = cast > a.cast
    if a.total is not None:
        fail |= total > a.total
    for p, s, t, c, f in zip(a.photos, sigs, total, cast, fail):
        name = p.replace("\\", "/").split("/")[-1]
        print(f"{name:<18}{s[0]:6.1f}{s[1]:6.1f}{s[2]:6.1f}{t:8.2f}{c:8.2f}{'  FAIL' if f else ''}")
    print(f"set: max cast {cast.max():.2f}, median cast {np.median(cast):.2f}, "
          f"{int(fail.sum())}/{len(fail)} failed")
    sys.exit(1 if fail.any() else 0)


if __name__ == "__main__":
    main()

The np.broadcast_to line in de00 works around a bug. In scikit-image 0.26.0, passing an (N, 3) array and a single (3,) reference color to deltaE_ciede2000 raises AxisError: source: axis 1 is out of bounds for array of dimension 1, and swapping the arguments raises ValueError: not enough values to unpack. That is scikit-image issue #8326, still open when I checked; deltaE_cie76 and deltaE_ciede94 accept the same inputs. Broadcasting the reference to the full shape first avoids it.

Because it exits with 1 on failure, you can put it in front of an upload step:

python score_set.py export/SKU-1042/*.jpg --ref export/SKU-1042/hero.jpg --total 4.0 && ./upload.sh SKU-1042

What does the script print on a test listing?

To see whether the scores mean anything, I built a listing with known problems. The base image is a bedroom photo from the example gallery on Virse's Color Grade Transfer page. make_variants.py applies channel gains in linear light, the way a white-balance or exposure slider does in a raw converter, and saves six JPEGs. The variants are synthetic; the scores are real output.

# make_variants.py
"""Build a test listing set with known problems from one photo.

Gains are applied in linear light, like a white-balance or exposure change
in a raw converter. The names say what was injected.
"""
import os
import numpy as np
from PIL import Image

def to_linear(c):
    return np.where(c <= 0.04045, c / 12.92, ((c + 0.055) / 1.055) ** 2.4)

def to_srgb(c):
    c = np.clip(c, 0, 1)
    return np.where(c <= 0.0031308, c * 12.92, 1.055 * c ** (1 / 2.4) - 0.055)

def variant(rgb, r=1.0, g=1.0, b=1.0, ev=0.0):
    lin = to_linear(rgb) * np.array([r, g, b]) * 2 ** ev
    return (to_srgb(lin) * 255 + 0.5).astype(np.uint8)

src = np.asarray(Image.open("photos/strengths/bed_01.png").convert("RGB")) / 255.0
os.makedirs("listing", exist_ok=True)
jobs = {
    "01_hero":        dict(),
    "02_resaved":     dict(),                       # JPEG re-encode only
    "03_under_third": dict(ev=-1/3),                # 1/3 stop darker
    "04_warm":        dict(r=1.06, b=0.92),
    "05_cool":        dict(r=0.94, b=1.08),
    "06_green":       dict(g=1.04),
}
for name, kw in jobs.items():
    q = 80 if name == "02_resaved" else 95
    Image.fromarray(variant(src, **kw)).save(f"listing/{name}.jpg", quality=q)
    print(name, kw)

$ python score_set.py listing/*.jpg --ref listing/01_hero.jpg --total 4.0
reference L*a*b*: 81.0 0.8 2.8
photo                 L*    a*    b*    dE00    cast
01_hero.jpg         81.0   0.8   2.8    0.00    0.00
02_resaved.jpg      81.4   1.0   2.7    0.40    0.31
03_under_third.jpg  74.3   0.7   2.6    4.75    0.29  FAIL
04_warm.jpg         80.8   1.6   7.1    3.54    3.54  FAIL
05_cool.jpg         79.2   0.0   0.2    2.96    2.68  FAIL
06_green.jpg        81.4  -0.9   4.2    2.82    2.81  FAIL
set: max cast 3.54, median cast 1.49, 4/6 failed

Reading it row by row:

The re-saved JPEG moves 0.40, under the 1.0 visibility threshold. Compression alone does not trip the gate.
The underexposed copy has a plain ΔE00 of 4.75 but a cast of 0.29. The columns say "exposure, not white balance", and that is exactly what was injected.
Warm, cool and green all land between 2.68 and 3.54 on the cast column, inside Konica Minolta's "clearly visible" band or just below it.

Without --ref, the script uses the set median as the reference. On the same six files that gives a max cast of 3.63 and the same three cast failures. The underexposed copy is not flagged in that run: its cast is 0.16, and --total is off unless you set it.

Why not just compare average RGB?

Because average RGB distance ranks these photos in the wrong order. I computed the Euclidean distance between each file's mean RGB and the hero's:

Photo	Mean RGB distance	ΔE00	Cast ΔE00
resaved	0.1	0.40	0.31
under_third	27.5	4.75	0.29
warm	7.2	3.54	3.54
cool	7.0	2.96	2.68
green	2.8	2.82	2.81

By RGB distance, the green tint looks like the second-best photo in the set, ten times closer than the darker copy. By ΔE00 its cast is almost as strong as the warm one. For single colors, the dev.to post "Difference Between 2 Colours Using Python" describes the underlying problem with Euclidean distance: "What looks like identical colours to us, might give us a Euclidean distance that is greater than the Euclidean distance of colours that look different to us" (dev.to).

A related trap: OpenCV's 8-bit COLOR_BGR2LAB stores L* scaled to 0 to 255 and a*/b* offset by 128. I fed two nearby pixels, RGB (200, 190, 175) and (200, 185, 175), through both libraries:

OpenCV 8-bit Lab: [[198.0, 129.0, 137.0], [194.0, 132.0, 135.0]]
scikit-image Lab: [[77.4, 0.95, 8.83], [76.11, 3.62, 6.99]]
dE00 on raw OpenCV values: 1.75
dE00 after rescaling:      4.66
dE00 scikit-image:         4.15

Raw OpenCV values would pass that pair under a 2.0 limit. Rescaling fixes the units but keeps the 8-bit rounding error. Convert float RGB with rgb2lab instead.

What Delta E 2000 threshold should the gate use?

Start with a cast limit of 2.0 and turn on --total 4.0 only for sets with the same composition. The 2.0 sits at the top of the 1 to 2 "barely noticeable" band from the Konica Minolta guide, so anything flagged is past what most viewers let slide.

Situation	Reference	Limits
Same product, several angles, one backdrop	`--ref` the approved hero	`--cast 2.0 --total 4.0`
Different products, same studio setup	set median	`--cast 2.0`
Mixed scenes (lifestyle, UGC, stock)	set median	`--cast 3.0`, review flags by eye
Brand with a strict color spec	`--ref` hero	`--cast 1.0`

Konica Minolta gives an example of how widely tolerances vary: "a luxury cosmetic brand may demand ΔE ≤ 1.0, while an automotive supplier may accept ΔE ≤ 2.0." Those are for measured physical color. For photos, calibrate on your own data: run the script over five or ten listings your team already considers fine, look at the max cast values, and set the limit just above them.

One detail about the median reference: with an odd number of photos, the median signature is often one of the photos itself, so one row reads 0.00. That does not make that photo "correct". It is the middle of the set.

How does a real before/after set score?

The same page's gallery has a "Mixed Cameras, One Look" example: "three source photos graded against a single reference." I cut the two rows apart and scored each as a set.

sources:  cast 1.23, 6.97, 0.00   max 6.97  (1/3 failed)
graded:   cast 0.00, 0.75, 0.68   max 0.75  (0/3 failed)

The Mediterranean street photo in the source row fails with a cast of 6.97. After grading, the whole row sits under 1.0.

The Mixed Cameras example from Virse's tool page, scored as two sets: max cast 6.97 before, 0.75 after.

When a photo fails, you can fix white balance by hand in a raw editor, or, when you do not have the raw file, match the flagged photo to your hero with an AI color match for photos. Virse's Color Grade Transfer takes the photo plus one tone reference, matches Lab statistics rather than regenerating the image, and has Light, Standard and Full strengths. It returns one graded image per run, so you re-score the new file with the same command and see whether it passes.

The photo color matching form: one source image, one tone reference, three strengths.

Where does the neutral signature break?

It breaks when the least colorful lit pixels in one photo come from a different light than in the others. The clearest case in my runs was the six-photo interior set from the same gallery. Five photos scored a cast between 0.18 and 2.32 (two of them, at 2.03 and 2.32, just over the 2.0 limit). The doorway shot scored 5.44, with a plain ΔE00 of 19.84.

Where the neutral signature looks: the sunlit wall in one shot, the brighter room behind the door in the other.

The mask shows why. In the corner shot, the signature comes from the sunlit wall. In the doorway shot, most of it comes from the brighter room behind the door, which is under different light from the foreground wall. The photo may be fine; the signature is measuring a different surface.

Other cases where I would not trust the number without a look:

Product fills the frame and is strongly colored, with no backdrop in view. There are no neutral pixels to measure, so the signature picks the least colorful parts of the product.
Mixed lighting in one frame, such as a window plus warm lamps. The 20% slice can land on either.
Very small sets. With two or three photos, the median is weak, so use --ref.

The fix for all of these is the same: pass a mask. If your product photos come from a template, crop a fixed backdrop region (for example, the top 15% of the frame) before calling neutral_signature. The rest of the script does not change.

FAQ

Is Delta E 2000 symmetric? In my test, swapping the two arguments changed no value across all 34 Sharma pairs (max change 0.0). You can pass the reference in either position. Hold on to one convention anyway so that your logs read the same way.

Does this work on uncalibrated sRGB JPEGs? For consistency inside a set, yes, because every photo goes through the same conversion. For absolute color accuracy against a physical product, no: that needs a calibrated capture. python-colormath's docs describe ΔE as "a good rough starting point for comparing colors," and that is the right level of trust for camera JPEGs.

Can I use ΔE76 instead? You can, since scikit-image has deltaE_cie76. The thresholds in this post are for ΔE00, and the two scales differ, so do not reuse the numbers.

To try it on your own catalog, copy score_set.py, run it over one SKU folder with --ref pointing at the approved hero, and read the cast column before you pick a limit.

Tech Pack Python Script: Assemble a PDF from Product Photos and Line Drawings

virse — Wed, 23 Sep 2026 15:16:49 +0000

This tech pack Python script turns a product photo, a line drawing and a small style.json into a two-page PDF: page one puts the photo next to the drawing with numbered callout pins, page two holds the bill of materials, points of measure with tolerances, and a revision log. The script is 175 lines of Python built on reportlab and Pillow, and every number in this post comes from running it.

AI helped draft this post; I ran every code block and copied the printed output from those runs. This account belongs to Virse, and Virse's line art tool comes up once below as one way to get the drawing.

What does this tech pack Python script produce?

It produces a landscape A4 PDF with a header block on every page (style number, name, season, revision, date, page count) and two pages of content. Techpacker lists seven core components of a tech pack: "Cover page and style information," "technical flat sketches," "bill of materials," "measurement specifications and grading chart," "construction notes and stitching details," "cost sheet," and "revision history and version log" (source). Here is how the script maps to that list:

Component	In this script	Where
Cover page and style information	Yes, as a header on every page	`header()`
Technical flat sketch	Yes, line drawing with numbered pins	page 1
Construction notes	Partly, one spec line per callout	page 1 legend
Bill of materials	Yes	page 2
Measurements	Yes, one size with tolerances	page 2
Grading chart	No	extend `pom`
Cost sheet	No	out of scope
Revision log	Yes	page 2

The point is not to replace a PLM system. It is for the common case where a small hardware or apparel team keeps specs in a spreadsheet, drawings in a folder, and rebuilds the PDF by hand every time a supplier asks for "the latest version".

Page two: BOM, points of measure with tolerances, and the revision log, all read from style.json.

What do you need before running it?

Python 3 and three packages. I tested with Python 3.13.3, reportlab 4.5.1, Pillow 12.2.0 and PyMuPDF 1.27.2.3 (PyMuPDF is only used for the preview step at the end).

pip install reportlab pillow pymupdf

Each style gets its own folder with up to three files:

drill/
  photo.jpg      # optional reference photo
  lineart.png    # black lines on white
  style.json     # everything the tables and callouts need

style.json holds the header fields, callouts, BOM, points of measure and revisions. The drill below is a hypothetical example; the materials and dimensions are placeholders, not a real product's spec.

{
  "style_no": "DR-18",
  "name": "Cordless drill driver (example)",
  "season": "SS27",
  "revision": "B",
  "date": "2026-09-23",
  "callouts": [
    {"x": 0.25, "y": 0.14, "label": "Keyless chuck", "spec": "Knurl pattern as sample; no printed marks"},
    {"x": 0.92, "y": 0.16, "label": "Motor vents", "spec": "4 slots each side, keep open, no mesh"}
  ],
  "bom": [
    {"component": "Main housing", "material": "PC/ABS", "finish": "Yellow, light texture", "supplier": "TBD", "qty": 2}
  ],
  "pom": [
    {"code": "A", "point": "Overall length, chuck tip to rear vent", "target": 185, "tol": 1.5, "unit": "mm"}
  ],
  "revisions": [
    {"rev": "A", "date": "2026-09-10", "change": "First issue"},
    {"rev": "B", "date": "2026-09-23", "change": "Vent slots 5 -> 4; grip overmold 1.5 -> 2 mm proud"}
  ]
}

That listing is trimmed for space; the file I ran has seven callouts, five BOM rows and four points of measure.

Where does the line drawing come from?

Any flat that is black lines on a white background will work: an Illustrator export, a scanned hand drawing, or a drawing traced from a sample photo. The script only cares about two things. The background has to be white, because Step 1 finds the drawing by looking for dark pixels. And if you include a reference photo, the drawing should show the product from the same angle, or the callouts on the drawing will not match what people see in the photo next to it.

If all you have is a photo of the sample, you need a photo to line drawing for a tech pack step before this script runs. Virse's AI Line Art Generator takes one product photo, removes the background, and returns black lines on white in one of three styles (Detailed line art, Clean line art or Bold outline), plus an optional one-line note such as which seams to keep or which reflections to drop. It does not return a transparent PNG, which is fine here because the script expects white. The drill photo and drawing pair and the hoodie flat used in this post are example images published on that tool's page; I did not generate new ones for this tutorial.

The photo to line drawing step: one product photo, a line style, and an optional note on what to keep.

Step 1: clean and trim the line drawing

Both drawings I used arrived with a wide white margin around the product and gray anti-aliased pixels along every line. The margin shrinks the drawing once it is scaled into a column on the page. The gray pixels stop the image from being stored as 1-bit black and white, which is what keeps it small inside the PDF.

"""Assemble a tech pack PDF from a product photo, a line drawing and a style.json."""
import io
import json
import sys
from pathlib import Path

from PIL import Image, ImageOps
from reportlab.lib import colors
from reportlab.lib.pagesizes import A4, landscape
from reportlab.lib.utils import ImageReader
from reportlab.pdfgen import canvas
from reportlab.platypus import Table, TableStyle

PAGE_W, PAGE_H = landscape(A4)   # 842 x 595 pt
MARGIN = 28
HEADER_H = 46


def prep_line_drawing(path, threshold=200, pad=12):
    """Grayscale, snap to pure black/white, trim the empty margin."""
    img = Image.open(path).convert("L")
    bw = img.point(lambda v: 255 if v > threshold else 0, mode="1")
    bbox = ImageOps.invert(bw.convert("L")).getbbox()   # box around the ink
    left, top, right, bottom = bbox
    bbox = (max(left - pad, 0), max(top - pad, 0),
            min(right + pad, bw.width), min(bottom + pad, bw.height))
    trimmed = bw.crop(bbox)
    print(f"line drawing {img.size} -> trimmed {trimmed.size}, crop box {bbox}")
    return ImageReader(trimmed)

getbbox() returns the box around non-zero pixels, so the function inverts the 1-bit image first to make the ink the non-zero part. On the drill drawing it printed:

line drawing (766, 1024) -> trimmed (572, 752), crop box (92, 137, 664, 889)

The trim matters more than it looks. On page one the drawing column has an image area 332 pt tall. Fitted into it untrimmed, the drill itself would be drawn 244 pt tall; trimmed, the drill is 332 pt tall and uses the whole area. A threshold of 200 keeps thin stitch lines on the drawings I tried. If faint lines disappear on yours, raise it; if gray noise survives, lower it.

prep_line_drawing() on the drill: the crop box it printed, and the trimmed 1-bit drawing that goes into the PDF.

Step 2: embed the photo without bloating the PDF

This one surprised me. If you hand reportlab a decoded Pillow image, it stores the raw pixels with Flate compression. A photo compresses badly that way. When I passed the photo and the untrimmed RGB drawing straight to ImageReader, the two-page PDF came out at 1,235 KB. With the two prep functions it is 122 KB, about a tenth of the size.

def prep_photo(path, max_side=1400, quality=85):
    """Downscale and re-encode as JPEG so the PDF embeds it with DCT, not Flate."""
    photo = Image.open(path).convert("RGB")
    photo.thumbnail((max_side, max_side))
    buf = io.BytesIO()
    photo.save(buf, "JPEG", quality=quality)
    buf.seek(0)
    return ImageReader(buf)          # JPEG bytes go into the PDF as-is


def fit(img, box_w, box_h):
    """Scale an image into a box without distortion; return drawn w, h."""
    w, h = img.getSize()
    scale = min(box_w / w, box_h / h)
    return w * scale, h * scale

Giving ImageReader a file object that contains JPEG bytes lets reportlab copy those bytes into the PDF unchanged. Opening the finished file with PyMuPDF confirms it: the photo is stored as a 75,769-byte JPEG and the 1-bit drawing as a 21,087-byte Flate image. A tech pack usually travels as an email attachment, so cutting the file to a tenth is worth six lines of code.

To reproduce the comparison, this swaps both prep functions for the naive version and rebuilds into a copy of the folder:

import shutil
from pathlib import Path

from PIL import Image
from reportlab.lib.utils import ImageReader

import build_techpack as bt

naive = Path("naive")
shutil.copytree("drill", naive, dirs_exist_ok=True)
bt.prep_photo = lambda p: ImageReader(Image.open(p).convert("RGB"))
bt.prep_line_drawing = lambda p: ImageReader(Image.open(p).convert("RGB"))
bt.build(naive)

Step 3: pin numbered callouts to the drawing

Callouts are where a tech pack earns its keep. A dev.to post on what factories want puts it as "Construction Callouts That Map Directly to the Sketches" (source). The question for code is what coordinates to store.

Page coordinates break as soon as the layout changes. Pixel coordinates break when someone re-exports the drawing at a different resolution. So style.json stores each pin as a fraction of the trimmed drawing, with (0, 0) at the top-left and (1, 1) at the bottom-right. The page code converts that into points after it knows where the drawing landed.

def header(c, style, page_no, page_total, title):
    top = PAGE_H - MARGIN
    c.setLineWidth(0.8)
    c.rect(MARGIN, top - HEADER_H, PAGE_W - 2 * MARGIN, HEADER_H)
    c.setFont("Helvetica-Bold", 14)
    c.drawString(MARGIN + 10, top - 20, f"{style['style_no']}  {style['name']}")
    c.setFont("Helvetica", 9)
    c.drawString(MARGIN + 10, top - 36,
                 f"Season {style['season']}   Rev {style['revision']}   {style['date']}")
    c.setFont("Helvetica-Bold", 11)
    c.drawRightString(PAGE_W - MARGIN - 10, top - 20, title)
    c.setFont("Helvetica", 9)
    c.drawRightString(PAGE_W - MARGIN - 10, top - 36, f"Page {page_no} of {page_total}")


def make_table(c, rows, col_widths):
    """Build a styled table and measure it; returns (table, height in pt)."""
    t = Table(rows, colWidths=col_widths)
    t.setStyle(TableStyle([
        ("FONT", (0, 0), (-1, 0), "Helvetica-Bold", 8),
        ("FONT", (0, 1), (-1, -1), "Helvetica", 8),
        ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#e9ecef")),
        ("GRID", (0, 0), (-1, -1), 0.4, colors.grey),
        ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
    ]))
    _, h = t.wrapOn(c, sum(col_widths), PAGE_H)
    return t, h


def sketch_page(c, style, photo, drawing):
    # measure the callout legend first, then give the images whatever is left
    rows = [["#", "Callout", "Spec"]] + [
        [str(i), co["label"], co["spec"]] for i, co in enumerate(style["callouts"], 1)]
    legend, legend_h = make_table(c, rows, [24, 200, PAGE_W - 2 * MARGIN - 224])
    legend.drawOn(c, MARGIN, MARGIN)

    body_top = PAGE_H - MARGIN - HEADER_H - 12
    body_h = body_top - (MARGIN + legend_h + 24)
    if photo is not None:
        col_w = (PAGE_W - 2 * MARGIN - 20) / 2
        pw, ph = fit(photo, col_w, body_h)
        c.drawImage(photo, MARGIN + (col_w - pw) / 2, body_top - ph, width=pw, height=ph)
        c.setFont("Helvetica-Oblique", 8)
        c.drawCentredString(MARGIN + col_w / 2, body_top - ph - 11, "Reference photo, not to scale")
        draw_x0 = MARGIN + col_w + 20
    else:
        col_w = PAGE_W - 2 * MARGIN
        draw_x0 = MARGIN

    dw, dh = fit(drawing, col_w, body_h)
    dx = draw_x0 + (col_w - dw) / 2
    dy = body_top - dh
    c.drawImage(drawing, dx, dy, width=dw, height=dh)

    # callouts are stored as fractions of the trimmed drawing (0..1, origin top-left)
    for i, co in enumerate(style["callouts"], start=1):
        px = dx + co["x"] * dw
        py = dy + (1 - co["y"]) * dh
        c.setFillColor(colors.HexColor("#d62828"))
        c.circle(px, py, 8, stroke=0, fill=1)
        c.setFillColor(colors.white)
        c.setFont("Helvetica-Bold", 9)
        c.drawCentredString(px, py - 3, str(i))
    c.setFillColor(colors.black)

Two details here came from bugs in my first version:

Measure the legend before placing the images. I first reserved a fixed 110 pt for the callout table. With seven callouts the table is 124.8 pt tall, so it drew over the bottom of the photo and the drawing. Table.wrapOn() returns the real height before anything is drawn, so the image area is now whatever is left.
Flip the y axis once. PDF coordinates start at the bottom-left, image coordinates at the top-left. The 1 - co["y"] is the only place that conversion happens.

Because pins are relative to the trimmed drawing, re-exporting the drawing at double resolution keeps them in place. A new drawing with a different pose or crop does not; for that, re-check the pins in the preview (below) and adjust the fractions.

Step 4: BOM, points of measure and revision log

Page two is three tables stacked from the top. Each block draws a title, measures its table, draws it, and returns the y position for the next one.

def spec_page(c, style):
    width = PAGE_W - 2 * MARGIN
    top = PAGE_H - MARGIN - HEADER_H - 16

    def block(title, rows, col_widths, top):
        c.setFont("Helvetica-Bold", 10)
        c.drawString(MARGIN, top, title)
        t, h = make_table(c, rows, col_widths)
        t.drawOn(c, MARGIN, top - 8 - h)
        return top - 8 - h - 24

    bom = [["Component", "Material", "Color / finish", "Supplier ref", "Qty"]]
    bom += [[b["component"], b["material"], b["finish"], b["supplier"], str(b["qty"])]
            for b in style["bom"]]
    top = block("Bill of materials", bom, [150, 190, 170, 170, width - 680], top)

    pom = [["Code", "Point of measure", "Target", "Tol +/-", "Unit"]]
    pom += [[p["code"], p["point"], f"{p['target']:g}", f"{p['tol']:g}", p["unit"]]
            for p in style["pom"]]
    top = block("Points of measure", pom, [50, 330, 90, 90, width - 560], top)

    rev = [["Rev", "Date", "Change"]] + [[r["rev"], r["date"], r["change"]]
                                         for r in style["revisions"]]
    block("Revision log", rev, [50, 90, width - 140], top)

The :g format prints 1.5 as 1.5 and 2.0 as 2, so the tolerance column does not fill up with trailing zeros. The column widths add up to the roughly 786 pt between the margins; if you add a column, take the width from "Point of measure".

This version assumes a style fits on two pages. If your BOM runs to forty rows, switch page two to reportlab's SimpleDocTemplate, let the table split across pages, and call header() from the template's onPage callback.

Step 5: fail the build when the spec is incomplete

The same dev.to post lists "Measurements With Tolerances, Not Just Target Numbers" as one of the things factories want. A script can enforce that: refuse to build a PDF that has a measurement without a tolerance, or a pin that falls off the drawing.

def validate(style):
    errors = []
    for i, co in enumerate(style["callouts"], 1):
        if not (0 <= co["x"] <= 1 and 0 <= co["y"] <= 1):
            errors.append(f"callout {i} is outside the drawing: {co['x']}, {co['y']}")
    for p in style["pom"]:
        if p.get("tol") in (None, 0):
            errors.append(f"POM {p['code']} has no tolerance")
    if errors:
        sys.exit("style.json problems:\n  " + "\n  ".join(errors))


def build(folder):
    folder = Path(folder)
    style = json.loads((folder / "style.json").read_text(encoding="utf-8"))
    validate(style)
    drawing = prep_line_drawing(folder / "lineart.png")
    photo_path = folder / "photo.jpg"
    photo = prep_photo(photo_path) if photo_path.exists() else None

    out = folder / f"{style['style_no']}_rev{style['revision']}_techpack.pdf"
    c = canvas.Canvas(str(out), pagesize=(PAGE_W, PAGE_H))
    c.setTitle(f"{style['style_no']} tech pack rev {style['revision']}")
    header(c, style, 1, 2, "Sketch and callouts")
    sketch_page(c, style, photo, drawing)
    c.showPage()
    header(c, style, 2, 2, "Materials and measurements")
    spec_page(c, style)
    c.showPage()
    c.save()
    print(f"wrote {out} ({out.stat().st_size / 1024:.0f} KB)")


if __name__ == "__main__":
    build(sys.argv[1])

Save all the blocks from Step 1 to here, in order, as build_techpack.py. With a copy of the drill folder where I pushed one pin to x = 1.08 and set one tolerance to 0, the run stops before writing anything and exits with status 1:

$ python build_techpack.py broken
style.json problems:
  callout 3 is outside the drawing: 1.08, 0.16
  POM D has no tolerance

With the real files:

$ python build_techpack.py drill
line drawing (766, 1024) -> trimmed (572, 752), crop box (92, 137, 664, 889)
wrote drill\DR-18_revB_techpack.pdf (122 KB)

The file name carries the style number and revision, so "rev B" in an email subject and the attachment name can't drift apart.

How do you check the PDF before sending it?

Render it to images and look. A pin that lands one feature off is the most likely error, and no validation rule catches it.

import sys
import fitz  # PyMuPDF

doc = fitz.open(sys.argv[1])
print(f"{doc.page_count} pages, {doc[0].rect.width:.0f} x {doc[0].rect.height:.0f} pt")
for page in doc:
    page.get_pixmap(dpi=110).save(f"{sys.argv[1][:-4]}_p{page.number + 1}.png")

$ python preview.py drill/DR-18_revB_techpack.pdf
2 pages, 842 x 595 pt

The same script handles apparel. For a hoodie there is no photo, only a flat, so photo.jpg is left out and the drawing takes the full width. The run printed line drawing (1254, 1254) -> trimmed (860, 1186) and wrote a 40 KB PDF.

If you put these PNGs in a pull request or a shared folder, reviewers can comment on pin placement without opening a PDF viewer.

What this script does not do

Keeping the scope honest saves a supplier email later:

No grading. Points of measure cover one size. For apparel, add a sizes list and one column per size in spec_page().
One view. Techpacker notes that "For garment sketches, it is typical to have just a front and back view" (source). To add a back view, give each callout a view key and draw a second drawing in the photo column when there is no photo.
Built-in fonts only. Helvetica covers English specs. For notes in other writing systems, register a TTF font with pdfmetrics.registerFont(TTFont(...)) first.
No cost sheet, and nothing about compliance labels. Those usually live in a separate document anyway.

The parts that are worth copying even if you rebuild everything else: trim and threshold the drawing before layout, store pins as fractions of the trimmed drawing, hand reportlab JPEG bytes for photos, measure tables before placing images, and let a missing tolerance stop the build.

Seedance 2.5 prompt: write and validate a shot timeline

virse — Fri, 11 Sep 2026 03:54:58 +0000

AI-generated editorial illustration for this workflow, not a model test result.

A Seedance 2.5 prompt is easier to review when it assigns each shot a time span, an action, a camera instruction and a continuity rule. Write that timeline before generation, check it for gaps or overlaps, and judge the output against the visible events you actually requested.

Seedance 2.5 on Virse is an entry point for checking the available generation controls. This article develops a planning format and a local Python validator, not a provider API integration; its product-video brief is an illustrative example. Disclosure: This article was drafted with AI for Virse's content program.

In this guide: what should a seedance 2.5 prompt specify first; how do you turn the idea into a shot timeline; what should each shot contain; can python catch timeline errors before you render; how do you turn the timeline into a complete brief.

What should a Seedance 2.5 prompt specify first?

Specify the task and the intended ending before adding style. Decide whether you want a continuous shot, a sequence with cuts, or a change to existing footage.

ByteDance's Seedance 2.5 announcement describes longer storytelling, multimodal references and editing capabilities. The exact controls exposed by a hosting application still need a separate check. A model-level description does not establish what inputs or durations your current account can use.

For the example below, the task is a short product sequence about a desk lamp. The viewer should see the lamp, understand its adjustable arm, then reach a stable final composition. This is a useful brief because each stage has a distinct purpose.

The requested duration is 12 seconds for illustration. Use a duration supported by the selected interface in a real generation. The timeline is a way to organize intent; it does not guarantee that the model will execute every transition at an exact frame.

How do you turn the idea into a shot timeline?

Allocate time to visible actions and state what must remain consistent across the sequence. Avoid filling the timeline with abstract mood changes that a reviewer cannot identify in the result.

This sample uses four segments:

Time	Shot purpose	Requested action	Continuity requirement
0 to 3 seconds	Establish	Show the lamp on a desk	Preserve the approved silhouette
3 to 7 seconds	Explain	Reveal the arm joint in a closer view	Keep the same finish and joint design
7 to 10 seconds	Demonstrate	Show the arm changing position	Preserve believable connection points
10 to 12 seconds	Finish	Hold the selected final composition	Keep space available for an end message

These are proposed timings, not observed output measurements. They give the writer a way to check whether the request fits inside its own stated duration.

Choose whether each boundary represents a cut or a continuing camera move. A prompt that requests both an uninterrupted take and a sudden unrelated viewpoint can create an internal contradiction before generation begins.

If the reference image cannot show the lamp's joint clearly, obtain a better reference or simplify the demonstration. No timeline format can repair missing information about the product's actual construction.

What should each shot contain?

Each shot should identify the subject, its action, the camera behavior and the state that carries into the next shot. Add sound direction only when it serves the scene and is supported by the workflow.

For the establishing shot, you might write:

Show the approved desk lamp on a pale wooden desk. Keep its finish, base shape and arm proportions consistent with the product reference. Use a stationary medium view. The lamp is already on; the illumination stays steady. End with the product fully visible so the next shot can move to the joint detail.

For the detail shot, refer to the same product explicitly. Specify what changes in the viewpoint and what stays unchanged. If the intended sequence includes a cut, name the cut rather than relying on the model to infer it from a new description.

Keep the reference roles stable throughout the prompt. A product image should not become the setting reference halfway through the timeline. A separately labeled lighting reference should influence illumination without replacing the product geometry.

Can Python catch timeline errors before you render?

Yes. A local validator can check arithmetic and ordering. It cannot predict whether the generated footage will follow the plan.

Save the following as check_timeline.py. It uses only Python's standard library and makes no network requests:

import math

def validate_timeline(shots, duration):
    if not math.isfinite(duration) or duration <= 0:
        raise ValueError("Duration must be positive and finite")
    if not shots:
        raise ValueError("Add at least one shot")

    cursor = 0.0
    for index, shot in enumerate(shots, start=1):
        start, end = shot["start"], shot["end"]
        if not all(math.isfinite(x) for x in (start, end)):
            raise ValueError(f"Shot {index}: non-finite time")
        if start < 0 or end <= start:
            raise ValueError(f"Shot {index}: invalid time span")
        if not math.isclose(start, cursor, abs_tol=1e-6, rel_tol=0):
            raise ValueError(f"Shot {index}: gap or overlap")
        if not shot.get("action", "").strip():
            raise ValueError(f"Shot {index}: missing action")
        cursor = end

    if not math.isclose(cursor, duration, abs_tol=1e-6, rel_tol=0):
        raise ValueError("Timeline does not match the total duration")
    return True

if __name__ == "__main__":
    shots = [
        {"start": 0, "end": 3, "action": "Establish the lamp"},
        {"start": 3, "end": 7, "action": "Reveal the arm joint"},
        {"start": 7, "end": 10, "action": "Adjust the arm"},
        {"start": 10, "end": 12, "action": "Hold the ending"},
    ]
    validate_timeline(shots, duration=12)
    print("Timeline is continuous and matches the requested duration")

Python's math documentation explains the finite-number and approximate-equality checks. The tolerance here handles small floating-point differences. It is not a timing tolerance promised by the video model.

Run python check_timeline.py. Then deliberately change the second shot's start to 4 and run it again: the check should report a gap. Change it to 2 to check the overlap path. This makes the validator's limited purpose visible instead of treating a green message as proof that the whole creative brief is correct.

The function expects numeric times and the shown dictionary structure. It is a compact planning example, not a hardened parser for arbitrary user input. Add schema and type validation if you turn it into a shared application.

How do you turn the timeline into a complete brief?

Combine the approved reference roles, the shot sequence and the continuity requirements in plain language. Keep the local JSON or Python data as planning material unless your chosen provider explicitly accepts that format.

Here is an illustrative combined brief:

Create a product sequence of the lamp in the approved reference. Preserve its base, arm joint, finish and proportions throughout. Begin with a stationary medium view on a pale desk. Cut to a closer view that explains the arm joint. Show a small adjustment of the arm while keeping its connection to the base intact. Finish on a stable composition with uncluttered space for an end message. Keep the lighting direction and background consistent across the cuts. Do not add new lettering to the product.

Append the intended time spans if the interface supports that style of direction. Review the submitted text to make sure it still matches the timeline you checked locally.

For provider-specific examples, fal publishes a Seedance 2.5 prompting guide. Treat its controls and examples as belonging to that documented environment; do not copy an API assumption into a different application's prompt box.

How should you review continuity across shots?

Check the product and scene at both sides of each transition, then watch the whole sequence without pausing. The first pass catches object changes; the second catches awkward pacing.

For the desk lamp, compare the base proportions, hinge location, finish and direction of the light. Inspect whether the arm's adjustment remains mechanically plausible. A detail shot that looks attractive in isolation can still introduce a different joint design from the establishing shot.

Write acceptance criteria before selecting your favorite output. A useful criterion is "the lamp retains the same joint structure across the cut." A less useful criterion is "the video looks professional," which leaves the reviewer without a specific decision rule.

Record any manual edit needed to make a clip usable. If an output works after trimming away its final second, save that fact with the accepted version. The original generation and the finished asset are different deliverables.

What should you change after a failed attempt?

Change the instruction connected to the failure, while keeping the successful parts of the brief stable. This gives the next attempt a clear purpose.

If the transition is confusing, make the cut explicit. If the product changes, simplify the scene or strengthen the product reference role. If the action cannot fit into the allocated segment, adjust the timeline or split the sequence into separate jobs.

Keep a small revision log with the output ID, the observed problem and the change made. Do not claim one instruction caused an improvement when several inputs changed together. You can record a preference without pretending it is a controlled experiment.

Does passing the validator mean the prompt is correct?

No. It means the sample timeline has positive, continuous spans that match the stated duration and include action text. It does not check visual feasibility, provider limits, permissions or actual model behavior. Those require separate review of the inputs, the interface and the generated output.

Virse public page captured during editorial preparation. This screenshot documents the page, not a completed generation.

How do sound and copy affect the timeline?

Give spoken lines, visible copy and sound cues enough room in the sequence, then check their behavior in the result. A simple visual action can become crowded when a voice and an end message compete for the same moment.

For the lamp example, decide whether the final hold is for a voiceover, a graphic added later or a clean edit point. Write that purpose into the brief. If you plan to add approved copy in an editor, preserve empty space instead of asking the model to invent lettering.

The validator cannot tell whether a sentence can be spoken naturally inside its time span. Review the audio separately for intelligibility and timing. Record whether sound comes from generation or a later edit, so another teammate does not duplicate or omit that work.

Should every video use timestamps?

No. A simple continuous action may be clearer as a short prose brief. Timestamps help when the order and duration of distinct events matter. Use the structure that makes your intended result easiest to understand, and save the accepted brief with the references and final clip.

MiniMax H3 reference images: build a repeatable shot brief

virse — Fri, 11 Sep 2026 03:39:57 +0000

AI-generated editorial illustration for this workflow, not a model test result.

MiniMax H3 reference images work best as a clearly labeled input set: identify which file supplies the subject, which supplies the setting, and what the written prompt asks to change. Keep that set stable across related shots, and check the actual output for continuity rather than assuming a reference guarantees it.

MiniMax H3 on Virse provides a model entry to inspect when choosing a workspace. This tutorial builds a local planning manifest and a file check; it does not document a Virse API, submit a generation request or report a model benchmark. Disclosure: This article was drafted with AI for Virse's content program.

In this guide: what should minimax h3 reference images control; how do you record the input set; can you catch missing inputs before generation; how do you write the action without changing the subject; what should remain stable across a sequence.

What should MiniMax H3 reference images control?

They should communicate the visual information that is difficult to express precisely in prose, while the prompt explains how that information applies to the shot. Keep identity, setting and visual treatment distinct in the planning document.

MiniMax's full-reference guide distinguishes reference subjects, concrete frame anchors and other media roles. Its detailed formatting belongs to that documented workflow. The simpler manifest below is an editorial planning format you can inspect locally, not a replacement for the provider's request schema.

Consider a fictional product film about an unbranded ceramic mug. A clean product image defines the mug's silhouette. A separate kitchen photograph suggests a setting. Another image might suggest lighting, but its furniture and props should not silently become part of the brief.

Use files you have permission to process and publish. Name them according to their job rather than their download order. subject.png is easier to review than an unexplained screenshot filename, particularly when another person needs to reproduce the input selection.

Build an input manifest. Original explanatory diagram; example instructions, not measured results.

How do you record the input set?

Create a small text file that records the asset paths, their roles and the intended shot. The example uses JSON because it is easy to read and validate with standard Python.

{
  "shot_id": "mug-reveal-a",
  "assets": [
    {"role": "subject", "path": "references/subject.png"},
    {"role": "setting", "path": "references/scene.png"}
  ],
  "prompt": "Keep the mug still. Move the camera slowly closer, then hold.",
  "review": ["silhouette", "handle shape", "surface contact"]
}

Save it as shot.json beside a references directory containing your own files. The path names are example filenames, not downloadable assets. The short prompt is deliberately narrow so that the first review has a clear question: can the shot preserve the object while the viewpoint changes'

Add the model label and visible generation settings to your project log when you run the actual job. Do not silently replace "MiniMax H3" with a similarly named variant. Different interfaces may expose different controls even when they use related model names.

The Python JSON documentation describes how json.loads converts this text into Python objects. No network connection or vendor credentials are needed to inspect the planning file.

Can you catch missing inputs before generation?

Yes. A local check can catch absent files, repeated roles and an empty prompt before you spend time setting up the shot in an application. It cannot verify whether an image depicts the correct product.

Save this as check_shot.py next to the manifest:

import json
from pathlib import Path

def check_shot(manifest):
    manifest = Path(manifest).resolve()
    data = json.loads(manifest.read_text(encoding="utf-8"))
    assets = data.get("assets", [])
    if not assets:
        raise ValueError("Add at least one reference asset")

    roles = []
    for asset in assets:
        role = asset.get("role", "").strip()
        if not role:
            raise ValueError("Every asset needs a role")
        if role in roles:
            raise ValueError(f"Repeated role: {role}")
        roles.append(role)
        filename = asset.get("path", "")
        if not filename:
            raise ValueError(f"Missing path for {role}")
        source = (manifest.parent / filename).resolve()
        if not source.is_file():
            raise FileNotFoundError(f"Missing {role} file: {source}")

    if "subject" not in roles:
        raise ValueError("This workflow requires a subject reference")
    if not data.get("prompt", "").strip():
        raise ValueError("Write a prompt before generating")
    return data

if __name__ == "__main__":
    shot = check_shot("shot.json")
    print(f"Input files found for {shot['shot_id']}")

Run python check_shot.py from that directory. An error identifies the input to fix. A successful result means that the files exist and that this small planning convention is satisfied. It says nothing about image quality, supported upload formats or whether the provider accepts those inputs.

The one-role-per-file rule is a convention for this example. If a project needs several subject views, extend the format with named roles such as subject_front and subject_side, then update the required-role check. Do not change the structure halfway through a series without recording the revision.

Python's pathlib documentation explains the path operations used here. The check resolves asset paths relative to the manifest so that the location of a reference does not depend on where an unrelated script happens to run.

How do you write the action without changing the subject?

Describe the action and the camera separately, then state the visual properties that matter at review. For the mug example, a subject that stays still and a camera that moves closer are different instructions.

Keep appearance separate from action. Original explanatory diagram; example instructions, not measured results.

Use an illustrative shot brief like this:

Use the mug reference for the cup's silhouette, handle and surface finish. Use the kitchen image only for the setting. The mug rests on the counter throughout the shot. The camera makes a slow, straight move toward the mug and finishes on a closer view of the handle. Keep the mug's position and orientation unchanged. Hold the final view briefly so it can be used as an edit point.

If a generated result rotates the mug while the camera also moves, you have a specific issue to diagnose. Simplify the camera instruction or make the object's stationary state clearer before adding further visual effects.

Avoid treating a long list of stylistic adjectives as a substitute for action. "Cinematic" does not tell a reviewer where the subject should be at the end of the clip. An observable endpoint gives both generation and review a clearer target.

What should remain stable across a sequence?

Keep the approved subject reference, the naming scheme and the product constraints stable. Change the shot description intentionally, and record each change next to the result.

For a small sequence, the mug could appear in an establishing shot, a handle detail and a final composition with space for copy. The framing changes, but its contour, finish and handle must remain recognizable as the same object.

Make a reference revision only when you intend to change what the model sees. If the initial image has a cropped handle, replacing it with a clearer view may be sensible. Record that replacement because it can affect the comparison with earlier clips.

For stricter file tracking, store a checksum in your project log. Python's hashlib module can calculate a file digest. A digest helps detect a changed file with the same name; it does not establish copyright ownership or prove that two images show the same product.

How do you review character or product consistency?

Review the beginning, the moments of significant movement and the ending, then watch the clip at normal speed. A still-frame check can reveal structural changes, while playback reveals temporal problems that isolated images miss.

Validate, then compare. Original explanatory diagram; example instructions, not measured results.

For the sample product shot, use this checklist:

The handle retains its shape and attachment points.
The rim does not change thickness during the camera movement.
The base maintains believable contact with the counter.
Reflections change plausibly with the viewpoint.
The final composition provides the intended edit point.

For a character shot, replace the product checks with the relevant identity, wardrobe and pose details. Use an authorized reference and review the movement around occlusions, turns and interactions. Those are useful review moments because they demand a visible transition, not because this article establishes a measured model failure rate at those points.

Record a concrete reason for rejection. "Handle deforms during the approach" is more useful than "bad consistency." If a clip passes all mandatory requirements but you prefer another style, keep that distinction in the review log.

What can this workflow prove?

It can prove that your local inputs satisfy the checks you wrote and that your review record describes a specific output. It cannot prove that the model will preserve identity, that a provider supports every documented mode, or that the same prompt will return an identical clip later.

Before the first generation, inspect the chosen interface's current reference controls. If it accepts only still images, a video-reference workflow requires a different supported entry. Model documentation and application functionality should be checked separately.

Likewise, check the displayed price and available output settings in the actual application. This article deliberately makes no promise about H3 audio behavior, resolution or generation cost across providers.

Is a reference image the same as a first frame?

Not necessarily. A reference may guide the subject's appearance, while a first frame specifies the starting composition. Use the mode supported by your interface and state what the image is meant to control. Confusing those jobs can make a prompt ambiguous even when the uploaded file itself is correct.

Virse public page captured during editorial preparation. This screenshot documents the page, not a completed generation.

How should a team share the reference package?

Share a project folder containing the manifest, the approved references and the selected outputs. Keep those files together so that the relative paths continue to work when another person opens the folder on a different machine.

Add a short readme identifying the approved input version. Keep account credentials and private client material out of a public repository. When a collaborator returns a revision, ask for the changed prompt and any replaced references together. Compare that package with the earlier version before deciding what caused an output to change.

If the files are too large for your code repository, use the team's approved asset storage and keep a stable project record pointing to them. Run the local check after copying the files, then inspect the images. A valid path can still point to the wrong product.

What should you save after a successful shot?

Save the output, the manifest, the exact references, the prompt version and a short acceptance note. Include the visible model and settings used for the job. That package gives the next person enough context to make a deliberate revision instead of reconstructing the setup from memory.