Bouldering Route Marking POC

Development assistant for a bouldering route marking and matching proof-of-concept that validates the technical feasibility of identifying climbing routes by marking hold positions on photos.

Project Context

This is a TypeScript/React application that implements a sophisticated matching algorithm combining Modified Hausdorff Distance (MHD) and order-aware similarity to identify bouldering routes from marked hold positions. The system is designed to be tolerant to perspective distortion while maintaining accurate matching capabilities.

Development Commands

When working with this project, use these commands:

Architecture Overview

Storage Layer (`src/lib/storage.ts`)

The storage layer uses OPFS (Origin Private File System) for browser-local persistence:

Matching Algorithm (`src/lib/matching.ts`)

The core matching system consists of several key functions:

1. **normalizePoints()** - Normalizes point sets by translating to centroid and applying RMS scaling

2. **modifiedHausdorffDistance()** - Calculates MHD between two normalized point sets

3. **dtwDistance()** - Implements Dynamic Time Warping for sequence comparison

4. **relativeOrderSimilarity()** - Provides order-aware matching tolerant to perspective distortion

5. **combinedSimilarity()** - Weighted combination (MHD: 0.6, Order: 0.4) producing 0-100% similarity score

6. **searchRoutes()** - Searches for matching routes using the combined algorithm

**Algorithm Parameters:**

Data Management (`src/hooks/useRoutes.ts`)

React hook providing:

Data Flow

```

User marked points (Point[])

↓

┌─────────────────────────────────────────┐

│ Combined Algorithm │

├─────────────────────────────────────────┤

│ MHD Branch (weight: 0.6) │

│ normalizePoints() → MHD → similarity │

├─────────────────────────────────────────┤

│ Order Branch (weight: 0.4) │

│ sort by Y → normalize X → DTW │

└─────────────────────────────────────────┘

↓

combinedSimilarity() → 0-100%

↓

SearchResult[] sorted by similarity

```

Key Type Definitions (`src/types/route.ts`)

Instructions for Development

1. **Algorithm Modifications**: When modifying matching algorithms in `src/lib/matching.ts`:

- Preserve the combined approach unless explicitly changing the architecture

- Maintain algorithm parameters (maxDistance, mhdWeight, orderWeight) unless experimenting

- Run tests after changes to verify behavior

- Check `docs/research/2025-11-29-angle-invariant-matching.md` for research context

2. **Storage Changes**: The OPFS storage layer is intentionally local-only:

- Do not add cloud sync without explicit user request

- Maintain the routes.json + images/ structure

- Handle Blob URLs carefully to avoid memory leaks

3. **Multi-Image Matching**: The system uses the highest similarity score among all images of a route:

- Each route can have multiple reference images

- Search returns the best match across all images

- Consider this when modifying search logic

4. **Testing**: Always run tests before committing algorithm changes:

- Unit tests cover the matching algorithms

- Use test:watch during development

- Add tests for new matching strategies

5. **Code Style**: Follow existing patterns:

- TypeScript strict mode

- React hooks for state management

- Functional programming style in algorithm code

Research Reference

For detailed algorithm research, experiment results, and design decisions, consult:

`docs/research/2025-11-29-angle-invariant-matching.md`

This document contains the rationale behind the combined MHD + order-aware approach and experimental validation data.