Higgsfield Websites

higgsfield generate create gpt_image_2 \
  --aspect_ratio 3:2 --quality high --resolution 2k --count 2 \
  --image https://static.higgsfield.ai/website-builder/app-cover-generator/refs/scene-epic-film.jpg \
  --prompt "<scene prompt — ends with: no text, no letters, no logos, no captions, no UI>" \
  --wait

higgsfield generate create image_background_remover \
  --image <winning_scene_url_or_id> --wait

python3 compose_cover.py \
  --art scene.png --cutout cutout.png \
  --title "DreamCut" \
  --title-width 0.48 \
  --anchor left --block-x 0.07 --block-y 0.30 \
  --frame-color "#D23B2E" \
  --out-cover dreamcut_cover.png --out-og dreamcut_og.png \
  --out-og-wide dreamcut_og_wide.png

#!/usr/bin/env python3
"""Build Higgsfield-style covers from one full-bleed SCENE image (no text on it).

The image model renders ONLY the scene. ALL typography is drawn here as ONE
structured lockup block, matching the official covers:

        Higgsfield                 <- wordmark (small)
        DREAMCUT                   <- title (huge caps)
        ( Available now at … )     <- CTA pill
(NO tagline by default — the reference lockup has none; --tagline exists
only for an explicit user request.)

Break-out: pass --cutout (subject with alpha from remove_background, same
size as the scene) and on the framed OG variants the subject pops OUT of the
stadium capsule onto the frame color instead of being clipped by the window.
Text is ALWAYS the last (topmost) layer — the subject never covers a letter.

The stadium capsule, frame and corner dots are code too. Outputs:
  --out-cover   full-bleed scene + lockup (marketplace cover)
  --out-og      frame + capsule + dots + lockup, same ratio as the art (3:2)
  --out-og-wide the 1.91:1 social-card variant

ONE typeface: Inter (the title face on the reference cover) renders
EVERYTHING — wordmark, title, CTA. No other font ships in the bundle.

All type is FLAT white. No shadows, no outlines, no gradients — ever.
On framed outputs the whole lockup is clamped INSIDE the stadium capsule
(rounded ends included) — text never touches the frame.

Only Pillow required.

ASSETS: the font + logo glyph are NOT bundled — they are fetched once from the
hosted asset base and cached locally (~/.cache/higgsfield-cover, override with
$COVER_ASSET_CACHE). Point at a different host with $COVER_ASSET_BASE.
"""
import argparse
import colorsys
import os
import sys
import urllib.request

from PIL import Image, ImageDraw, ImageFilter, ImageFont

ALLOWED_FRAMES = {
    "sky-blue": "#A9CFF4",
    "peach": "#F7DDB9",
    "olive": "#7A7D3C",
    "warm-gray": "#D6D3CE",
    "dusty-rose": "#E7B7B0",
    "deep-navy": "#243A5E",
    "signal-red": "#D23B2E",
    "cream": "#F1EEE6",
}
DEFAULT_FRAME = ALLOWED_FRAMES["sky-blue"]
CTA_DEFAULT = "Available now at higgsfield.ai"
# ONE font. Inter Bold — the title face on the reference cover.
BRAND_FONT = "Inter-Variable.ttf"

# Hosted asset base (font + logo). Override with $COVER_ASSET_BASE. The two
# assets live at <base>/fonts/Inter-Variable.ttf and <base>/logo/hf-glyph.png.
ASSET_BASE = os.environ.get(
    "COVER_ASSET_BASE",
    "https://static.higgsfield.ai/website-builder/app-cover-generator",
).rstrip("/")


def cache_dir():
    d = os.environ.get(
        "COVER_ASSET_CACHE",
        os.path.join(os.path.expanduser("~"), ".cache", "higgsfield-cover"),
    )
    os.makedirs(d, exist_ok=True)
    return d


def ensure_asset(rel_path):
    """Return a local path to a hosted asset, downloading + caching on first use.
    rel_path is relative to ASSET_BASE, e.g. 'fonts/Inter-Variable.ttf'."""
    local = os.path.join(cache_dir(), os.path.basename(rel_path))
    if os.path.exists(local) and os.path.getsize(local) > 0:
        return local
    url = f"{ASSET_BASE}/{rel_path}"
    try:
        # A browser-ish User-Agent — some CDNs/WAFs 403 the default urllib UA.
        req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
        with urllib.request.urlopen(req, timeout=30) as r:  # noqa: S310 (trusted host)
            data = r.read()
        with open(local, "wb") as f:
            f.write(data)
        return local
    except Exception as e:  # pragma: no cover - network/host failure
        print(f"WARNING: could not fetch asset {url}: {e}", file=sys.stderr)
        return None


def hex_rgb(s):
    c = s.lstrip("#")
    if len(c) != 6:
        sys.exit(f"bad hex color: {s}")
    return tuple(int(c[i:i + 2], 16) for i in (0, 2, 4))


def check_frame_color(rgb, force):
    h, s, v = colorsys.rgb_to_hsv(*(c / 255 for c in rgb))
    if 40 / 360 <= h <= 160 / 360 and s > 0.55 and v > 0.55:
        msg = ("frame color %02X%02X%02X is in the BANNED acid lime/yellow band. "
               "Allowed: %s" %
               (*rgb, ", ".join(f"{k} {v}" for k, v in ALLOWED_FRAMES.items())))
        if force:
            print("WARNING:", msg)
        else:
            sys.exit("ERROR: " + msg)


def luminance(rgb):
    r, g, b = (c / 255 for c in rgb)
    return 0.2126 * r + 0.7152 * g + 0.0722 * b


def brand_font(px, weight):
    """Inter at the given weight (opsz pinned for display). The ONLY typeface."""
    path = ensure_asset(f"fonts/{BRAND_FONT}")
    if path is None:
        return ImageFont.load_default(px)
    try:
        f = ImageFont.truetype(path, px)
        try:
            f.set_variation_by_axes([32, weight])
        except Exception:
            pass
        return f
    except Exception:
        return ImageFont.load_default(px)


def measure(d, text, font):
    x0, y0, x1, y1 = d.textbbox((0, 0), text, font=font)
    return x1 - x0, y1 - y0, x0, y0


class Lockup:
    """One structured type block: wordmark / title lines / tagline / CTA pill."""

    def __init__(self, a, W, H):
        self.a = a
        probe = ImageDraw.Draw(Image.new("RGB", (8, 8)))
        lines = [ln.strip() for part in a.title.split("\\n")
                 for ln in part.split("\n") if ln.strip()]
        if a.title_caps == "upper":
            lines = [ln.upper() for ln in lines]
        self.title_lines = lines

        # Size the title so its longest line fills the width budget…
        budget = W * a.title_width
        px = round(H * 0.5)
        f = brand_font(px, 700)
        w = max(measure(probe, ln, f)[0] for ln in self.title_lines)
        px = max(24, round(px * budget / max(1, w)))
        # …capped by line height and by total available width at the anchor.
        px = min(px, round(H * a.title_max_h))
        avail = W * (0.94 - a.block_x) if a.anchor == "left" else W * 0.88
        f = brand_font(px, 700)
        w = max(measure(probe, ln, f)[0] for ln in self.title_lines)
        if w > avail:
            px = round(px * avail / w)
        self.title_px = px
        self.f_title = brand_font(px, 700)

        glyph_path = ensure_asset("logo/hf-glyph.png")
        self.glyph = (Image.open(glyph_path).convert("RGBA")
                      if glyph_path and os.path.exists(glyph_path) else None)
        self.f_word = brand_font(max(16, round(px * 0.26)), 650)
        self.f_tag = brand_font(max(14, round(px * 0.20)), 500)
        self.f_cta = brand_font(max(13, round(px * 0.17)), 500)
        self.cta_pad_y = round(px * 0.14)
        self.cta_pad_x = round(px * 0.30)

        def rows_for(names):
            rows = []
            if "word" in names and a.wordmark:
                rows.append(("word", a.wordmark, self.f_word, 0))
            if "title" in names:
                for i, ln in enumerate(self.title_lines):
                    gap = round(px * (0.30 if (i == 0 and a.wordmark) else 0.10 if i else 0))
                    rows.append(("title", ln, self.f_title, gap))
            if "tag" in names and a.tagline:
                rows.append(("tag", a.tagline, self.f_tag, round(px * 0.26)))
            if "cta" in names and a.cta:
                rows.append(("cta", a.cta, self.f_cta, round(px * 0.30)))
            out = []
            for kind, text, font, gap in rows:
                tw, th, ox, oy = measure(probe, text, font)
                if kind == "cta":
                    tw += 2 * self.cta_pad_x
                    th += 2 * self.cta_pad_y
                if kind == "word" and self.glyph is not None:
                    gh = round(th * 1.3)
                    tw += round(gh * self.glyph.width / self.glyph.height) \
                        + round(th * 0.45)
                    th = max(th, gh)
                out.append([kind, text, font, gap, tw, th, ox, oy])
            return out

        self.rows = rows_for(("word", "title", "tag", "cta"))
        self.width = max(r[4] for r in self.rows)
        self.height = sum(r[3] + r[5] for r in self.rows)

    def origin(self, W, H, window=None):
        a = self.a
        bx = round(W * a.block_x)
        by = round(H * a.block_y)
        if a.anchor == "center":
            bx -= self.width // 2
        bx = max(round(W * 0.05), min(bx, W - self.width - round(W * 0.05)))
        by = max(round(H * 0.07), min(by, H - self.height - round(H * 0.075)))
        if window:
            # Framed variant: the WHOLE block must sit inside the stadium
            # capsule, including its rounded ends — never on/over the frame.
            wx0, wy0, wx1, wy1 = window
            r = (wy1 - wy0) / 2
            cy = (wy0 + wy1) / 2
            pad = round(W * 0.015)
            by = max(wy0 + pad, min(by, wy1 - self.height - pad))
            for _ in range(3):
                dy = max(abs(by - cy), abs(by + self.height - cy))
                dx = r - (max(r * r - dy * dy, 0.0)) ** 0.5
                lo = round(wx0 + dx) + pad
                hi = round(wx1 - dx) - pad - self.width
                bx = max(lo, min(bx, max(lo, hi)))
                by = max(wy0 + pad, min(by, wy1 - self.height - pad))
        return bx, by

    def render(self, im, cutout=None, window=None):
        """Layer order: scene -> scrim -> subject cutout -> ALL text LAST.

        The cutout's only job is the capsule break-out on the framed OG
        variants (the subject pops over the frame like the official covers).
        Text is always the topmost layer and never hidden by the subject."""
        a = self.a
        W, H = im.size
        bx, by = self.origin(W, H, window)
        base = im.convert("RGBA")

        if a.scrim > 0:
            scr = Image.new("L", (W, H), 0)
            pad = round(self.title_px * 0.8)
            ImageDraw.Draw(scr).rounded_rectangle(
                (bx - pad, by - pad, bx + self.width + pad, by + self.height + pad),
                radius=pad, fill=a.scrim)
            scr = scr.filter(ImageFilter.GaussianBlur(pad))
            base.alpha_composite(
                Image.composite(Image.new("RGBA", (W, H), (8, 8, 12, 255)),
                                Image.new("RGBA", (W, H), (0, 0, 0, 0)), scr))

        white = (255, 255, 255, 255)

        def draw_rows(target, kinds):
            layer = Image.new("RGBA", (W, H), (0, 0, 0, 0))
            d = ImageDraw.Draw(layer)
            y = by
            for kind, text, font, gap, tw, th, ox, oy in self.rows:
                y += gap
                if kind not in kinds:
                    y += th
                    continue
                x = bx if a.anchor == "left" else bx + (self.width - tw) // 2
                if kind == "cta":
                    ss = 4
                    tile = Image.new("RGBA", (tw * ss, th * ss), (0, 0, 0, 0))
                    td = ImageDraw.Draw(tile)
                    td.rounded_rectangle((0, 0, tw * ss - 1, th * ss - 1),
                                         radius=th * ss // 2, fill=(15, 15, 18, 135),
                                         outline=(255, 255, 255, 115), width=ss)
                    layer.alpha_composite(tile.resize((tw, th), Image.LANCZOS), (x, y))
                    d.text((x + self.cta_pad_x - ox, y + self.cta_pad_y - oy),
                           text, font=font, fill=white)
                elif kind == "word" and self.glyph is not None:
                    twt, tht, oxt, oyt = measure(d, text, font)
                    gh = round(tht * 1.3)
                    gw = round(gh * self.glyph.width / self.glyph.height)
                    tile = Image.new("RGBA", (tw, th), (0, 0, 0, 0))
                    tile.alpha_composite(
                        self.glyph.resize((gw, gh), Image.LANCZOS), (0, (th - gh) // 2))
                    ImageDraw.Draw(tile).text(
                        (gw + round(tht * 0.45) - oxt, (th - tht) // 2 - oyt),
                        text, font=font, fill=white)
                    layer.alpha_composite(tile, (x, y))
                else:
                    d.text((x - ox, y - oy), text, font=font, fill=white)
                y += th
            target.alpha_composite(layer)

        if cutout is not None:
            base.alpha_composite(cutout.convert("RGBA"))
        draw_rows(base, {"title", "word", "tag", "cta"})
        return base.convert("RGB")


def stadium_mask(size, box):
    W, H = size
    ss = 4 if max(W, H) <= 1800 else 2
    big = Image.new("L", (W * ss, H * ss), 0)
    r = (box[3] - box[1]) // 2
    ImageDraw.Draw(big).rounded_rectangle([v * ss for v in box],
                                          radius=r * ss, fill=255)
    return big.resize((W, H), Image.LANCZOS)


def draw_dots(im, dot_rgb):
    W, H = im.size
    dr = max(3, round(W * 0.008))
    ox, oy = round(W * 0.028), round(H * 0.045)
    ss = 4
    tile = Image.new("RGBA", (dr * 2 * ss, dr * 2 * ss), (0, 0, 0, 0))
    ImageDraw.Draw(tile).ellipse((0, 0, dr * 2 * ss - 1, dr * 2 * ss - 1),
                                 fill=(*dot_rgb, 255))
    tile = tile.resize((dr * 2, dr * 2), Image.LANCZOS)
    for cx in (ox, W - ox):
        for cy in (oy, H - oy):
            im.paste(tile, (cx - dr, cy - dr), tile)


def crop_box_for(size, ratio):
    w, h = size
    if w / h > ratio:
        nw = round(h * ratio)
        x = (w - nw) // 2
        return (x, 0, x + nw, h)
    nh = round(w / ratio)
    y = (h - nh) // 2
    return (0, y, w, y + nh)


def touches_edges(piece, band_h, band_w):
    """True if the subject plate has meaningful alpha in the top or side
    bands of the window — i.e. the subject actually reaches the capsule
    edge and a breakout is possible."""
    alpha = piece.getchannel("A")
    w, h = alpha.size
    for bbox in (
        (0, 0, w, max(1, band_h)),          # top band
        (0, 0, max(1, band_w), h),          # left band
        (w - max(1, band_w), 0, w, h),      # right band
    ):
        region = alpha.crop(bbox)
        hist = region.histogram()
        solid = sum(hist[128:])
        if solid > 0.005 * (region.width * region.height):
            return True
    return False


def build_framed(art, cutout, canvas_ratio, a, frame_rgb, dot_rgb):
    W = art.width
    H = round(W / canvas_ratio)
    mx, my = round(W * a.margin_x), round(H * a.margin_y)
    box = (mx, my, W - mx, H - my)
    bw, bh = box[2] - box[0], box[3] - box[1]
    cb = crop_box_for(art.size, bw / bh)

    scene = Image.new("RGB", (W, H), frame_rgb)
    scene.paste(art.crop(cb).resize((bw, bh), Image.LANCZOS), (box[0], box[1]))

    cut = None
    mask_box = box
    if cutout is not None:
        # UNCLIPPED on purpose: the subject breaks out of the capsule onto the
        # frame (official look — Cinema Studio 4's boot + ball over the green).
        cut = Image.new("RGBA", (W, H), (0, 0, 0, 0))
        piece = cutout.crop(cb).resize((bw, bh), Image.LANCZOS)
        cut.paste(piece, (box[0], box[1]), piece)
        # ADAPTIVE window shrink: only if the subject actually reaches the
        # window's top/side edges does the window pull in (top + sides,
        # bottom stays flush) so the full-size plate pops over the capsule
        # with zero ghosting. Otherwise the window keeps the full scene —
        # no wasted frame ring.
        ins = round(bh * a.pop_inset)
        if ins > 0 and touches_edges(piece, round(bh * 0.06), round(bw * 0.04)):
            mask_box = (box[0] + ins, box[1] + ins, box[2] - ins, box[3])

    mask = stadium_mask((W, H), mask_box)
    out = Image.composite(scene, Image.new("RGB", (W, H), frame_rgb), mask)
    if not a.no_dots:
        draw_dots(out, dot_rgb)
    return Lockup(a, W, H).render(out, cut, window=mask_box)


def main():
    p = argparse.ArgumentParser(description=__doc__,
                                formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("--art", required=True, help="full-bleed SCENE image, no text on it")
    p.add_argument("--cutout", help="subject-with-alpha PNG aligned to --art "
                                    "(remove_background output); pops out of the OG capsule")
    p.add_argument("--title", required=True, help=r"product name; '\n' splits lines")
    p.add_argument("--title-caps", choices=["upper", "keep"], default="upper")
    p.add_argument("--title-width", type=float, default=0.52,
                   help="longest title line as fraction of canvas width (0.35-0.62)")
    p.add_argument("--title-max-h", type=float, default=0.26)
    p.add_argument("--wordmark", default="Higgsfield", help="'' to disable")
    p.add_argument("--tagline", default="")
    p.add_argument("--cta", default=CTA_DEFAULT, help="'' to disable")
    p.add_argument("--anchor", choices=["left", "center"], default="left")
    p.add_argument("--block-x", type=float, default=0.07)
    p.add_argument("--block-y", type=float, default=0.28)
    p.add_argument("--scrim", type=int, default=90,
                   help="0-255 soft dark scrim behind the block (0 = off)")
    p.add_argument("--out-cover")
    p.add_argument("--out-og")
    p.add_argument("--out-og-wide")
    p.add_argument("--frame-color", default=DEFAULT_FRAME)
    p.add_argument("--force-frame-color", action="store_true")
    p.add_argument("--dot-color", default="auto")
    p.add_argument("--no-dots", action="store_true")
    p.add_argument("--margin-x", type=float, default=0.045)
    p.add_argument("--margin-y", type=float, default=0.055)
    p.add_argument("--pop-inset", type=float, default=0.03,
                   help="with --cutout: shrink the capsule window by this "
                        "fraction of its height (top/sides) so the subject "
                        "plate pops over the edge — applied ONLY when the "
                        "subject actually reaches the window edge; 0 disables")
    p.add_argument("--min-width", type=int, default=1500)
    a = p.parse_args()

    if not (a.out_cover or a.out_og or a.out_og_wide):
        sys.exit("nothing to do: pass --out-cover / --out-og / --out-og-wide")

    frame_rgb = hex_rgb(a.frame_color)
    check_frame_color(frame_rgb, a.force_frame_color)
    dot_rgb = ((26, 26, 26) if luminance(frame_rgb) > 0.55 else (255, 255, 255)) \
        if a.dot_color == "auto" else hex_rgb(a.dot_color)

    art = Image.open(a.art).convert("RGB")
    if art.width < a.min_width:
        sys.exit(f"ERROR: art is {art.width}px wide (< {a.min_width}). Upscale "
                 f"first — do not ship a soft cover.")
    cutout = None
    if a.cutout:
        cutout = Image.open(a.cutout).convert("RGBA")
        if cutout.size != art.size:
            cutout = cutout.resize(art.size, Image.LANCZOS)

    if a.out_cover:
        out = Lockup(a, art.width, art.height).render(art, cutout)
        out.save(a.out_cover)
        print(f"cover    {a.out_cover} {out.size[0]}x{out.size[1]}")

    if a.out_og:
        out = build_framed(art, cutout, art.width / art.height, a, frame_rgb, dot_rgb)
        out.save(a.out_og)
        print(f"og       {a.out_og} {out.size[0]}x{out.size[1]} frame={a.frame_color}")

    if a.out_og_wide:
        out = build_framed(art, cutout, 1.91, a, frame_rgb, dot_rgb)
        out.save(a.out_og_wide)
        print(f"og-wide  {a.out_og_wide} {out.size[0]}x{out.size[1]} frame={a.frame_color}")


if __name__ == "__main__":
    main()