# IDEA.md – ett program som räknar ut färgblandningar Det här är en fristående uppdragsbeskrivning. Ge den i sin helhet till Claude Code (eller ett liknande verktyg) för att bygga en egen implementation. Den bygger på erfarenheterna från Color Paint, ett skrivbordsprogram för Windows och macOS byggt i Rust med Claude Code. ## 1. Vad som ska byggas Ett skrivbordsprogram som räknar ut **hur färger ska blandas för att träffa en önskad kulör**, med de färger användaren faktiskt har. Problemet: den som färgar epoxi, polyuretan, målarfärg eller annat material behöver ibland träffa en befintlig kulör så nära som möjligt. Att gissa andelar ur en handfull grundfärger går sällan. Webbtjänster som gör det kräver ofta prenumeration och begränsar antalet blandningar per dag. Programmet ska göra samma sak lokalt, utan nät, utan tak. Programmet ska kunna: - **Ta emot en målfärg** som hex (`#7A9668`, `7a9668`, `#abc`), `rgb(…)`, `hsl(…)`, HSV, CMYK, CIELAB eller LCh, med en färgväljare, med pipett ur en bild, eller som en kod eller ett namn ur en färgkarta (`RAL 3020`, `ral3020`, `3020`). Alla fält hålls i synk med varandra. Ctrl+V var som helst i fönstret klistrar in en målfärg. - **Lista de bästa recepten** ur den valda paletten, bäst först. Varje recept har färgerna med heltalsdelar och procent, den förutsagda färgen, ΔE (CIEDE2000) mot målet och ett omdöme. - **Räkna om delarna till mängder** för en sats: gram, milliliter eller droppar. - **Visa en ljushetstrappa**: blandningen med ¼, ½ och 1 del svart respektive vitt per del blandning. Klick på ett steg gör det till målfärg. - **Blandningsbord**: lägg delar av färger med + och − och se den förutsagda blandningen och ΔE mot målet direkt. Ett recept kan öppnas på bordet för att justeras, och blandningen kan göras till ny målfärg. - **Paletter**: en inbyggd standardpalett (15 konstnärsfärger) som inte kan ändras men kan dupliceras. Egna paletter med namn, färg, pigmentkod, tintstyrka och en ruta för aktiv/inaktiv per färg. Import och export som fil. - **Färgkartor**: RAL och färgtillverkarnas kulörer (ungefär 23 000) inbyggda i programmet. En flik visar dem bok för bok som färgprov med sökning. En kulör kan bli målfärg, läggas i en palett eller sparas som recept. Under målfärgen visas de tre närmaste kulörerna med ΔE. - **Sparade recept**: en sparad post är en **målfärg** med namn, anteckning, datum och projekt – inte delar. När den öppnas räknas receptet fram mot den valda paletten som den ser ut just då. Lista med sökning, gruppering och filter per projekt, export som CSV och JSON. Samma färg sparas bara en gång. - **Pipett ur bild**: öppna PNG eller JPEG, klicka, medelvärde över 1×1, 5×5 eller 11×11 pixlar. Visa bildens åtta dominerande färger (k-means) som prov. Ingår **inte**: pipett direkt från skärmen, spektrofotometer, utskrift, Pantone/NCS (licens och varumärken), tvåkonstantsmodell med uppmätta spektra, import av en hel färgbok som palett (lösaren blir för långsam, se avsnitt 5). ## 2. Stack och arkitektur Color Paint valde följande. Det som är **viktigt** är markerat; resten går att byta. - **Rust** (edition 2024), en Cargo-workspace med två crates. Valt för att det ger en liten, snabb, fristående binär utan runtime, och för att syskonprojekten använder samma uppsättning. Går att byta, men lösaren måste vara kompilerad kod eller motsvarande snabb. - **Viktigt: en UI-fri kärna** (`core`) och ett separat fönsterprogram (`app`). Kärnan innehåller färgrymder, blandningsmodellen, lösaren, paletter, färgkartor, biblioteket och pipettens matematik. Den testas utan fönster. Allt som går att räkna ska gå att testa utan att starta programmet. - **eframe/egui** (0.36) för gränssnittet: omedelbart läge, samma kod på Windows och macOS. Går att byta mot annat ramverk. - **Lösaren på en egen tråd**, så att färgväljaren inte hackar när paletten är stor. Svaret bär med sig vilken palett det räknades i (se Fallgropar). - **Menyn beskrivs en gång som data.** På Windows ritas den i fönstret; på macOS synkas samma modell till systemets menyrad (t.ex. med `muda`). Tangentgenvägar finns på ett enda ställe, och menyn formaterar sin genvägstext ur samma konstant som utlöser kommandot. Meny, tangentbord och knappar producerar alla samma `Action`-värden som går genom en enda `apply`-funktion. - **Färgkartorna kompileras in** (`include_str!` av en textfil, ca 590 kB). Ingen nedladdning vid körning. - **Data per användare**: paletter och recept i en JSON-fil, skriven atomiskt (skriv till temporär fil, byt namn). `%APPDATA%\\data` på Windows, `~/Library/Application Support/` på macOS. - **Tredjepartsdata**: spektraltabellerna från spectral.js (MIT, Ronald van Wijnen) och färgkartorna från colornerd (MIT). Licenserna följer med i `third_party/` och i paketens README. - **Paketering**: Windows-exe korskompilerad med `cargo xwin` till `x86_64-pc-windows-msvc`, NSIS-installerare och portabel zip. macOS `aarch64-apple-darwin`, `.app` och dmg. Versionsnummer `major.minor.bygge`, där byggskripten räknar upp tredje siffran. ## 3. Beslut som visade sig avgörande **Blanda inte i RGB.** Färg blandas subtraktivt: varje pigment absorberar en del av spektrumet. Ett medelvärde av RGB blandar ljus, och gult + blått blir grått i stället för grönt. Det är fel just där användaren behöver hjälp. **Spektral Kubelka-Munk, enkelkonstant, 38 band (380–750 nm).** Samma modell som spectral.js: 1. *Spektrum ur sRGB.* Linjärisera färgen och dela upp den i vitt, cyan, magenta, gult, rött, grönt och blått (Smits 1999). Spektrumet är summan av sju grundkurvor viktade med andelarna. Det ger tillbaka samma färg (ΔE < 1, testa det), men det är bara *ett* av många spektra som ger den färgen. 2. *K/S per band:* `K/S = (1 − R)² / 2R`. 3. *Blanda:* medelvärdesbilda K/S viktat med koncentrationen `c = delar² × tintstyrka² × luminans`. Räkna tillbaka till reflektans med `R = 1 + K/S − √((K/S)² + 2·K/S)`, vidare till XYZ, Lab och sRGB. Kvadraten på delarna och luminansvikten är spectral.js empiriska val, inte fysik. Utan dem dränker vitt allt det blandas med. Mixbox bedömdes ge bättre resultat men har licensen CC BY-NC och kan därför inte användas. **Tintstyrka per färg.** Samma RGB säger inte hur stark en färg är: ftaloblått och ultramarin kan se lika ut tunt utstrukna, men ftaloblått tar över en blandning med vitt helt. Varje färg har därför en tintstyrka som multipliceras in i koncentrationen. Standardpalettens värden **kalibreras**, inte gissas: välj för varje färg en typisk ljushet L* för en 1:1-tint med titanvitt, och sök den tintstyrka som ger den ljusheten. Lägg kalibreringen i ett test som körs på begäran och skriver ut de nya värdena. Riktvärden (L* för 1:1 med vitt → tintstyrka): Ivory Black 40 → 2,71; Cadmium Yellow Light 92 → 0,84; Cadmium Yellow Medium 85 → 1,20; Cadmium Red Light 64 → 1,08; Cadmium Red Medium 57 → 1,25; Quinacridone Magenta 55 → 1,57; Alizarin Crimson 55 → 1,31; Dioxazine Purple 40 → 2,78; Ultramarine Blue 50 → 1,87; Phthalo Blue 45 → 2,47; Phthalo Green 50 → 2,58; Yellow Ochre 80 → 0,93; Burnt Sienna 60 → 1,28; Burnt Umber 50 → 1,94. Titanium White 1,0. Det är uppskattningar, och de är det första att justera när recept slår fel. **Lösaren.** 1. Pröva alla kombinationer av 1, 2 och 3 aktiva färger. Pröva 4 färger bara som förlängningar av de 30 bästa trefärgskombinationerna – annars växer sökningen för fort. 2. För varje kombination: lägg ett grovt rutnät över andelarna (simplexet; 24 steg för två färger, 12 för tre, 6 för fyra), varje färg minst 0,5 %. Förfina den bästa punkten med koordinatsökning: flytta andel mellan två färger i taget, halvera steget när inget blir bättre, sluta under 1e-4. Målfunktionen är CIEDE2000 mot målet. 3. Avrunda de ~80 bästa kombinationerna till heltalsdelar: pröva varje totalsumma upp till *Max parts* (standard 20), dela med största gemensamma delare, och **välj den minsta totalsumman som ligger inom 0,5 ΔE från den bästa**. Då väljs 3 : 1 före 14 : 5. Bedöm receptet på de avrundade delarna, så att färgen som visas är den man faktiskt får. 4. Rangordna med 0,35 ΔE i straff per färg utöver den första. Ta bort dubbletter (samma färguppsättning). 5. Omdöme ur ΔE: < 1 Exact ("No visible difference"), < 2 Excellent ("Visible only side by side"), < 5 Good, < 10 Approximate, annars Out of reach ("This palette cannot mix the color. Add a paint closer to it."). Säg det rakt ut när paletten inte räcker. Inställningar: färger per recept 1–4, *Avoid black*, *Max parts*, satsstorlek och enhet. **Ett sparat recept är en målfärg, inte delar.** Paletten ändras – färger tar slut, nya kommer till. Spara målfärgen med namn, anteckning, datum och projekt, och räkna fram receptet mot den aktuella paletten när det öppnas. Från blandningsbordet sparas blandningens färg; med samma palett räknar lösaren fram samma blandning igen. Namnet föreslås ur färgkartan när målet är en kulör där. **Färgkartornas kulörer är vanliga färger.** Modellen räknar fram spektrum ur sRGB för *alla* färger, även standardpalettens. En kulör ur en karta kan alltså läggas i en palett och blandas som vilken färg som helst, med tintstyrka 1,0. Märk tydligt i gränssnittet att värdena är tillverkarnas skärmfärger, inte uppmätta prover. **En sanningskälla för genvägar och meny**, se avsnitt 2. Ett nytt kommando läggs in på ett ställe och dyker upp i menyn, i tangentbordet och på båda plattformarna. **Utvecklarhjälp från dag ett.** Miljövariabler som låter en agent granska gränssnittet utan att någon sitter vid skärmen: - `_DATA_DIR=dir` – egen datakatalog, så att en testkörning inte rör användarens data - `_WINDOW=1240x800@X,Y` – fönsterstorlek och läge - `_SCREENSHOT=fil.ppm` – spara en bild av fönstret och avsluta; `_SCREENSHOT_DELAY=N` bildrutor att vänta först - `_DEBUG_STATE=…` – kommaseparerade steg som sätter lägen vid start: `tab=…`, `target=#hex|RAL 3020`, `type=text`, `chart=…`, `book=…`, `palette=…`, `board=Namn:2;Namn:1`, `recipe=N`, `project=…`, `dialog=save|rename`, `do=save:Namn|duplicate|new|add` - `_DEBUG_MENU=Recipe` – fäll upp en meny så att den syns i bilden Varje debugsteg ska gå **samma väg** som menyn eller knappen det motsvarar, annars bevisar skärmbilden ingenting. ## 4. Fallgropar - **Visa recept ihop med paletten de räknades i, inte den valda.** Annars pekar recepten ut färger med index i den förra paletten när användaren byter palett, skapar en ny tom palett eller tar bort en färg – och programmet kraschar (`index out of bounds: the len is 0 but the index is 12`). Låt lösarens svar bära sin palett, och stäng av "Load Best Recipe" tills svaret gäller den valda paletten. Skriv ett test som frågar om en tom palett medan svaret för standardpaletten visas. - **Räkna med att en panik är osynlig på Windows.** Ett release-bygge utan konsol visar ingen felruta – fönstret bara försvinner. Reproducera med debugstegen och kontrollera avslutningskoden (101 vid panik, 0 normalt). - **Anta inte att en färg utan uppmätt spektrum inte kan blandas.** Ingen färg i modellen har ett uppmätt spektrum; alla räknas fram ur sRGB. Den felaktiga premissen kostade ett extra varv. - **Tvätta tredjepartsdata innan den byggs in.** colornerd har `rgb(…)` i stället för hex hos en tillverkare, blanksteg före `#` hos två, blandade format hos en, och dubblettkoder (Behr 43, Benjamin Moore 12, Kilz 41, MPC 3). Vissa namn är bara koden igen, och vissa är avhuggna ("HC-154 Hale" i stället för "Hale Navy"). Skriv ett importskript som tolkar varje värde med samma färgtolk som programmet, tar bort dubbletter, sätter prefix på koderna (`RAL 3020`, `SW 0001`) och kan köras om. - **Ta inte med tryckfärgsböcker** (DIC, HKS, TOYO, Trumatch), papper eller folie: de är kommersiella system eller ointressanta för färgblandning. Ta målarfärgstillverkarna och RAL. - **Gör inte en hel färgbok till palett.** Lösaren klarar runt 30 färger per palett; 4 000 gör den obrukbart långsam. - **Spara inte delar i recepten.** Se avsnitt 3. Läs ändå in gamla filer med delar, och behåll deras målfärg, namn och anteckning. - **Bygg inte i `target/` på en Windows-disk från WSL.** På `/mnt/…` faller rustc på `Invalid cross-device link (os error 18)` när den döper om sina filer. Lägg `target/` på Linux-filsystemet (`CARGO_TARGET_DIR` eller en symlänk). - **Ta inte med systemets Klipp ut/Kopiera/Klistra in i macOS-menyn.** Den nativa menyn tar ⌘-tangenterna innan egui ser dem, och då slutar ⌘C/⌘V fungera i textfälten. - **En skärmbild av fönstret når inte macOS-menyraden.** Rita menyn i fönstret med `_DEBUG_MENU` när den ska granskas. - **Ett helt täckt fönster ritas inte på macOS**, och då tas ingen skärmbild. Placera fönstret synligt med `_WINDOW=…@X,Y`. - **Räkna inte upp versionen två gånger för samma utgåva.** Ett misslyckat bygge räknade upp numret; låt en miljövariabel (`_KEEP_BUILD=1`) hålla det stilla. ## 5. Krav och mått Riktmärken från Color Paint (release, Apple Silicon där inget annat sägs): - Lösaren: 15 färger, högst 3 per recept: **13–19 ms** per sökning. Kravet var under 500 ms. Högst 4 per recept: **34 ms**. Lägg ett test med tidsgräns som bara gäller i release. - Färgkartorna: 22 960 kulörer i 16 böcker. Inläsning 9,5 ms en gång, sökning 0,10 ms, närmaste kulör 0,05 ms – ingen cache behövs. Rutnätet ritar bara de rader som syns. - Binären växte från 14,06 till 14,69 MB när kartorna byggdes in. Windows-installeraren 6,3 MB, portabel zip 6,0 MB. - Spektrumet ur sRGB ska ge tillbaka samma färg med ΔE < 1. - Exempel ur standardpaletten att testa mot: - `#7A9668` salvia → 4 Yellow Ochre + 3 Titanium White + 2 Ultramarine Blue, ΔE 0,99 - `#E8C4B8` rosa pastell → 12 Titanium White + 3 Cadmium Red Light + 1 Ultramarine Blue, ΔE 0,73 - `#8B5A2B` sadelbrun → 6 Burnt Umber + 5 Cadmium Yellow Medium + 2 Quinacridone Magenta, ΔE 0,18 - `#00FF00` neongrön → ΔE 9,7, och programmet säger att färgen ligger utanför paletten - Lösaren går att köra från terminalen: ett exempelprogram som tar en målfärg och max antal färger och skriver ut recepten. ## 6. Så verifieras det - **Enhetstester i kärnan** för: färgtolkning (alla notationer och toleranta varianter), att varje färgrymd går fram och tillbaka via RGB, CIEDE2000 mot Sharmas referenspar, att spektrum ur sRGB ger tillbaka färgen, att gult och blått blir grönt och inte grått, att en färg blandad med sig själv är oförändrad, att vitt ljusar utan att flytta kulören mycket, att en känd blandning hittas igen med ΔE < 1, att *max färger*, *Avoid black* och avbockade färger respekteras, att heltalsdelarna blandas om till exakt den visade färgen, att recept behåller sin palett, att alla färgkartans rader läses in, kodvarianter i sökningen, att närmaste-uppslaget stämmer med en fullständig sökning, att gamla biblioteksfiler läses in, att en trasig fil flyttas undan i stället för att skrivas över, och att atomisk skrivning inte lämnar temporära filer. - **Lint och korskontroll**: `cargo clippy --workspace --all-targets` utan varningar, `cargo test --workspace --release`, och `cargo check --target` för den plattform man inte sitter på. - **Gränssnittet granskas med skärmbilder** tagna med utvecklarhjälpen från den riktiga binären – inte antaget. Ett ärende är klart när bilden visar det. - **Röktest av paketet**: starta den paketerade binären med egen datakatalog, spara en palett och ett recept, starta om och kontrollera att de finns kvar. - **Mot riktig färg**: blanda tre recept på riktigt – en grön av gult och blått, en pastell med vitt, en brun – och jämför med förutsägelsen, helst med färgmätare eller foto i jämnt ljus. Det har *inte* gjorts för Color Paint ännu, och det är där modellen mest behöver prövas: kvadraten på delarna och tintstyrkorna. "Klart" betyder: testerna gröna, clippy tyst, båda plattformarna kontrollerade, och varje gränssnittsändring visad i en skärmbild. ## 7. Arbetssätt - **Plan först.** Börja med research på liknande program (Trycolors, Mixbox, spectral.js, Golden-blandare, "Paint Mixer"-appar) och skriv en plan: blandningsmodell, lösare, begränsningar. Dela upp arbetet i små ärenden med en tydlig gräns för vad som inte ingår. - **Fråga om verkliga beslut, inte om allt.** Exempel: ska färgkartorna vara mål eller blandfärger? Vilka böcker ska med? Ska gamla sparade recept bevaras? Kommentera tolkningen innan bygget när premissen skaver – och rätta premissen öppet när den visar sig fel. - **Ett ärende i taget**, med mätningen i avslutskommentaren: tider, antal tester, filstorlekar. - **Testa i en riktig miljö.** Bygg Windows-paketet och kör den riktiga exe-filen med utvecklarhjälpen; ta skärmbilder därifrån. Det som kräver en människa – installeraren, ikonen i Utforskaren, riktiga tangenttryck, blandning av riktig färg – blir egna verifieringsärenden. ## 8. Prompten > Bygg ett skrivbordsprogram för [Windows och macOS] i [Rust med eframe/egui] som räknar ut hur färger ska blandas för att träffa en målfärg, med de färger användaren har. Jag färgar [epoxi och polyuretan / målarfärg / …] och behöver ibland träffa en befintlig kulör så nära som möjligt. > > Läs hela IDEA.md nedan först. Den beskriver funktionerna, blandningsmodellen (spektral Kubelka-Munk som i spectral.js, inte RGB), lösaren, de beslut som visade sig avgörande och fallgroparna att undvika. > > Arbeta så här: > 1. Gör research på liknande program och skriv en plan. Dela upp arbetet i små delar och säg vad som inte ingår. > 2. Lägg all beräkning i ett bibliotek utan gränssnitt, med tester, innan fönstret byggs. > 3. Bygg utvecklarhjälpen (egen datakatalog, fönsterstorlek, skärmbild, debugsteg) tidigt, och granska varje gränssnittsändring med en skärmbild från den riktiga binären. > 4. Fråga mig bara om verkliga beslut, till exempel [vilka färgkartor som ska med, standardpalettens färger, enheter för satsen]. > 5. Mät lösarens tid och redovisa den. Kravet är under 500 ms med [15] färger och högst 3 per recept. > > Min palett: [lista dina färger, gärna med pigmentkod, eller använd standardpaletten i IDEA.md]. > > [klistra in IDEA.md här]