apriltag-js

apriltag-js is a TypeScript port of apriltag-generation with no dependencies. See also the main AprilTag repo and paper.

While the reference implementation is geared toward designing and evaluating new tag families, this library only renders them, which is a much easier task. It supports all official tag families, and you can easily use your own.

• 16h5
• 25h9
• 36h9
• 36h10
• 36h11
• Circle21h7
• Circle49h12
• Custom48h12
• Standard41h12
• Standard52h13

The main contribution of this library is the introduction of a new JSON format for defining tag families, which is more portable and consistent than the set of Java class definitions found in the reference implementation.

Installation

npm install apriltag

You can also just copy and paste the code into your project! Or include it on your web page like this:

<script src="https://cdn.jsdelivr.net/npm/apriltag@latest/dist/browser.js"></script>

Usage

If you use npm:

import { AprilTagFamily } from 'apriltag'
import tagConfig36h11 from 'apriltag/families/36h11.json'

const family = new AprilTagFamily(tagConfig36h11);
console.log(family.render(1));

Alternatively, if you're using a plain <script> tag:

<script src="https://cdn.jsdelivr.net/npm/apriltag@latest/dist/browser.js"></script>
<script>
  async function main() {
    const rsp = await fetch('https://cdn.jsdelivr.net/npm/apriltag@latest/families/36h11.json')
    const tagConfig36h11 = await rsp.json()

    const family = new AprilTagFamily(tagConfig36h11)
    console.log(family.render(1))
  }

  main()
</script>

You'll get back a 2D array of characters representing pixels. w means white, b means black, and x means transparent. More details on the format are in the next section.

[
  ['w', 'w', 'w', 'w', 'w', 'w', 'w', 'w', 'w', 'w'],
  ['w', 'b', 'b', 'b', 'b', 'b', 'b', 'b', 'b', 'w'],
  ['w', 'b', 'w', 'w', 'b', 'w', 'w', 'b', 'b', 'w'],
  ['w', 'b', 'b', 'w', 'b', 'w', 'w', 'w', 'b', 'w'],
  ['w', 'b', 'w', 'w', 'w', 'w', 'b', 'b', 'b', 'w'],
  ['w', 'b', 'b', 'w', 'w', 'b', 'b', 'b', 'b', 'w'],
  ['w', 'b', 'w', 'b', 'w', 'w', 'b', 'w', 'b', 'w'],
  ['w', 'b', 'b', 'b', 'w', 'b', 'b', 'w', 'b', 'w'],
  ['w', 'b', 'b', 'b', 'b', 'b', 'b', 'b', 'b', 'w'],
  ['w', 'w', 'w', 'w', 'w', 'w', 'w', 'w', 'w', 'w']
]

What you do with it is up to you! You could render them as ASCII art, create HTML elements or SVG, generate images, or draw them on a canvas. Take a look at the unit tests for this library if you're not sure how to begin.

You can check the size and number of IDs a tag family supports by accessing family.size and family.codes.length respectively.

Tag family format

Look in the families/ folder for examples. Tag families must adhere to the following type:

type AprilTagConfig = {
  size: number;
  layout: string;
  codes: number[];
};

size

size is the length of one side of a tag in pixels. Squaring it gives you the area. It's the measurement of the entire tag, not just the data region (e.g. 36h11 has size 10).

layout

layout is a string consisting of size × size characters, which can be w for white, b for black, x for transparent, or d for data. See Fig. 3 of the paper:

codes

codes is a list of numbers representing the bits encoded in each tag. One code is one tag, and a tag's ID is its index in the codes array.

These are the AprilTag 3 "upgraded" codes, so the codes for tags from earlier generations are written differently than how they appear in the reference implementation, but they mean the same thing.