Hyperpigmentation

Overview

Hyperpigmentation measures areas of skin that are darker than the surrounding tissue — sun damage, post-inflammatory marks, melasma overlap, age spots. The value is the larger of two sub-scores — a diffuse area component and a discrete dark-spot component (both returned in sum_measures) — so it reflects the worse of the two, not their sum. The base hyperpigmentation score is normalized within the user’s own skin tone; hyperpigmentation_adjusted rescales for comparability across skin tones. The visualization channel returns spot-type features — one feature per detected pigmented spot, suitable for marker overlays.

component: hyperpigmentation
request:
  query: "components=hyperpigmentation,hyperpigmentation_adjusted,hyperpigmentation_visualization"
response_path: "results[].description == \"hyperpigmentation\""
value_range: [0, 1]
also_request:
  - hyperpigmentation_adjusted       # cross-tone-comparable variant
  - hyperpigmentation_visualization  # spot-type features, intensity range [0..400]
warnings: [401]

Reference imagery

Reference imagery for this metric is not yet published.

When to use which variant

For new integrations, prefer the standalone melasma / freckles / dark_spots metrics above. If you’re maintaining an existing hyperpigmentation integration:

Goal	Use
User-relative dashboard (“your level vs. last month”)	`hyperpigmentation`
Cross-user comparisons / cohort analytics	`hyperpigmentation_adjusted`
Per-spot marker rendering on the face	`hyperpigmentation_visualization`

Rendering notes

const hp = response.results.find((r) => r.description === "hyperpigmentation");
const score = Math.round(hp.value * 100);

Beyond the top-level value, the finding exposes two sum_measures — area (diffuse pigmentation) and spot (discrete dark spots), each 0..1. Each measurement_locations[] entry carries the same area / spot measures plus its own value and mask_shapes.

When a region’s mask can’t be sampled, that region signals unavailability in two different ways — guard for both:

its area and spot measures come back as -1;
the region’s own value comes back as null, not -1.

Either way it means “region unavailable,” not a real low score. (The standalone melasma, freckles and dark_spots metrics are simpler here — their region value is -1 in the same situation.)

For per-spot markers, iterate each measurement location’s visualization_data[] (each feature is a single spot — length: 1, x[0] / y[0] is the centroid, intensity is the feature’s severity in [0..400]). The marker colours are ones you choose, so colour balance doesn’t apply to them; only re-bias a CV-measured colour with inverse_color_balance_rb if you overlay one. Paste-ready: Rendering recipes → Spots.

`local_warnings[]`

Inherits global image-quality codes. Region-mask failures surface as idx: 401.

Recommended instead: melasma, freckles, dark_spots — the standalone pigmentation metrics this legacy aggregate is built from.
How metrics connect — the pigmentation family (hyperpigmentation, dark_spots, freckles, melasma) shares one analysis; hyperpigmentation_adjusted combines shine + dark_spots + melasma.
Visualization data — Cat D (AOI + mask + advanced); spot-type features, intensity range [0..400].
Rendering recipes → Spots — paste-ready dot / box / cross renderers.