LED Similarity Calculator Skill

Guidance for working with LEDSimilarityCalculator in the lib-electronic-components library.

For metadata-driven similarity architecture, see /similarity-metadata:

• SpecImportance levels (CRITICAL, HIGH, MEDIUM, LOW, OPTIONAL)
• ToleranceRule types (exactMatch, percentageTolerance, minimumRequired, etc.)
• SimilarityProfile contexts (DESIGN_PHASE, REPLACEMENT, COST_OPTIMIZATION, etc.)
• Calculator integration patterns and gotchas

Overview

The LEDSimilarityCalculator compares LEDs based on:

• LED family - Same manufacturer series
• Bin codes - Brightness and color temperature bins
• Color temperature - Must match for high similarity

Applicable Types

ComponentType.LED
// Any type starting with "LED_"
// Uses getBaseType() == ComponentType.LED

Returns false for null type.

Similarity Thresholds

HIGH_SIMILARITY = 0.9;   // Same LED, same color temp
MEDIUM_SIMILARITY = 0.7; // Different families but valid LEDs
LOW_SIMILARITY = 0.3;    // Different color temperatures

LED Equivalent Groups

TI High-Power LED Series

LG LED Series

Samsung LM Series

Nichia NCS Series

Bin Code Handling

LEDs use bin codes for brightness and color sorting:

Brightness Bins (Typical)

• K, L, M, N - Brightness grades

Color Temperature Bins (Cree)

• FK* - One color temperature
• FC* - Different color temperature

// Same color temperature = HIGH
calculator.calculateSimilarity("XPERED-L1-FKA", "XPERED-L1-FKB", registry);
// Returns 0.9

// Different color temperatures = LOW
calculator.calculateSimilarity("XPERED-L1-FKA", "XPERED-L1-FCA", registry);
// Returns 0.3

Family Detection

Package Compatibility

Test Examples

// Same LED
calculator.calculateSimilarity("TLHR5400", "TLHR5400", registry);
// Returns 0.9

// Same family, different bin
calculator.calculateSimilarity("TLHR5400", "TLHR5401", registry);
// Returns 0.9

// LG variants with suffix
calculator.calculateSimilarity("LG R971", "LG R971-KN", registry);
// Returns 0.9

// Different color temps
calculator.calculateSimilarity("XPERED-L1-FKA", "XPERED-L1-FCA", registry);
// Returns 0.3

Metadata-Driven Implementation (January 2026)

Status: ✅ Converted (PR #118)

The LEDSimilarityCalculator now uses a metadata-driven approach with spec-based comparison.

Specs Compared

Implementation Pattern

// Short-circuit check for CRITICAL incompatibility
if (!color1.isEmpty() && !color2.isEmpty() && !color1.equals(color2)) {
    return LOW_SIMILARITY;
}

// Weighted spec scoring
// color: CRITICAL (1.0 weight)
// family: HIGH (0.7 weight)
// brightness: HIGH (0.7 weight)
// package: LOW (0.2 weight)

// Family boost for known equivalent groups
if (areSameFamily(mpn1, mpn2)) {
    similarity = Math.max(similarity, HIGH_SIMILARITY);
}

Behavior Changes

Why more accurate: Metadata approach prioritizes color matching (CRITICAL) and separates family from brightness considerations.

Learnings & Quirks

Color Temperature Codes

• Cree uses FK/FC in bin codes to indicate color temp
• Same base LED with different color temps are NOT equivalent

Brightness Bin Codes

• Adjacent brightness bins (K vs L) are usually interchangeable
• Large gaps in brightness bins may not be suitable substitutes

LG LED Format

• Format: LG R971-KN where -KN is the suffix variant
• All suffix variants of same base part are equivalent

Package Suffixes

• -RL, -RT = Tape and reel packaging
• -TUBE = Tube packaging
• These don't affect LED equivalence