Skip to content

Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.

macOS: the small app icon (Finder Get Info, 16/32 px) is the cube again, not noise (#156, @tristratos)

islandmed3bbbf2057da9
diff --git a/CMakeLists.txt b/CMakeLists.txt
index c5d4a32a..56d57043 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -769,6 +769,9 @@ if(SCULPTFORGE_BUILD_TESTS)
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) # docs/legal/trademarks.md
# No raw string literal in src/ over MSVC's ~16K characters (C2026: only the Windows build would fail).
add_test(NAME raw_literal_size COMMAND ${Python3_EXECUTABLE} -I ${CMAKE_CURRENT_SOURCE_DIR}/tools/dev/check_literals.py)
+ # assets/branding/sculptforge.icns: every slot decodes at its size, 16/32 px as RGB + mask, never PNG (#156).
+ add_test(NAME icns COMMAND ${Python3_EXECUTABLE} -I ${CMAKE_CURRENT_SOURCE_DIR}/tools/brand/icns.py)
+ add_test(NAME icns_self_test COMMAND ${Python3_EXECUTABLE} -I ${CMAKE_CURRENT_SOURCE_DIR}/tools/brand/icns.py --self-test)
add_test(NAME macos_api COMMAND ${Python3_EXECUTABLE} -I ${CMAKE_CURRENT_SOURCE_DIR}/tools/dev/check_macos_api.py)
add_test(NAME macos_api_self_test COMMAND ${Python3_EXECUTABLE} -I ${CMAKE_CURRENT_SOURCE_DIR}/tools/dev/check_macos_api.py --self-test)
# website/brushes.html #packs matches src/core/BrushPacks.cpp: every brush, its preview and the guide links.
diff --git a/assets/branding/sculptforge.icns b/assets/branding/sculptforge.icns
index a7ef2db4..e1c9ec4f 100644
Binary files a/assets/branding/sculptforge.icns and b/assets/branding/sculptforge.icns differ
diff --git a/changes/fix-macos-icon-small-156.md b/changes/fix-macos-icon-small-156.md
new file mode 100644
index 00000000..32fe1a7e
--- /dev/null
+++ b/changes/fix-macos-icon-small-156.md
@@ -0,0 +1,9 @@
+---
+fixed: macOS: the app's small icon (Finder's Get Info thumbnail, list view, 16 and 32 px) was noise; the .icns now
+ stores those sizes in the classic RGB + mask form Finder draws everywhere (#156, thanks @tristratos).
+testers:
+ - macOS: Finder > Applications > SculptForge > Get Info; the small icon at the top left is the orange cube, as is
+ the list view's icon.
+---
+tools/brand/icns.py writes and checks the .icns (no Pillow); tests icns and icns_self_test. make_icons.py --icns-only
+rebuilds just the .icns. The large slots' pixels are unchanged.
diff --git a/docs/brand.md b/docs/brand.md
index 4252ec6e..8d7fd033 100644
--- a/docs/brand.md
+++ b/docs/brand.md
@@ -28,7 +28,8 @@ The outline cube: Lucide's "box" icon (ISC, credited in `THIRD_PARTY_NOTICES.md`
tile, as it shipped in 0.1-0.10 (088f0cd6, site 71cd4f7) and as the Discord developer portal shows it. Tony 11-06 21:1x:
"I want that back as the icon as it was before". The originals are frozen in `tools/brand/cube-outline/` and copied
pixel for pixel; only sizes that never shipped (24 px, the macOS `.icns` on Apple's grid, apple-touch-icon) are rendered
-from its SVG. Never redraw or retouch it. Comparison sheets: `~/Work/.sf/brand/shots/cube-outline-*.png`.
+from its SVG. Never redraw or retouch it. The `.icns` keeps 16 and 32 px as RGB + mask (`is32`/`il32`), never PNG:
+Finder draws PNG there as noise (#156); `tools/brand/icns.py` checks it (test `icns`). Comparison sheets: `~/Work/.sf/brand/shots/cube-outline-*.png`.
| Where | File |
|---|---|
diff --git a/tools/brand/icns.py b/tools/brand/icns.py
new file mode 100644
index 00000000..20769579
--- /dev/null
+++ b/tools/brand/icns.py
@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The macOS .icns container: writing it (make_icons.py) and decoding every representation (ctest icns).
+
+No Pillow, so the check runs on every CI machine. The 16 and 32 px 1x slots are the classic RGB + 8-bit mask pairs
+(is32/s8mk, il32/l8mk): Finder's Get Info thumbnail draws PNG data in icp4/icp5 as noise (#156). Larger slots are PNG.
+
+ tools/brand/icns.py [file.icns] exit 1 unless every slot decodes at its size (default: the app's icon)
+ tools/brand/icns.py --self-test the RGB run-length codec round-trips
+"""
+import struct
+import sys
+import zlib
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+APP_ICNS = ROOT / "assets" / "branding" / "sculptforge.icns"
+
+RGB_SLOTS = {"is32": ("s8mk", 16), "il32": ("l8mk", 32)} # the classic pairs: run-length RGB + raw alpha
+PNG_SLOTS = {"ic11": 32, "ic12": 64, "ic07": 128, "ic13": 256, "ic08": 256, "ic14": 512, "ic09": 512, "ic10": 1024}
+LAYOUT = ("is32", "s8mk", "il32", "l8mk") + tuple(PNG_SLOTS) # what write() emits, in order
+GARBLED = ("icp4", "icp5", "icp6") # PNG in these small slots shows as noise in Finder
+
+
+def pack_channel(data):
+ """Apple's run-length code for one 8-bit channel: n<128 copies n+1 bytes, n>=128 repeats one byte n-125 times."""
+ out = bytearray()
+ i, n = 0, len(data)
+ while i < n:
+ run = 1
+ while i + run < n and run < 130 and data[i + run] == data[i]:
+ run += 1
+ if run >= 3:
+ out += bytes((run + 125, data[i]))
+ i += run
+ continue
+ j = i # literals until the next run of 3 (or 128 bytes)
+ while j < n and j - i < 128 and not (j + 2 < n and data[j] == data[j + 1] == data[j + 2]):
+ j += 1
+ out.append(j - i - 1)
+ out += data[i:j]
+ i = j
+ return bytes(out)
+
+
+def unpack_channel(data, pos, count):
+ """One channel of count bytes from data[pos:]; returns (bytes, next pos). Raises ValueError on bad data."""
+ out = bytearray()
+ while len(out) < count:
+ if pos >= len(data):
+ raise ValueError("run-length data ends early")
+ c = data[pos]
+ if c < 128:
+ out += data[pos + 1:pos + 2 + c]
+ pos += 2 + c
+ else:
+ if pos + 1 >= len(data):
+ raise ValueError("run-length data ends early")
+ out += bytes((data[pos + 1],)) * (c - 125)
+ pos += 2
+ if len(out) != count:
+ raise ValueError(f"run-length channel is {len(out)} bytes, not {count}")
+ return bytes(out), pos
+
+
+def pack_rgb(rgba, n):
+ """is32/il32 data from n*n RGBA bytes: the R, G and B planes, each run-length coded."""
+ return b"".join(pack_channel(rgba[c::4]) for c in range(3))
+
+
+def unpack_rgb(data, n):
+ planes, pos = [], 0
+ for _ in range(3):
+ p, pos = unpack_channel(data, pos, n * n)
+ planes.append(p)
+ if pos != len(data):
+ raise ValueError(f"{len(data) - pos} bytes left after the RGB planes")
+ return planes
+
+
+def chunk(kind, data):
+ return kind.encode() + struct.pack(">I", 8 + len(data)) + data
+
+
+def write(path, rgba_at, png_at):
+ """The .icns: rgba_at(n) gives n*n RGBA bytes (16, 32 px), png_at(n) PNG bytes (the larger slots)."""
+ body = b""
+ for kind, (mask, n) in RGB_SLOTS.items():
+ rgba = rgba_at(n)
+ body += chunk(kind, pack_rgb(rgba, n)) + chunk(mask, bytes(rgba[3::4]))
+ for kind, n in PNG_SLOTS.items():
+ body += chunk(kind, png_at(n))
+ Path(path).write_bytes(b"icns" + struct.pack(">I", 8 + len(body)) + body)
+
+
+def chunks(data):
+ if data[:4] != b"icns" or struct.unpack(">I", data[4:8])[0] != len(data):
+ raise ValueError("not an icns, or its length is wrong")
+ i = 8
+ while i < len(data):
+ kind, size = data[i:i + 4].decode("latin-1"), struct.unpack(">I", data[i + 4:i + 8])[0]
+ if size < 8 or i + size > len(data):
+ raise ValueError(f"{kind}: bad length {size}")
+ yield kind, data[i + 8:i + size]
+ i += size
+
+
+def decode_png(data):
+ """(width, height) after inflating every row: a truncated or corrupt PNG raises."""
+ if data[:8] != b"\x89PNG\r\n\x1a\n":
+ raise ValueError("not PNG data")
+ pos, idat, ihdr = 8, b"", None
+ while pos < len(data):
+ n, t = struct.unpack(">I4s", data[pos:pos + 8])
+ body = data[pos + 8:pos + 8 + n]
+ if zlib.crc32(t + body) != struct.unpack(">I", data[pos + 8 + n:pos + 12 + n])[0]:
+ raise ValueError(f"PNG {t!r} CRC mismatch")
+ if t == b"IHDR":
+ ihdr = struct.unpack(">IIBBBBB", body)
+ elif t == b"IDAT":
+ idat += body
+ pos += 12 + n
+ w, h, depth, ctype, _, _, interlace = ihdr
+ if (depth, ctype, interlace) != (8, 6, 0):
+ raise ValueError(f"PNG is depth {depth} type {ctype} interlace {interlace}, not 8-bit RGBA")
+ if len(zlib.decompress(idat)) != h * (1 + w * 4):
+ raise ValueError("PNG pixel data is the wrong length")
+ return w, h
+
+
+def check(path):
+ """Problems with the .icns at path (empty when every slot decodes at its size and none is missing)."""
+ problems, seen = [], {}
+ try:
+ for kind, data in chunks(Path(path).read_bytes()):
+ seen[kind] = data
+ except ValueError as e:
+ return [str(e)]
+ for kind in GARBLED:
+ if kind in seen:
+ problems.append(f"{kind}: Finder shows PNG in this slot as noise; use the RGB + mask pair")
+ for kind, (mask, n) in RGB_SLOTS.items():
+ if kind not in seen or mask not in seen:
+ problems.append(f"{kind}/{mask}: missing ({n} px)")
+ continue
+ try:
+ unpack_rgb(seen[kind], n)
+ except ValueError as e:
+ problems.append(f"{kind}: {e}")
+ if len(seen[mask]) != n * n:
+ problems.append(f"{mask}: {len(seen[mask])} bytes, not {n * n}")
+ for kind, n in PNG_SLOTS.items():
+ if kind not in seen:
+ problems.append(f"{kind}: missing ({n} px)")
+ continue
+ try:
+ if decode_png(seen[kind]) != (n, n):
+ problems.append(f"{kind}: {decode_png(seen[kind])}, not {n}x{n}")
+ except ValueError as e:
+ problems.append(f"{kind}: {e}")
+ return problems
+
+
+def self_test():
+ import random
+ rnd = random.Random(156)
+ cases = [b"", b"\x01", b"\x07" * 300, bytes(range(256)) * 2, b"ab" * 200 + b"\x00" * 3 + b"c" * 131]
+ cases += [bytes(rnd.choice((0, 0, 0, 9, rnd.randrange(256))) for _ in range(1024)) for _ in range(200)]
+ for data in cases:
+ packed = pack_channel(data)
+ if unpack_channel(packed, 0, len(data)) != (data, len(packed)):
+ print(f"round trip failed for {data[:16]!r}...", file=sys.stderr)
+ return 1
+ rgba = bytes(rnd.randrange(256) for _ in range(32 * 32 * 4))
+ if unpack_rgb(pack_rgb(rgba, 32), 32) != [rgba[c::4] for c in range(3)]:
+ print("RGB planes round trip failed", file=sys.stderr)
+ return 1
+ print("icns codec OK")
+ return 0
+
+
+def main(argv):
+ if argv[1:] == ["--self-test"]:
+ return self_test()
+ path = argv[1] if len(argv) > 1 else APP_ICNS
+ problems = check(path)
+ for p in problems:
+ print(f"{path}: {p}", file=sys.stderr)
+ if not problems:
+ print(f"{path}: every slot decodes")
+ return 1 if problems else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv))
diff --git a/tools/brand/make_icons.py b/tools/brand/make_icons.py
index c17400c1..c8cb1fe0 100644
--- a/tools/brand/make_icons.py
+++ b/tools/brand/make_icons.py
@@ -2,6 +2,7 @@
"""Builds every SculptForge icon and logo file.
python -I tools/brand/make_icons.py <bust.jpeg> [--discord DIR] [--style outline|filled]
+ python -I tools/brand/make_icons.py --icns-only [--style outline|filled]
Which mark goes where: docs/brand.md. The app icon is the outline cube (Tony 11-06 21:1x: "I want that back as the icon
as it was before"): the files that shipped in 0.1-0.10, frozen in tools/brand/cube-outline/ (Lucide's "box" on a dark
@@ -17,12 +18,14 @@ icon, GitHub avatar).
import argparse
import io
import os
-import struct
import subprocess
import sys
from PIL import Image, ImageDraw, ImageFilter, ImageFont
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import icns # noqa: E402 (tools/brand/icns.py)
+
ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
SS = 4 # supersampling of masks and drawn shapes
BASE = 1105.0 # the measured tile size the corner profile is sampled at (set by master_from_concept)
@@ -220,26 +223,28 @@ def flat(im, bg=(0x0e, 0x0e, 0x11)):
def write_icns(path):
- """macOS: every iconset slot as PNG (Pillow's writer leaves out the 16 and 32 px 1x ones), on Apple's grid."""
- slots = (("icp4", 16), ("icp5", 32), ("ic11", 32), ("ic12", 64), ("ic07", 128), ("ic13", 256), ("ic08", 256),
- ("ic14", 512), ("ic09", 512), ("ic10", 1024))
- chunks = b""
- for kind, n in slots:
+ """macOS: every iconset slot on Apple's grid (tools/brand/icns.py: 16 and 32 px as RGB + mask, the rest PNG)."""
+ def png(n):
buf = io.BytesIO()
mac(n).save(buf, format="PNG", optimize=True)
- chunks += kind.encode() + struct.pack(">I", 8 + len(buf.getvalue())) + buf.getvalue()
- with open(path, "wb") as f:
- f.write(b"icns" + struct.pack(">I", 8 + len(chunks)) + chunks)
+ return buf.getvalue()
+ icns.write(path, lambda n: mac(n).convert("RGBA").tobytes(), png)
def main():
ap = argparse.ArgumentParser()
- ap.add_argument("bust")
+ ap.add_argument("bust", nargs="?")
ap.add_argument("--discord")
ap.add_argument("--style", choices=("outline", "filled"), default="outline")
+ ap.add_argument("--icns-only", action="store_true", help="only assets/branding/sculptforge.icns (no bust needed)")
a = ap.parse_args()
global STYLE
STYLE = a.style
+ if a.icns_only:
+ write_icns(os.path.join(ROOT, "assets", "branding", "sculptforge.icns"))
+ return print("done")
+ if not a.bust:
+ ap.error("the bust concept art is needed (or --icns-only)")
def png(im, *path):
im.save(os.path.join(ROOT, *path), optimize=True)