Image sampling, palette extraction, and duotone processing

Representative automated fixture coverage

Hue Codex imports versioned JSON fixtures and tests the corresponding pure production functions directly. The groups below are the representative regression evidence most relevant to this methodology.

• Image-sampling fixtures: Known RGBA pixel grids, coordinate bounds, alpha handling, averages, and deterministic samples. View the JSON fixtures.
• Export fixtures: Displayed-versus-exported values, parseable CSS and JSON, and safe allowlisted SVG output. View the JSON fixtures.

What a pass means. A passing group confirms the named vectors and tested properties still match the documented implementation. It does not prove every possible input, final browser rendering, full accessibility conformance, profile-aware print output, or every downstream export consumer.

Selected image files are not uploaded or sent to Hue Codex servers. Image Eyedropper, Image Palette Extractor, and Duotone Generator load the user-selected file in the browser, draw it to canvas, and calculate samples, palettes, previews, and PNG downloads from browser-held pixel data.

This claim covers the selected image file used by the image tools; ordinary page requests, analytics, fonts, scripts, or external assets are governed by the site privacy policy and should not receive image file contents.

Browser limitations, cross-origin image rules, and user-selected files still determine whether canvas pixel data can be read.

Hue Codex samples the pixels returned by the browser canvas, not the original file bytes or an embedded-profile color-managed source representation. The image tools create 2D canvas contexts with willReadFrequently enabled and do not pass a colorSpace option such as display-p3.

Because Hue Codex does not request a wide-gamut canvas, sampled channels are treated as encoded sRGB-style RGBA values in the 0..255 range. HEX, RGB, HSL, OKLCH, contrast, palette buckets, and duotone math are derived from those returned channel values.

If a browser decodes an ICC-profiled image, wide-gamut image, EXIF-oriented image, or compressed image differently before drawing it to canvas, Hue Codex reports the browser-converted canvas pixels. The image tools do not preserve Display P3 source coordinates, expose raw profile values, or perform profile-aware conversion.

Image Eyedropper converts the pointer location from viewport CSS pixels to the canvas backing-store coordinate system, then maps that point into the contained image bounds and finally to a browser-decoded source-image pixel.

Hue Codex does not multiply pointer coordinates by devicePixelRatio directly. It uses the ratio between the intrinsic canvas size and the rendered CSS box, so CSS scaling is handled by canvas.width / rect.width and canvas.height / rect.height.

Source coordinates are nearest source pixels after browser image decoding and drawImage() behavior. Hue Codex does not parse EXIF orientation itself, so coordinates follow the image orientation and pixel data exposed by the browser-rendered canvas.

rect = canvas.getBoundingClientRect()
canvasX = (event.clientX - rect.left) * (canvas.width / rect.width)
canvasY = (event.clientY - rect.top) * (canvas.height / rect.height)

if canvasX < bounds.x or canvasX > bounds.x + bounds.width:
  return no_sample
if canvasY < bounds.y or canvasY > bounds.y + bounds.height:
  return no_sample

normalizedX = (canvasX - bounds.x) / bounds.width
normalizedY = (canvasY - bounds.y) / bounds.height
sourceX = round(clamp(normalizedX * (sourceWidth - 1), 0, sourceWidth - 1))
sourceY = round(clamp(normalizedY * (sourceHeight - 1), 0, sourceHeight - 1))

Image Eyedropper maps pointer coordinates to the rendered image canvas, reads the selected pixel area, and returns HEX, RGB, HSL, OKLCH, contrast, and export metadata.

A sample size of one pixel reports the exact canvas pixel. Larger sample sizes average nearby pixels and can smooth JPEG artifacts, antialiasing, and texture noise.

Image Palette Extractor scans the sampled canvas at a quality-dependent pixel step. Pixels with alpha below 0.5 are skipped. Partially transparent pixels are composited over the Hue Codex paper color, #FBFAF5 (RGB 251, 250, 245), before bucketing.

Colors first enter deterministic rounded RGB buckets, with optional neutral merging. Those coarse buckets are converted to OKLab, ranked for the selected focus, used as deterministic starting centroids, and refined through weighted nearest-centroid assignment. Every sampled bucket contributes its count to a final cluster, so displayed coverage describes the final palette rather than only the initial seed buckets.

Image Palette Extractor does not reject a source merely because it exceeds 20 megapixels. Once the browser decodes a selected file, the tool immediately creates a bounded local working copy whose longest edge matches the highest supported extraction-quality input, reports both original and analysis dimensions, and releases the full-resolution image reference instead of retaining it for later palette renders.

The role shortlist does not generate or repair colors. It assigns four distinct, unmodified final cluster centroids to Surface, Text, Primary, and Secondary; derives higher-contrast black or white action foregrounds; and reports the five pairings shown in the specimen. A final centroid is source-derived because it is a weighted average of assigned source buckets, but it is not guaranteed to equal one literal source pixel. The resulting palette is evidence-backed source material, not a finished brand or design system.

When no unique source-only assignment passes all five shown pair contracts, Hue Codex preserves the colors, labels the role set incomplete, exposes every ratio through the role inspector, and offers recovery through UI-focused extraction, additional swatches, or a handoff to Palette Generator for deliberate fitting. The extractor never silently changes source-derived colors to force a pass.

Custom SVG and PNG palette cards are rendered from the derived swatches and supported settings. Layout, theme, value format, scale, branding, edit link, QR code, role labels, token names, and pair-specific accessibility notes can be changed independently. The local source image is not embedded, and an exact edit link restores supported settings and derived colors rather than source pixels or the local filename.

The selected image is decoded by the browser, drawn to a sample canvas, then scanned at the pixel step for the chosen quality mode. The sample canvas longest side is capped by max dimension before scanning, so browser decoding and image resizing can affect the exact pixel stream.

Bucket keys are deterministic. For non-neutral buckets, each composited RGB channel is rounded to the nearest multiple of the quality bucket size, then clamped to 0..255. When neutral merging is enabled and channel spread is within the neutral threshold, Hue Codex uses one neutral key based on midpoint lightness instead of three separate RGB channel keys.

Weighted OKLab refinement is also deterministic. Quick uses three centroid updates, Balanced uses four, and Detailed uses five. Hue Codex always runs that fixed iteration count; it does not use an early-stop convergence test. Assignment ties keep the first centroid because a later centroid replaces the current choice only when its squared OKLab distance is strictly smaller. An empty cluster retains its prior centroid. Final centroids are converted to clamped, rounded sRGB channels for display. Final coverage is the assigned sample count divided by all accepted samples; average fit is the count-weighted Delta E 76 distance between coarse bucket representatives and their assigned final centroids.

# Partial alpha pixels are composited over Hue Codex paper #FBFAF5 first.
r = round(r * alpha + 251 * (1 - alpha))
g = round(g * alpha + 250 * (1 - alpha))
b = round(b * alpha + 245 * (1 - alpha))

spread = max(r,g,b) - min(r,g,b)
midpoint = (max(r,g,b) + min(r,g,b)) / 2

if merge_neutrals and spread <= quality.neutralSpread:
  key = "neutral-" + round(midpoint / quality.neutralStep) * quality.neutralStep
else:
  key = clamp(round(r / quality.bucketSize) * quality.bucketSize, 0, 255),
        clamp(round(g / quality.bucketSize) * quality.bucketSize, 0, 255),
        clamp(round(b / quality.bucketSize) * quality.bucketSize, 0, 255)

coverage = min(100, entry.coveragePercent * 7)
lightness = entry.oklch.l * 100
middleLightness = 100 - abs(lightness - 54)
surfaceBonus = entry.isNeutral and lightness >= 82 ? 30 : 0
inkBonus = entry.isNeutral and lightness <= 24 ? 30 : 0
accentBonus = entry.oklch.c >= 0.09 and 30 <= lightness <= 76 ? 22 : 0

dominant = coverage*1.45 + entry.oklch.c*70
balanced = coverage*0.82 + entry.oklch.c*210 + middleLightness*0.25
vivid = coverage*0.48 + entry.oklch.c*520 + middleLightness*0.15
ui = coverage*0.72 + surfaceBonus + inkBonus + accentBonus + middleLightness*0.14

diversityDelta = focus == dominant ? max(4, quality.diversityDelta - 3)
                                   : quality.diversityDelta

centers = select_ranked_seed_centroids(requested_count, diversityDelta)
repeat quality.iterations times:
  assign each coarse bucket to nearest center in OKLab
  update each center to the sample-count-weighted OKLab mean

finalCoverage(cluster) = assignedSampleCount(cluster) / acceptedSampleCount

A complete role set requires four distinct final cluster colors. Hue Codex evaluates every unique Surface, Text, Primary, and Secondary assignment independently of the selected presentation sort. It first maximizes how many of the five shown pair contracts pass, then compares normalized contract fitness, a visual-role heuristic, and finally the ascending Surface/Text/Primary/Secondary HEX tuple for deterministic ties.

The accessibility thresholds are scoped to the shown specimen pairings, not the palette as a universal system. Body text on Surface and derived black-or-white text on each action require 4.5:1. Primary and Secondary against Surface require 3:1 as UI/non-text checks. Pass/fail uses the unrounded ratio; displayed ratios are rounded only for reporting.

If fewer than four distinct centroids exist, no four-role set is assigned. If four or more exist but the best assignment does not pass all five checks, Hue Codex displays that best incomplete assignment with its failures and keeps every source-derived color unchanged. Users can request more swatches, use UI-focused extraction, or hand the extracted palette to Palette Generator when intentional color fitting is acceptable.

Duotone Generator estimates source luminance from RGB channels, maps that luminance through contrast and midtone controls, then mixes between the selected shadow and highlight colors. Intensity blends the duotone result back toward the original pixel.

Downloaded PNG output is rendered from source image dimensions when a source image is available. CSS duotone output is an approximation for live treatments and may not match the exact PNG pixels.

Hue Codex duotone rendering uses encoded 8-bit sRGB channel values from canvas pixels. It does not linearize sRGB channels, convert through Lab or OKLab, apply ICC profiles, or run a perceptual gamut-mapping step.

The luminance value is a tone-mapping signal calculated with WCAG-style coefficients on encoded RGB channels. Because the channels are not linearized first, this is not the full WCAG relative-luminance formula used for contrast conformance.

inputs:
  source pixel = r,g,b,a8 where r,g,b,a8 are canvas channels in 0..255
  shadow = Rs,Gs,Bs from shadow HEX
  highlight = Rh,Gh,Bh from highlight HEX
  intensity = clamp(controlIntensity / 100, 0, 1)
  contrast = controlContrast / 100
  midtone = controlMidtone / 100

# Encoded-sRGB tone signal. This is not WCAG relative luminance because
# the r,g,b channels are not linearized before applying the coefficients.
luminance = (0.2126*r + 0.7152*g + 0.0722*b) / 255

# Contrast expands or compresses tone around the midpoint.
tone0 = clamp(((luminance - 0.5) * contrast) + 0.5, 0, 1)

# Midtone is strongest at tone 0.5 and has no effect at tone 0 or tone 1.
midtoneWeight = 1 - abs((tone0 * 2) - 1)
tone = clamp(tone0 + midtone * midtoneWeight, 0, 1)

# Shadow/highlight ramp in encoded sRGB.
duoR = round(Rs + (Rh - Rs) * tone)
duoG = round(Gs + (Gh - Gs) * tone)
duoB = round(Bs + (Bh - Bs) * tone)

# Intensity blends from the original encoded RGB toward the duotone RGB.
outR = round(r + (duoR - r) * intensity)
outG = round(g + (duoG - g) * intensity)
outB = round(b + (duoB - b) * intensity)
outA = a8

These fixtures are small unprofiled sRGB PNGs with known pixel matrices. Expected values assume the browser returns matching encoded sRGB-style RGBA canvas pixels through getImageData(); browser decoding, profile handling, and resampling can still affect arbitrary real images.

The tiny 1x1 and 2x2 fixtures are intended for exact-pixel and coordinate tests. Palette stride tests should use the larger checkerboard and ramp fixtures, or a test harness with pixelStep = 1, so quality-mode sampling does not skip the intended pixels.

These steps apply after the browser has decoded the image and exposed canvas pixels. Browser image decoding and color management can still change the input pixels.

quality presets:
  quick:    maxDimension 420, pixelStep 5, bucketSize 36, neutralSpread 18, neutralStep 28, diversityDelta 7
  balanced: maxDimension 640, pixelStep 3, bucketSize 28, neutralSpread 16, neutralStep 22, diversityDelta 9
  detailed: maxDimension 860, pixelStep 2, bucketSize 20, neutralSpread 12, neutralStep 16, diversityDelta 11

extract_palette(canvas, count, quality, focus, sort, merge_neutrals):
  for y from 0 to canvas.height step quality.pixelStep:
    for x from 0 to canvas.width step quality.pixelStep:
      r, g, b, a8 = canvas_pixel(x, y)
      alpha = a8 / 255
      if alpha < 0.5: continue

      # Composite partial alpha over Hue Codex paper #FBFAF5.
      r = round(r * alpha + 251 * (1 - alpha))
      g = round(g * alpha + 250 * (1 - alpha))
      b = round(b * alpha + 245 * (1 - alpha))

      spread = max(r,g,b) - min(r,g,b)
      midpoint = (max(r,g,b) + min(r,g,b)) / 2
      if merge_neutrals and spread <= quality.neutralSpread:
        key = "neutral-" + round(midpoint / quality.neutralStep) * quality.neutralStep
      else:
        key = clamp(round(r / quality.bucketSize) * quality.bucketSize, 0, 255),
              clamp(round(g / quality.bucketSize) * quality.bucketSize, 0, 255),
              clamp(round(b / quality.bucketSize) * quality.bucketSize, 0, 255)

      bucket[key].count += 1
      bucket[key].r += r; bucket[key].g += g; bucket[key].b += b

  candidates = average each bucket and convert to Lab, OKLab, and OKLCH
  ranked = sort candidates by focus_score(entry, focus), then count, then HEX

  diversity = focus == dominant ? max(4, quality.diversityDelta - 3) : quality.diversityDelta
  seeds = []
  for entry in ranked:
    if seeds is empty or min(delta_e_76(entry, seed)) >= diversity:
      seeds.append(entry)
    if seeds length == count: break

  if seeds has fewer than count:
    append highest ranked non-duplicate HEX entries as seeds

  centers = seeds converted to OKLab
  repeat quality.iterations times:
    assign every candidate bucket to its nearest OKLab center
    update each center to the bucket-count-weighted OKLab mean

  final clusters receive the total count of their assigned buckets
  return final clusters sorted by requested mode and labeled by role heuristic

focus_score(entry, focus):
  coverage = min(100, entry.coveragePercent * 7)
  lightness = entry.oklch.l * 100
  middleLightness = 100 - abs(lightness - 54)
  surfaceBonus = entry.isNeutral and lightness >= 82 ? 30 : 0
  inkBonus = entry.isNeutral and lightness <= 24 ? 30 : 0
  accentBonus = entry.oklch.c >= 0.09 and 30 <= lightness <= 76 ? 22 : 0

  if focus == vivid:
    return coverage*0.48 + entry.oklch.c*520 + middleLightness*0.15
  if focus == balanced:
    return coverage*0.82 + entry.oklch.c*210 + middleLightness*0.25
  if focus == ui:
    return coverage*0.72 + surfaceBonus + inkBonus + accentBonus + middleLightness*0.14
  # dominant
  return coverage*1.45 + entry.oklch.c*70

These vectors validate the deterministic pieces of image processing once canvas pixels are available. Browser decoding and color management can still affect real uploaded images.

Tools using this methodology

These Hue Codex tools link to this methodology because they depend on the formulas, assumptions, limits, or data policy described here.

Report a calculation issue

If a result does not match the documented formula or fixture, send the exact input, tool settings, displayed result, expected result, precision mode, and browser details. Please do not include private images, personal information, or secrets.