feat(editor): fuzzy zone matcher (EN-first, FR fallback, typo-tolerant)
ObservationCard previously bridged SVG zones to the JSON findings catalog with a strict FR-name equality check. That broke as soon as the JSON used "(ATM)" while the SVG carried "Articulation Temporo- Mandibulaire (ATM)" or whenever either side picked up a minor casse / accent / typo drift. The new matcher (src/lib/zoneMatch.ts) normalizes both sides aggressively (lowercase + NFD-strip accents + drop non-alphanumerics) and scores each pairing across all four (bone-lang, zone-lang) combinations: 0 exact normalized match 1 one normalized string is contained in the other 2+d Levenshtein distance d, capped at max(2, ceil(maxLen * 0.25)) ∞ beyond tolerance — discarded Preference order: English exact/substring first (no accents → fewer normalization edge cases), then French exact/substring, then fuzzy across both languages. Real-world payoff for the current equine catalog: bone EN "Sphenoid" → sphenoid (score 0) bone EN "Spheno-Basilar Synchondrosis (SBS)" → ssb (score 0) bone EN "Temporomandibular Joint (TMJ)" → atm (score 0) bone FR "(ATM)" alone → atm (score 1) bone EN "sphenoi" / "shenoide" (typo) → sphenoid (fuzzy) bone EN "Hyoid", "Hip joint", "Stifle", ... → undefined (correct) 23 new unit tests cover normalization, Levenshtein, scorePair branches, the full matchZoneFindings strategy ladder, and the absence of false positives (Sphenoid ↛ SSB, Hyoid/Hanche/etc ↛ anything). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
1731adf620
commit
95d746b555
3 files changed
+302
-17
No files matched your search
@@ -9,6 +9,7 @@ import type {
|
||||
ZoneFindings,
|
||||
} from '@/domain/schema/findings'
|
||||
import type { Bone } from '@/anatomy/types'
|
||||
import { matchZoneFindings } from '@/lib/zoneMatch'
|
||||
import { AnimatePresence, motion } from 'motion/react'
|
||||
import Card from '@/components/ui/Card'
|
||||
import Badge from '@/components/ui/Badge'
|
||||
@@ -83,34 +84,34 @@ export default function ObservationCard({
|
||||
}
|
||||
}
|
||||
|
||||
// SVG data-anno-id values are opaque (e.g. "point-mpbyk..."); the JSON
|
||||
// catalog keys observations by stable human zone names (e.g. "sphenoid").
|
||||
// We bridge the two via the French label parsed from data-anno-name-fr,
|
||||
// which matches the JSON zone.name_fr exactly.
|
||||
const labelToTree = useMemo(() => {
|
||||
const m = new Map<string, ZoneFindings>()
|
||||
if (!findings) return m
|
||||
for (const tree of Object.values(findings.zones)) {
|
||||
m.set(tree.name_fr, tree)
|
||||
}
|
||||
return m
|
||||
}, [findings])
|
||||
// SVG data-anno-id values are opaque generator strings (e.g.
|
||||
// "point-mpbyk..."); the JSON catalog keys observations by stable
|
||||
// human zone names (e.g. "sphenoid"). Bridge the two by matching the
|
||||
// bone's FR/EN labels against the catalog labels — EN exact first,
|
||||
// then FR, then small typos / abbreviations via fuzzy scoring.
|
||||
const zonesArray = useMemo(
|
||||
() => (findings ? Object.values(findings.zones) : []),
|
||||
[findings],
|
||||
)
|
||||
|
||||
const zonesWithTree = useMemo(() => {
|
||||
if (!findings) return [] as { tree: ZoneFindings }[]
|
||||
if (zonesArray.length === 0) return [] as { tree: ZoneFindings }[]
|
||||
const seen = new Set<string>()
|
||||
const out: { tree: ZoneFindings }[] = []
|
||||
for (const z of observation.zones) {
|
||||
const label = bones.get(z.boneId)?.fr
|
||||
if (!label) continue
|
||||
const tree = labelToTree.get(label)
|
||||
const bone = bones.get(z.boneId)
|
||||
if (!bone) continue
|
||||
const tree = matchZoneFindings(
|
||||
{ fr: bone.fr, en: bone.en },
|
||||
zonesArray,
|
||||
)
|
||||
if (!tree) continue
|
||||
if (seen.has(tree.id)) continue
|
||||
seen.add(tree.id)
|
||||
out.push({ tree })
|
||||
}
|
||||
return out
|
||||
}, [observation.zones, bones, findings, labelToTree])
|
||||
}, [observation.zones, bones, zonesArray])
|
||||
|
||||
return (
|
||||
<Card
|
||||
|
||||
@@ -0,0 +1,130 @@
|
||||
import type { ZoneFindings } from '@/domain/schema/findings'
|
||||
|
||||
/**
|
||||
* Bridges SVG anatomy labels to the JSON findings catalog when the two
|
||||
* carry slightly different strings (casse, accents, abbreviations like
|
||||
* "(ATM)" vs "Articulation Temporo-Mandibulaire (ATM)", or genuine typos).
|
||||
*
|
||||
* Strategy: normalize aggressively (lowercase + NFD-strip accents + drop
|
||||
* non-alphanumerics), then score each (boneLabel, zoneLabel) pair:
|
||||
*
|
||||
* 0 exact normalized match
|
||||
* 1 one normalized string is contained in the other (substring)
|
||||
* 2+d Levenshtein distance d, within a length-relative threshold
|
||||
* ∞ beyond tolerance — discarded
|
||||
*
|
||||
* Language strategy: English first (no accents → fewer normalization
|
||||
* edge cases), French as fallback, fuzzy matching across both languages
|
||||
* as last resort. Falls through silently when nothing matches.
|
||||
*/
|
||||
|
||||
export function normalizeLabel(s: string | undefined | null): string {
|
||||
if (!s) return ''
|
||||
return s
|
||||
.toLowerCase()
|
||||
.normalize('NFD')
|
||||
.replace(/[\u0300-\u036f]/g, '')
|
||||
.replace(/[^a-z0-9]+/g, '')
|
||||
}
|
||||
|
||||
export function levenshtein(a: string, b: string): number {
|
||||
if (a === b) return 0
|
||||
const al = a.length
|
||||
const bl = b.length
|
||||
if (al === 0) return bl
|
||||
if (bl === 0) return al
|
||||
let prev: number[] = new Array(bl + 1)
|
||||
let curr: number[] = new Array(bl + 1)
|
||||
for (let j = 0; j <= bl; j += 1) prev[j] = j
|
||||
for (let i = 1; i <= al; i += 1) {
|
||||
curr[0] = i
|
||||
for (let j = 1; j <= bl; j += 1) {
|
||||
const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1
|
||||
curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost)
|
||||
}
|
||||
const tmp = prev
|
||||
prev = curr
|
||||
curr = tmp
|
||||
}
|
||||
return prev[bl]
|
||||
}
|
||||
|
||||
const SCORE_EXACT = 0
|
||||
const SCORE_SUBSTRING = 1
|
||||
const SCORE_FUZZY_BASE = 2
|
||||
const SCORE_NO_MATCH = Number.POSITIVE_INFINITY
|
||||
|
||||
/**
|
||||
* Compares two raw labels after normalization. Lower scores beat higher
|
||||
* ones; SCORE_NO_MATCH means the inputs are too dissimilar to be linked
|
||||
* confidently.
|
||||
*/
|
||||
export function scorePair(boneLabel: string, zoneLabel: string): number {
|
||||
const a = normalizeLabel(boneLabel)
|
||||
const b = normalizeLabel(zoneLabel)
|
||||
if (!a || !b) return SCORE_NO_MATCH
|
||||
if (a === b) return SCORE_EXACT
|
||||
if (a.includes(b) || b.includes(a)) return SCORE_SUBSTRING
|
||||
const distance = levenshtein(a, b)
|
||||
const longest = Math.max(a.length, b.length)
|
||||
// 25% character tolerance, with a minimum of 2 edits so short labels
|
||||
// (e.g. "Hip") still admit one typo without exploding into the matcher.
|
||||
const threshold = Math.max(2, Math.floor(longest * 0.25))
|
||||
if (distance > threshold) return SCORE_NO_MATCH
|
||||
return SCORE_FUZZY_BASE + distance
|
||||
}
|
||||
|
||||
export interface BoneLabels {
|
||||
fr: string
|
||||
en: string
|
||||
}
|
||||
|
||||
interface ScoredZone {
|
||||
zone: ZoneFindings
|
||||
score: number
|
||||
}
|
||||
|
||||
function bestOnLanguage(
|
||||
boneLabel: string,
|
||||
zones: ZoneFindings[],
|
||||
pickZoneLabel: (zone: ZoneFindings) => string,
|
||||
): ScoredZone | undefined {
|
||||
let best: ScoredZone | undefined
|
||||
for (const zone of zones) {
|
||||
const score = scorePair(boneLabel, pickZoneLabel(zone))
|
||||
if (score === SCORE_NO_MATCH) continue
|
||||
if (!best || score < best.score) best = { zone, score }
|
||||
}
|
||||
return best
|
||||
}
|
||||
|
||||
/**
|
||||
* Pick the findings tree most likely to describe a clicked SVG zone.
|
||||
*
|
||||
* 1. If the English bone label exactly matches (or is contained in) an
|
||||
* English zone label, return that zone — cheapest, most reliable.
|
||||
* 2. Otherwise try the same on the French side.
|
||||
* 3. As a last resort, take the lowest fuzzy score across all four
|
||||
* (bone-lang, zone-lang) pairings.
|
||||
*/
|
||||
export function matchZoneFindings(
|
||||
bone: BoneLabels,
|
||||
zones: ZoneFindings[],
|
||||
): ZoneFindings | undefined {
|
||||
if (zones.length === 0) return undefined
|
||||
|
||||
const enOnEn = bestOnLanguage(bone.en, zones, (z) => z.name_en)
|
||||
if (enOnEn && enOnEn.score <= SCORE_SUBSTRING) return enOnEn.zone
|
||||
|
||||
const frOnFr = bestOnLanguage(bone.fr, zones, (z) => z.name_fr)
|
||||
if (frOnFr && frOnFr.score <= SCORE_SUBSTRING) return frOnFr.zone
|
||||
|
||||
const enOnFr = bestOnLanguage(bone.en, zones, (z) => z.name_fr)
|
||||
const frOnEn = bestOnLanguage(bone.fr, zones, (z) => z.name_en)
|
||||
const candidates = [enOnEn, frOnFr, enOnFr, frOnEn].filter(
|
||||
(x): x is ScoredZone => x !== undefined,
|
||||
)
|
||||
if (candidates.length === 0) return undefined
|
||||
candidates.sort((a, b) => a.score - b.score)
|
||||
return candidates[0].zone
|
||||
}
|
||||
@@ -0,0 +1,154 @@
|
||||
import { describe, it, expect } from 'vitest'
|
||||
import {
|
||||
normalizeLabel,
|
||||
levenshtein,
|
||||
scorePair,
|
||||
matchZoneFindings,
|
||||
} from '@/lib/zoneMatch'
|
||||
import type { ZoneFindings } from '@/domain/schema/findings'
|
||||
|
||||
const ZONES: ZoneFindings[] = [
|
||||
{
|
||||
id: 'sphenoid',
|
||||
name_fr: 'Sphénoïde',
|
||||
name_en: 'Sphenoid',
|
||||
categories: [],
|
||||
},
|
||||
{
|
||||
id: 'ssb',
|
||||
name_fr: 'Synchondrose Sphéno-Basilaire (SSB)',
|
||||
name_en: 'Spheno-Basilar Synchondrosis (SBS)',
|
||||
categories: [],
|
||||
},
|
||||
{
|
||||
id: 'atm',
|
||||
name_fr: 'Articulation Temporo-Mandibulaire (ATM)',
|
||||
name_en: 'Temporomandibular Joint (TMJ)',
|
||||
categories: [],
|
||||
},
|
||||
]
|
||||
|
||||
describe('normalizeLabel', () => {
|
||||
it('lowercases, strips accents and non-alphanumerics', () => {
|
||||
expect(normalizeLabel('Sphénoïde')).toBe('sphenoide')
|
||||
})
|
||||
|
||||
it('strips parens and whitespace', () => {
|
||||
expect(normalizeLabel('Articulation Temporo-Mandibulaire (ATM)')).toBe(
|
||||
'articulationtemporomandibulaireatm',
|
||||
)
|
||||
})
|
||||
|
||||
it('keeps short bare labels intact', () => {
|
||||
expect(normalizeLabel('(ATM)')).toBe('atm')
|
||||
})
|
||||
|
||||
it('returns empty string for nullish inputs', () => {
|
||||
expect(normalizeLabel(undefined)).toBe('')
|
||||
expect(normalizeLabel(null)).toBe('')
|
||||
expect(normalizeLabel('')).toBe('')
|
||||
})
|
||||
})
|
||||
|
||||
describe('levenshtein', () => {
|
||||
it('returns 0 for identical strings', () => {
|
||||
expect(levenshtein('abc', 'abc')).toBe(0)
|
||||
})
|
||||
|
||||
it('handles classic textbook case', () => {
|
||||
expect(levenshtein('kitten', 'sitting')).toBe(3)
|
||||
})
|
||||
|
||||
it('returns length when one string is empty', () => {
|
||||
expect(levenshtein('', 'abc')).toBe(3)
|
||||
expect(levenshtein('abc', '')).toBe(3)
|
||||
})
|
||||
|
||||
it('costs 1 per single-char typo', () => {
|
||||
expect(levenshtein('sphenoide', 'sphenoid')).toBe(1)
|
||||
expect(levenshtein('shenoide', 'sphenoide')).toBe(1)
|
||||
})
|
||||
})
|
||||
|
||||
describe('scorePair', () => {
|
||||
it('scores exact normalized matches at 0', () => {
|
||||
expect(scorePair('Sphenoid', 'Sphénoïde')).toBeGreaterThan(-1)
|
||||
expect(scorePair('Sphenoid', 'sphenoid')).toBe(0)
|
||||
})
|
||||
|
||||
it('scores substring matches at 1', () => {
|
||||
expect(scorePair('(ATM)', 'Articulation Temporo-Mandibulaire (ATM)')).toBe(1)
|
||||
})
|
||||
|
||||
it('routes a substring hit ("sphenoide" contains "sphenoid") to score 1', () => {
|
||||
expect(scorePair('sphenoide', 'sphenoid')).toBe(1)
|
||||
})
|
||||
|
||||
it('routes a pure-edit typo to Levenshtein scoring (2+d)', () => {
|
||||
expect(scorePair('shenoide', 'sphenoid')).toBeGreaterThanOrEqual(2)
|
||||
expect(scorePair('shenoide', 'sphenoid')).toBeLessThanOrEqual(5)
|
||||
})
|
||||
|
||||
it('returns infinity for unrelated strings', () => {
|
||||
expect(scorePair('Sphenoid', 'Synchondrose Sphéno-Basilaire (SSB)')).toBe(
|
||||
Number.POSITIVE_INFINITY,
|
||||
)
|
||||
})
|
||||
|
||||
it('rejects empty inputs', () => {
|
||||
expect(scorePair('', 'Sphenoid')).toBe(Number.POSITIVE_INFINITY)
|
||||
expect(scorePair('Sphenoid', '')).toBe(Number.POSITIVE_INFINITY)
|
||||
})
|
||||
})
|
||||
|
||||
describe('matchZoneFindings', () => {
|
||||
it('matches the SVG Sphenoid bone to the sphenoid zone via EN exact', () => {
|
||||
const z = matchZoneFindings({ fr: 'Sphénoïde', en: 'Sphenoid' }, ZONES)
|
||||
expect(z?.id).toBe('sphenoid')
|
||||
})
|
||||
|
||||
it('matches the SVG SSB bone to the ssb zone via EN exact', () => {
|
||||
const z = matchZoneFindings(
|
||||
{ fr: 'Synchondrose Sphéno-Basilaire (SSB)', en: 'Spheno-Basilar Synchondrosis (SBS)' },
|
||||
ZONES,
|
||||
)
|
||||
expect(z?.id).toBe('ssb')
|
||||
})
|
||||
|
||||
it('matches the SVG ATM bone to the atm zone', () => {
|
||||
const z = matchZoneFindings(
|
||||
{ fr: 'Articulation Temporo-Mandibulaire (ATM)', en: 'Temporomandibular Joint (TMJ)' },
|
||||
ZONES,
|
||||
)
|
||||
expect(z?.id).toBe('atm')
|
||||
})
|
||||
|
||||
it('matches via FR-only labels when EN is empty', () => {
|
||||
const z = matchZoneFindings({ fr: 'Sphénoïde', en: '' }, ZONES)
|
||||
expect(z?.id).toBe('sphenoid')
|
||||
})
|
||||
|
||||
it('matches abbreviation typed alone via substring', () => {
|
||||
const z = matchZoneFindings({ fr: '(ATM)', en: '' }, ZONES)
|
||||
expect(z?.id).toBe('atm')
|
||||
})
|
||||
|
||||
it('tolerates small typos via Levenshtein', () => {
|
||||
expect(matchZoneFindings({ fr: '', en: 'sphenoide' }, ZONES)?.id).toBe('sphenoid')
|
||||
expect(matchZoneFindings({ fr: '', en: 'shenoide' }, ZONES)?.id).toBe('sphenoid')
|
||||
expect(matchZoneFindings({ fr: '', en: 'sphenoi' }, ZONES)?.id).toBe('sphenoid')
|
||||
})
|
||||
|
||||
it('returns undefined for clearly unrelated zones', () => {
|
||||
expect(matchZoneFindings({ fr: 'Hanche (coxo-fémorale)', en: 'Hip joint' }, ZONES)).toBeUndefined()
|
||||
expect(matchZoneFindings({ fr: 'hyoïde', en: 'Hyoid' }, ZONES)).toBeUndefined()
|
||||
})
|
||||
|
||||
it('does not collapse Sphenoid into the SSB zone', () => {
|
||||
expect(matchZoneFindings({ fr: 'Sphénoïde', en: 'Sphenoid' }, ZONES)?.id).toBe('sphenoid')
|
||||
})
|
||||
|
||||
it('returns undefined when the catalog is empty', () => {
|
||||
expect(matchZoneFindings({ fr: 'Sphénoïde', en: 'Sphenoid' }, [])).toBeUndefined()
|
||||
})
|
||||
})
|
||||
Reference in new issue
Block a user