Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion backend/snapstudio_api/routes_calibration.py
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,15 @@ def evaluate(data: dict) -> tuple[int, dict]:
family = data.get("family")
if family not in ("frontlit", "backlit"):
raise rv.ValidationError("Invalid 'family'")
material = rv.require_bounded_str(data, "material", 32) if "material" in data else "PLA"
if not material.strip():
raise rv.ValidationError("Material must not be empty")
basis = service.basis_document(family, rv.require_positive_float(data, "layer_height_mm"),
rv.optional_positive_float(data, "nozzle_mm", 0.4),
rv.optional_bounded_str(data, "material", 32) or "PLA")
material,
source=source, model=rv.optional_bounded_str(data, "model", 128),
first_layer_height_mm=rv.require_positive_float(data, "first_layer_height_mm")
if "first_layer_height_mm" in data else None)
palette = decoded.value.to_dict()
result = service.evaluate(palette, basis, _colors(data), _owned(data))
saved = service.save_run(basis, palette, result, data_dir=paths.data_dir())
Expand Down
44 changes: 44 additions & 0 deletions backend/snapstudio_core/calibration/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Palette calibration input and history

DitherForge TXT accepts `#RRGGBB 1.9 Label`, a label without TD, and the
`td=1.9` form. Lines starting with `# `, `;` or `//` are comments. Missing TD
is explicitly nominal (1.0), never a measurement. Invalid or conflicting TD
is not replaced with a nominal value. The earlier Studio `td Label` syntax
remains readable for compatibility.

Kromacut v2 `.kpal` files are JSON objects with `version: 2`, `colors`,
optional `colorNames` and optional `disabledColors` indices. Indices remain
in their original positions. Disabled colours are shown but receive no
physical reading or owned-filament suggestion. The earlier Studio `palette`
row representation remains readable; it is not the upstream export format.
Palette-library arrays and unsupported schema versions are not evaluated.

The screen accepts TXT, JSON and KPAL. Physical observations and owned spool
colours start empty. Changing the palette or the calibration basis clears
observations and invalidates an in-flight result. File reads also have an
identity guard, so an older import cannot replace a later selection.

The visible basis includes family, layer height, first-layer height, nozzle,
material, palette source and an optional user-entered model/revision label.
These fields participate in the basis hash. The label is not a verified model
file identity. Omitted first-layer/model/source data on older history remains
unknown. This changes no database schema: extended basis data stays in the
existing saved comparison payload. History is local, newest first, up to 50;
viewing it never reapplies old readings to current input.

The results are advisory RGB comparisons. No printer, spectrometer or
physical calibration is performed. Tests use synthetic fixtures conforming
to pinned upstream contracts, rather than captured physical readings.

Contract references:
- [DitherForge README](https://github.com/rtwfroody/ditherforge/blob/4d3552a434e8084d9b5fe573959a3493325be29f/README.md)
- [Kromacut palette manager](https://github.com/vycdev/Kromacut/blob/94874755426ee7f33b3684a5544e7fab0e2e73f7/src/lib/paletteManager.ts)


Review follow-up: every explicit TD token is checked, repeated td= assignments
are refused, and leading/fallback values must agree. A blank material is refused;
only an omitted material retains the legacy PLA default. Blank model labels become
unknown. The expanded basis/palette documents change their hashes: pre-change
identities are not reproduced, and old saved comparisons are left untouched.
A numeric leading label such as `#FF0000 2 Tone` is interpreted as TD 2 by the
documented upstream grammar, rather than a label beginning with the number 2.
60 changes: 43 additions & 17 deletions backend/snapstudio_core/calibration/palette.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@ class PaletteEntry:
color: str
td: float
td_provenance: str
enabled: bool = True

def to_dict(self) -> dict:
return {"label": self.label, "color": self.color, "td": self.td,
"td_provenance": self.td_provenance}
"td_provenance": self.td_provenance, "enabled": self.enabled}


@dataclass
Expand Down Expand Up @@ -48,35 +49,35 @@ def parse_ditherforge(text: str) -> Decoded[Palette]:
diagnostics: list[Diagnostic] = []
for number, line in enumerate(text.splitlines(), 1):
stripped = line.strip()
if not stripped or stripped.startswith(";") or stripped.startswith("//"):
if not stripped or stripped.startswith(";") or stripped.startswith("//") or stripped.startswith("# "):
continue
# `td=` is a fallback syntax and may appear after the optional label.
match = _DITHER.match(stripped)
if not match:
diagnostics.append(diag("invalid_palette_line", f"line:{number}", ERROR))
continue
color, remainder = match.groups()
remainder = remainder or ""
# The documented `td label` shape carries a label with no measured TD.
# A numeric value can follow `td`, while `td=<number>` is the fallback form.
fallback = re.search(r"\btd\s*=\s*([0-9.eE+-]+)", remainder, re.IGNORECASE)
td_text = fallback.group(1) if fallback else None
label = remainder
leading_td = re.match(r"^td(?:\s+([0-9.eE+-]+))?(?:\s+|$)(.*)$", remainder, re.IGNORECASE)
assignments = list(re.finditer(r"\btd\s*=\s*(\S*)", remainder, re.IGNORECASE))
values = [item.group(1) for item in assignments]
label = re.sub(r"\btd\s*=\s*\S*", "", remainder, flags=re.IGNORECASE).strip()
leading_td = re.match(r"^td(?:\s+([0-9.eE+-]+))?(?:\s+|$)(.*)$", label, re.IGNORECASE)
numeric = re.match(r"^([+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)(?:\s+|$)(.*)$", label)
if leading_td:
if leading_td.group(1) is not None:
td_text = leading_td.group(1)
values.append(leading_td.group(1))
label = leading_td.group(2)
if fallback:
label = re.sub(r"\btd\s*=\s*[0-9.eE+-]+", "", label or "", flags=re.IGNORECASE).strip()
elif numeric:
values.append(numeric.group(1))
label = numeric.group(2)
try:
td = float(td_text) if td_text is not None else 1.0
numbers = [float(value) for value in values]
except ValueError:
diagnostics.append(diag("invalid_td", f"line:{number}", ERROR))
continue
if not (td > 0 and td < float("inf")):
diagnostics.append(diag("invalid_td", f"line:{number}", ERROR))
numbers = [float("nan")]
if len(assignments) > 1 or any(not (0 < value < float("inf")) for value in numbers) or len(set(numbers)) > 1:
diagnostics.append(diag("invalid_or_conflicting_td", f"line:{number}", ERROR))
continue
td = numbers[0] if numbers else 1.0
td_text = values[0] if values else None
entries.append(PaletteEntry((label or f"Color {len(entries) + 1}").strip(),
f"#{color.upper()}", td,
"provided" if td_text is not None else "derived"))
Expand All @@ -88,6 +89,31 @@ def parse_ditherforge(text: str) -> Decoded[Palette]:


def _build_kromacut(reader) -> Palette:
# Kromacut v2 exports parallel arrays in a .kpal JSON object. Keep every
# original index, including disabled colours, so readings cannot shift rows.
if "colors" in reader.raw:
colors = reader.raw["colors"]
names = reader.raw.get("colorNames", [])
disabled = reader.raw.get("disabledColors", [])
if not isinstance(colors, list) or not colors or len(colors) > 256:
reader.error("invalid_colors", "colors")
return Palette("kromacut_json_v2", [])
if not isinstance(names, list) or len(names) > len(colors) or any(not isinstance(n, str) or len(n) > 256 for n in names):
reader.error("invalid_color_names", "colorNames")
return Palette("kromacut_json_v2", [])
if not isinstance(disabled, list) or any(type(i) is not int or not 0 <= i < len(colors) for i in disabled):
reader.error("invalid_disabled_colors", "disabledColors")
return Palette("kromacut_json_v2", [])
entries = []
for index, raw_color in enumerate(colors):
color = _color(raw_color)
if color is None:
reader.error("invalid_color", f"colors[{index}]")
continue
label = names[index].strip() if index < len(names) else ""
entries.append(PaletteEntry(label or f"Color {index + 1}", color, 1.0, "derived", index not in disabled))
return Palette("kromacut_json_v2", entries)
# Retain the earlier Studio row representation for saved fixtures.
rows = reader.items("palette", required=True)
if not rows:
reader.error("empty_palette", "palette")
Expand Down
19 changes: 15 additions & 4 deletions backend/snapstudio_core/calibration/service.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,21 +30,32 @@
"""


def basis_document(family: str, layer_height_mm: float, nozzle_mm: float, material: str) -> dict:
def basis_document(family: str, layer_height_mm: float, nozzle_mm: float, material: str,
*, source: str | None = None, model: str | None = None,
first_layer_height_mm: float | None = None) -> dict:
if family not in ("frontlit", "backlit"):
raise ValueError("family must be frontlit or backlit")
values = (layer_height_mm, nozzle_mm)
values = (layer_height_mm, nozzle_mm) + (() if first_layer_height_mm is None else (first_layer_height_mm,))
if not isinstance(material, str) or not material.strip() or len(material) > 32:
raise ValueError("material must be a non-empty name of at most 32 characters")
if source not in (None, "ditherforge_txt", "kromacut_json"):
raise ValueError("unknown palette source")
if model is not None and (not isinstance(model, str) or len(model) > 128):
raise ValueError("model must be at most 128 characters")
if any(isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v) or v <= 0 for v in values):
raise ValueError("layer height and nozzle must be positive finite numbers")
normalized = {"family": family, "layer_height_mm": round(float(layer_height_mm), 4),
"nozzle_mm": round(float(nozzle_mm), 4), "material": material.strip().upper()}
normalized.update(source=source, model=(model.strip() or None) if model else None,
first_layer_height_mm=round(float(first_layer_height_mm), 4) if first_layer_height_mm is not None else None)
return {**normalized, "calibration_basis_id": "calibration-basis:" + content_hash(normalized).split(":", 1)[1]}


def evaluate(palette: dict, basis: dict, physical_colors: dict[str, str], owned_filaments: list[dict]) -> dict:
entries = []
for index, item in enumerate(palette["entries"]):
physical = physical_colors.get(str(index))
enabled = item.get("enabled", True)
physical = physical_colors.get(str(index)) if enabled else None
alternatives = []
for spool in owned_filaments:
color = spool.get("color") if isinstance(spool, dict) else None
Expand All @@ -57,7 +68,7 @@ def evaluate(palette: dict, basis: dict, physical_colors: dict[str, str], owned_
entries.append({"label": item["label"], "simulated_color": item["color"],
"physical_color": physical, "physical_distance": material_plan.colour_distance(
item["color"], physical), "td": item["td"],
"td_provenance": item["td_provenance"], "alternatives": alternatives[:3]})
"td_provenance": item["td_provenance"], "enabled": enabled, "alternatives": alternatives[:3] if enabled else []})
return {"calibration_basis": basis, "entries": entries,
"advisory": "Palette colours are simulated targets; physical readings are separate observations. Owned-filament matches are advisory."}

Expand Down
73 changes: 73 additions & 0 deletions backend/tests/calibration/test_real_palette_formats.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
import json
import pytest
from snapstudio_core.calibration import palette, service

def test_upstream_ditherforge_numeric_td_and_comments():
result = palette.parse_ditherforge("# Collection comment\n#FF0000 1.9 Red\n#00FF00 0.4 Green\n#0000FF Blue")
assert result.valid_for_evaluation
assert [(e.label,e.td,e.td_provenance) for e in result.value.entries] == [
("Red",1.9,"provided"),("Green",0.4,"provided"),("Blue",1.0,"derived")]

@pytest.mark.parametrize("td", ["0", "-1", "1e999"])
def test_numeric_td_must_be_positive_finite(td):
assert palette.parse_ditherforge(f"#FF0000 {td} Red").value is None

def test_kromacut_exported_v2_colors_names_and_disabled_indices():
raw = {"version":2,"name":"Synthetic palette","colors":["#FF0000","#00FF00"],
"colorNames":["Red","Green"],"disabledColors":[1],"createdAt":1,"updatedAt":1}
result=palette.parse_kromacut(json.dumps(raw))
assert result.valid_for_evaluation
assert [e.color for e in result.value.entries] == ["#FF0000","#00FF00"]
assert [e.label for e in result.value.entries] == ["Red","Green"]
assert [e.enabled for e in result.value.entries] == [True,False]
assert all(e.td_provenance=="derived" for e in result.value.entries)

@pytest.mark.parametrize("changes", [
{"colors":["not-a-colour"]},{"disabledColors":[9]},{"disabledColors":[True]},
{"colorNames":"not-an-array"}])
def test_invalid_kpal_metadata_is_refused(changes):
raw={"version":2,"colors":["#FF0000"],"colorNames":["Red"],"disabledColors":[]}
assert palette.parse_kromacut({**raw,**changes}).value is None

def test_basis_distinguishes_generator_model_and_first_layer():
common=("frontlit",0.2,0.4,"PLA")
a=service.basis_document(*common,source="ditherforge_txt",model="swatch-A",first_layer_height_mm=0.2)
for changes in [dict(source="kromacut_json"),dict(model="swatch-B"),dict(first_layer_height_mm=0.3)]:
b=service.basis_document(*common,**{**dict(source="ditherforge_txt",model="swatch-A",first_layer_height_mm=0.2),**changes})
assert a["calibration_basis_id"] != b["calibration_basis_id"]

def test_disabled_color_keeps_its_index_without_claiming_a_physical_reading():
from snapstudio_core.calibration.service import evaluate
parsed = palette.parse_kromacut({"version": 2, "colors": ["#112233", "#445566"], "disabledColors": [0]}).value.to_dict()
result = evaluate(parsed, service.basis_document("frontlit", .2, .4, "PLA"), {"0": "#aaaaaa", "1": "#bbbbbb"}, [])
assert result["entries"][0]["enabled"] is False
assert result["entries"][0]["physical_color"] is None
assert result["entries"][1]["physical_color"] == "#bbbbbb"

def test_route_persists_basis_identity_and_real_kpal_rows(tmp_path, monkeypatch):
from snapstudio_api.routes_calibration import evaluate, get_history
import json
monkeypatch.setenv("SNAPSTUDIO_DATA_DIR", str(tmp_path))
code, body = evaluate({"source": "kromacut_json", "content": json.dumps({"version": 2, "colors": ["#123456"]}),
"family": "backlit", "layer_height_mm": .16, "nozzle_mm": .6, "material": "PETG", "model": "synthetic-swatch-2", "first_layer_height_mm": .24})
assert code == 200 and body["status"] == "evaluated"
basis = body["result"]["calibration_basis"]
assert basis["source"] == "kromacut_json" and basis["model"] == "synthetic-swatch-2"
assert basis["first_layer_height_mm"] == .24 and basis["nozzle_mm"] == .6
assert get_history({})[1]["runs"][0]["calibration_basis"] == basis

@pytest.mark.parametrize("row", ["#FF0000 td=oops Red", "#FF0000 td=1.2junk Red", "#FF0000 1.9 Red td=1..2", "#FF0000 1.9 Red td=2"])
def test_invalid_or_conflicting_td_does_not_fall_back_to_nominal(row):
assert palette.parse_ditherforge(row).value is None

@pytest.mark.parametrize("row", ["#FF0000 1.9 Red td=1.9 td=2", "#FF0000 td=1.9 Red td=oops", "#FF0000 td 1.9 Red td=2", "#FF0000 td=1.9 td=1.9"])
def test_all_explicit_td_values_are_validated(row):
assert palette.parse_ditherforge(row).value is None

@pytest.mark.parametrize("material", ["", " "])
def test_empty_material_is_not_silently_replaced_with_pla(tmp_path, monkeypatch, material):
from snapstudio_api.routes_calibration import evaluate
from snapstudio_api.request_validation import ValidationError
monkeypatch.setenv("SNAPSTUDIO_DATA_DIR", str(tmp_path))
with pytest.raises(ValidationError):
evaluate({"source":"ditherforge_txt", "content":"#FF0000 Red", "family":"frontlit", "layer_height_mm":.2, "material": material})
Loading
Loading