Image metadata API

Read the route inside the photo.

Every image TickMark exports carries its climb as structured data: grade, styles, rules, every outlined hold and the route markers. Read it from any app, in any language, without an account or a network call.

Overview

TickMark writes standard XMP into each export, in its own namespace. Photos apps ignore unknown namespaces, so captions, keywords and dates stay untouched. Inside, one property, tickmark:Data, holds a JSON document: that JSON is the contract this page documents. A few flat, human-readable properties are written alongside it for quick inspection.

Where it lives

Quick start

Command line

# Register nothing; exiftool prints unknown XMP namespaces as-is.
exiftool -XMP-tickmark:Data -b climb.png | jq .

Swift (iOS, macOS)

import ImageIO

func tickmarkData(at url: URL) -> [String: Any]? {
  guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
        let metadata = CGImageSourceCopyMetadataAtIndex(source, 0, nil),
        let mutable = CGImageMetadataCreateMutableCopy(metadata) else return nil
  CGImageMetadataRegisterNamespaceForPrefix(mutable, "https://tickmark.baguette-studios.dev/ns/1.0/" as CFString, "tickmark" as CFString, nil)
  guard let json = CGImageMetadataCopyStringValueWithPath(mutable, nil, "tickmark:Data" as CFString) as String? else return nil
  return try? JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any]
}

JavaScript (browser or Node)

// Works for PNG and JPEG: TickMark's XMP packet is stored as plain UTF-8 text.
export function readTickmark(bytes) {
  const text = new TextDecoder('utf-8', { fatal: false }).decode(bytes);
  const raw = text.match(/<tickmark:Data>([\s\S]*?)<\/tickmark:Data>/)?.[1]
           ?? text.match(/tickmark:Data="([^"]*)"/)?.[1];
  if (!raw) return null;
  const json = raw.replace(/&quot;/g, '"').replace(/&apos;/g, "'")
    .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
  const data = JSON.parse(json);
  // Refuse data written for a newer reader (see Versioning).
  return (data.compatible ?? data.version) <= 3 ? data : null;
}

Kotlin (Android)

fun readTickmark(bytes: ByteArray): JSONObject? {
  val text = String(bytes, Charsets.UTF_8)
  val raw = Regex("<tickmark:Data>([\\s\\S]*?)</tickmark:Data>").find(text)?.groupValues?.get(1)
    ?: Regex("tickmark:Data=\"([^\"]*)\"").find(text)?.groupValues?.get(1) ?: return null
  val json = raw.replace("&quot;", "\"").replace("&apos;", "'")
    .replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
  return JSONObject(json).takeIf { it.optInt("compatible", it.optInt("version")) <= 3 }
}

Python

import html, json, re

def read_tickmark(path):
    text = open(path, "rb").read().decode("utf-8", "ignore")
    m = re.search(r"<tickmark:Data>(.*?)</tickmark:Data>", text, re.S) or re.search(r'tickmark:Data="([^"]*)"', text)
    if not m: return None
    data = json.loads(html.unescape(m.group(1)))
    return data if data.get("compatible", data["version"]) <= 3 else None

Route data

The top-level JSON object in tickmark:Data.

{
  "format": "tickmark-route", "version": 3, "compatible": 2,
  "name": "Moonlight traverse",
  "grade": { "system": "font", "low": "7A", "high": "7B" },
  "styles": ["Powerful", "Compression"],
  "rules": [{ "text": "No matching" }, { "text": "Feet only", "color": "#FF646B" }],
  "areas": [{
    "id": "outline-mvf0c565-2", "color": "#FFD84D", "allowed": true,
    "roles": ["start"], "rules": ["Right hand only"],
    "bounds": [0.3512, 0.1806, 0.2911, 0.1524],
    "outline": [[0.3644, 0.2611, 0.4102, 0.1902, 0.6023, 0.1871, /* … */]]
  }],
  "markers": [{ "kind": "start", "label": "START", "center": [0.845, 0.3647], "radius": 0.052,
    "tapes": [[0.775, 0.3, 0.845, 0.3647]] }]
}

Grade

Rules

Rules exist at two levels. Global rules live in the top-level rules array; hold rules live on each area.

Built-in texts you may want to recognise (custom rules can be anything): whole problem — No matching, Feet follow hands, Marked feet only, Feet anywhere, No feet (campus), Sit start, No dynos; holds — No matching, Right hand only, Left hand only, Hands only, Feet only, Use once.

Areas

Markers

Coordinates

All positions are fractions of the image: x / width and y / height, origin at the top-left, rounded to four decimals. They are resolution independent: multiply by the decoded image's pixel size. Because x and y are scaled separately, convert to pixels before measuring distances.

XMP properties

Flat properties for quick inspection in tools like exiftool. tickmark:Data is the source of truth.

Rules for a hold

A hold's effective rules are its own rules, plus global rules pinned to its colour, plus unpinned global rules.

function rulesFor(data, area) {
  const same = (a, b) => a?.toUpperCase() === b?.toUpperCase();
  return {
    hold: area.rules,
    colour: data.rules.filter(r => r.color && same(r.color, area.color)).map(r => r.text),
    problem: data.rules.filter(r => !r.color).map(r => r.text),
  };
}

Versioning

Every TickMark data block states three things: its format, the version that wrote it, and the oldest reader it stays compatible with.

• Additive changes (new optional fields) raise version only. Older readers keep working; ignore fields you don't know.
• Breaking changes raise both. If compatible is greater than the version your code supports, stop: the data needs a newer reader.

What survives sharing

Changelog

Questions or building something with TickMark data? support@baguette-studios.dev