napa-vision 0.4.0__tar.gz

napa_vision-0.4.0/CMakeLists.txt

@@ -0,0 +1,48 @@
+# Napa. Copyright (c) 2026 Zachary Wilson. PolyForm Noncommercial License 1.0.0: see LICENSE.
+# Napa's detector core as a plain C library, for C and C++ programs. Python users: pip install napa-vision.
+#
+#   cmake -S . -B build && cmake --build build && cmake --install build --prefix /usr/local
+#
+# Then, in your project: find_package(napa) and target_link_libraries(app PRIVATE napa::napa).
+cmake_minimum_required(VERSION 3.15)
+file(STRINGS src/napa_vision/_version.py NAPA_VERSION_LINE REGEX "^__version__")
+string(REGEX MATCH "[0-9]+\\.[0-9]+\\.[0-9]+" NAPA_VERSION "${NAPA_VERSION_LINE}")
+project(napa VERSION ${NAPA_VERSION} LANGUAGES C)
+
+option(BUILD_SHARED_LIBS "Build a shared library" OFF)
+option(NAPA_BUILD_EXAMPLES "Build the example program" OFF)
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+set(NAPA_NATIVE ${CMAKE_CURRENT_SOURCE_DIR}/src/napa_vision/_native)
+add_library(napa ${NAPA_NATIVE}/napa_core.c)
+add_library(napa::napa ALIAS napa)
+target_include_directories(napa PUBLIC $<BUILD_INTERFACE:${NAPA_NATIVE}> $<INSTALL_INTERFACE:include>)
+set_target_properties(napa PROPERTIES
+  C_STANDARD 99
+  C_STANDARD_REQUIRED ON
+  C_VISIBILITY_PRESET hidden
+  POSITION_INDEPENDENT_CODE ON
+  PUBLIC_HEADER ${NAPA_NATIVE}/napa_core.h)
+if(MSVC)
+  target_compile_options(napa PRIVATE $<$<CONFIG:Release>:/O2>)
+else()
+  # Signed overflow isn't relied on; -fno-wrapv keeps compilers free to optimise the inner loops.
+  target_compile_options(napa PRIVATE $<$<CONFIG:Release>:-O3> -fno-wrapv)
+  target_link_libraries(napa PRIVATE m)
+endif()
+
+include(GNUInstallDirs)
+install(TARGETS napa EXPORT napaTargets
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+  PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(FILES LICENSE THIRD_PARTY_NOTICES DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/napa)
+install(EXPORT napaTargets NAMESPACE napa:: FILE napaConfig.cmake DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/napa)
+
+if(NAPA_BUILD_EXAMPLES)
+  add_executable(napa_detect_pgm examples/c/detect_pgm.c)
+  target_link_libraries(napa_detect_pgm PRIVATE napa)
+endif()

napa_vision-0.4.0/LICENSE

@@ -0,0 +1,77 @@
+Required Notice: Copyright (c) 2026 Zachary Wilson (https://github.com/zwatx/NAPA)
+Required Notice: Napa ("Not Another Pixel Algorithm") was created by Zachary Wilson. Copies, forks, and works based on it must keep these notices and credit Zachary Wilson as Napa's author.
+Required Notice: Commercial use needs a separate license from Zachary Wilson; ask through https://github.com/zwatx/NAPA.
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

napa_vision-0.4.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE THIRD_PARTY_NOTICES CMakeLists.txt
+recursive-include examples *.c
+include benchmarks/corpus.example.json
+include docs/guide.md
+recursive-include src/napa_vision/_native *.c *.h

napa_vision-0.4.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: napa-vision
+Version: 0.4.0
+Summary: Napa: a fast, dependency-free tag36h11 AprilTag detector with optional pose processing
+Author: Zachary Wilson
+License-Expression: PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/zwatx/NAPA
+Project-URL: Repository, https://github.com/zwatx/NAPA.git
+Project-URL: Issues, https://github.com/zwatx/NAPA/issues
+Keywords: apriltag,computer-vision,fiducial,pose-estimation,robotics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES
+Requires-Dist: numpy>=1.24
+Provides-Extra: gui
+Requires-Dist: opencv-python>=4.7; extra == "gui"
+Provides-Extra: headless
+Requires-Dist: opencv-python-headless>=4.7; extra == "headless"
+Provides-Extra: benchmark
+Requires-Dist: robotpy-apriltag==2026.2.2; extra == "benchmark"
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# Napa
+
+**Not Another Pixel Algorithm**: Napa skips most of the pixels in each frame.
+
+Napa is a fast AprilTag detector for any camera. It reads every AprilTag family, and `tag36h11`, the FRC family, by
+default. Give it a frame and it returns tag IDs and sub-pixel
+corners, plus poses if you supply a calibration. It opens no cameras, starts no threads, and publishes nothing, so a
+webcam, a Raspberry Pi, a headset, recorded video, or a camera SDK can all feed it the same way.
+
+The detector is a small C library with no dependencies, plus a Python binding that needs only numpy.
+
+## Compared with standard AprilTag
+
+"Standard AprilTag" here means the upstream AprilTag 3 library at its default settings (`quad_decimate=2`). Both
+detectors ran single-threaded on one pinned core of an Intel Core Ultra 7 256V laptop (Windows 11, Ubuntu-like Linux
+under WSL2, best-performance power mode), taking turns on the same grayscale frames. Earlier published results came
+from a desktop Intel i7-12700H, so absolute times differ from those.
+
+The benchmark has **3,000 distinct frames holding 5,521 tags**. Every frame is rendered separately, with random tag
+IDs, positions, sizes, angles, 3D tilt, backgrounds, and camera degradations, and every tag has exact sub-pixel
+ground truth. [The benchmark guide](benchmarks/README.md) describes each scene.
+
+**Tags found.** Napa found **99.8%** of tags. Standard AprilTag found 86.2%, and AprilTag at full resolution
+(`quad_decimate=1`) 99.4%. Napa finds the small tags that standard AprilTag's decimation loses, and in every one of
+the 60 scene and resolution combinations it found at least as many tags as standard AprilTag.
+
+**Range.** Napa sees tags from much farther away. A tag looks smaller the farther it is, so the smallest tag a
+detector can find sets its range. A separate sweep rendered 50 tags at each of eleven sizes, from 12 to 96 px across
+the black square, with light noise and up to 15° of tilt, and counted what each detector found:
+
+| Smallest black square found | Standard AprilTag | AprilTag at full resolution | Napa |
+| --- | ---: | ---: | ---: |
+| Every tag | 96 px | 40 px | **24 px** |
+| Most tags | 64 px (36 of 50) | 32 px (39 of 50) | **20 px (46 of 50)** |
+
+That is **4× the range of standard AprilTag** and 1.7× the range of AprilTag at full resolution. For example, a
+6.5-inch FRC tag seen by a 1280×720 camera with a 70° field of view is 24 px across at 6.3 m, where standard
+AprilTag needs it within 1.6 m. To see farther still, lower `min_tag_px` (see [the guide](docs/guide.md#detection)).
+
+**Speed.** Napa was faster on every one of the 3,000 frames:
+
+- **Noise-free frames: 5.7× to 12.6× faster** (median per frame, by resolution). The slowest single frame was
+  still 4.8× faster.
+- **Realistic frames: about 21× faster** (median). Every other scene includes at least light sensor noise
+  (σ ≈ 1.5 grey levels), which a real sensor always has. Standard AprilTag's time climbs steeply with noise: on a
+  1280×720 frame its median is 1.35 ms with none, and 10–15 ms in most noisy scenes (overexposed and JPEG frames,
+  whose clipping and compression smooth the noise, take 2–2.6 ms). Napa stays under about 0.5 ms. The slowest single
+  frame here was 3.6× faster.
+- Against AprilTag at full resolution, Napa was 87× faster (median) and at least 11.8× faster on every frame.
+
+These are the 1280×720 results; the guide has every resolution:
+
+| Scene, 1280×720 | Tags | AprilTag | Napa | Speedup (median) | Slowest frame | Tags found (AprilTag → Napa) |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Noise-free | 104 | 1.35 ms | 0.16 ms | 8× | 6.9× | 104 → 104 |
+| One tag | 50 | 13.1 ms | 0.20 ms | 65× | 46× | 50 → 50 |
+| 2–12 tags | 354 | 9.64 ms | 0.49 ms | 20× | 8.0× | 354 → 354 |
+| Small tags (32–53 px) | 120 | 11.6 ms | 0.29 ms | 41× | 11.6× | 0 → 120 |
+| Large tags | 50 | 10.6 ms | 0.29 ms | 37× | 13.4× | 50 → 50 |
+| Steep angle (40–65°) | 112 | 10.6 ms | 0.35 ms | 31× | 11.6× | 109 → 111 |
+| Defocus blur | 89 | 10.2 ms | 0.32 ms | 32× | 9.2× | 89 → 89 |
+| Motion blur | 94 | 10.2 ms | 0.38 ms | 17× | 9.1× | 94 → 94 |
+| Heavy noise (σ 4–14) | 104 | 9.66 ms | 0.52 ms | 19× | 6.0× | 104 → 104 |
+| Uneven lighting | 103 | 11.0 ms | 0.37 ms | 29× | 12.0× | 103 → 103 |
+| Low contrast | 100 | 13.9 ms | 0.23 ms | 66× | 39× | 95 → 99 |
+| Underexposed | 99 | 11.3 ms | 0.33 ms | 35× | 13.6× | 99 → 99 |
+| Overexposed | 112 | 2.04 ms | 0.26 ms | 7× | 5.4× | 112 → 112 |
+| JPEG artefacts | 100 | 2.58 ms | 0.25 ms | 8× | 4.2× | 100 → 100 |
+| Busy background | 87 | 10.9 ms | 0.30 ms | 38× | 11.3× | 87 → 87 |
+| At the frame edge | 105 | 10.8 ms | 0.32 ms | 35× | 12.2× | 103 → 105 |
+| Dark background | 105 | 10.3 ms | 0.29 ms | 38× | 12.0× | 91 → 105 |
+| No tag: empty / clutter / decoys | — | 9–15 ms | 0.12–0.31 ms | 19–101× | 5.1× | — |
+
+Times are the median detector call. Speedups are per frame: AprilTag's time divided by Napa's on the same frame.
+"Slowest frame" is the smallest of those ratios.
+
+**Corners.** For each tag, the benchmark measured the worst corner's distance from the true corner. On the 4,754
+tags both detectors found, Napa's median error was **0.020 px** against AprilTag's 0.099 px, and its 95th percentile
+**0.088 px** against 0.303 px. Napa was more accurate at the median and 95th percentile in every scene. The exception
+is the single worst case under heavy motion blur: with 11 px of blur on a tag about 50 px across, one of Napa's
+corners was 2.5 px off, where AprilTag's worst in that scene was 0.98 px.
+
+**False detections.** In 3,000 frames, Napa reported one wrong ID: a tag-shaped decoy whose random payload happened
+to fall within 2 bits of a real code, the same tolerance standard AprilTag uses. Standard AprilTag reported none,
+and full-resolution AprilTag 3. On a separate test of 80,000 such decoys, Napa reported none.
+
+## Every tag family
+
+Napa reads all nine of upstream AprilTag's families: tag36h11 (the default), tag16h5, tag25h9, tag36h10,
+tagStandard41h12, tagStandard52h13, tagCircle21h7, tagCircle49h12, and tagCustom48h12. Pass the family when you create
+a detector: `NapaDetector(family="tagStandard41h12")`. tag36h11's detection is unchanged by the other families: it
+gives exactly the same results as before they were added.
+
+A family-by-family run over the same 20 scenes (each with its own family's tags, spaced by their printed size) gave:
+
+| Family | Tags | Found: AprilTag → Napa | False IDs: AprilTag → Napa | Median corner error: AprilTag → Napa | Speedup: median (slowest frame) |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| tag36h11 | 289 | 288 → 287 | 0 → 0 | 0.097 → 0.022 px | 40× (7.9×) |
+| tag16h5 | 282 | 282 → 280 | **581 → 0** | 0.107 → 0.022 px | 38× (5.5×) |
+| tag25h9 | 287 | 286 → 286 | 3 → 0 | 0.098 → 0.021 px | 36× (7.2×) |
+| tagStandard41h12 | 232 | 232 → 231 | 0 → 0 | 0.097 → 0.025 px | 42× (8.5×) |
+| tagCircle21h7 | 231 | 231 → 230 | 9 → 0 | 0.097 → 0.025 px | 42× (9.3×) |
+
+Frames were 640×480 and 1280×720. Speedups are per frame, from a separate timing pass over 80 frames per family on
+one pinned core.
+
+Every tag that only AprilTag found was small (40–60 px) and steeply tilted, where the white quiet zone narrows to a
+pixel or two: either its narrow side was under `min_tag_px`, or a dark line in the background touched the tag and
+joined its border (see [Limits](#limits)). On tagStandard52h13, tagCircle49h12, tagCustom48h12, and tag36h10 (which the reference
+Python binding doesn't include), Napa found 99.2–99.6% of tags with no false IDs. Upstream's decode table for the
+three big families needs several gigabytes, which is one more reason to prefer Napa for them: its tables take
+megabytes.
+
+tag16h5's 30 codes are only 5 bits apart, so a decoder that corrects two wrong bits, as AprilTag does by default,
+accepts about one in four random tag-shaped patterns. Napa sets each family's default correction so that chance
+matches stay as rare as they are for tag36h11, and adds a "soft" correction for families like tag16h5: a few bits
+may still be corrected, but only if they're exactly the payload's least certain readings. [The API
+reference](docs/api.md#tag-families) has the details.
+
+These are synthetic frames on one laptop CPU. Measure on your own camera and hardware before relying on a specific
+number: `napa-benchmark` scores Napa on your own annotated images (see [the guide](docs/guide.md)).
+
+## Why it's faster
+
+Standard AprilTag treats each frame as a large image-processing job. It thresholds every pixel, segments the whole
+image into regions, and fits quadrilaterals to every region's boundary before it asks whether anything is a tag.
+Napa asks that question as early and as cheaply as it can.
+
+![Napa on one frame, stage by stage: the rake keeps every third pixel, flat tiles are skipped, dark samples become runs and blobs, shapes that can't be tags are dropped, and only the tags get edge fitting and decoding at full resolution.](docs/napa-pipeline.webp)
+
+*One synthetic frame, stage by stage. Every overlay is computed from the frame by a port of Napa's pipeline.*
+
+### 1. The rake: sample sparsely, with a guarantee
+
+A tag's black border is one cell wide, and a tag is 8 cells across. Sample every few pixels and you're guaranteed to
+land on the border of every tag above a minimum size, so skipping the pixels in between can't skip a tag.
+
+Napa drags a "rake" across the frame, taking one sample every ¾ of the smallest cell in each direction. Blur greys a
+cell's edges but leaves its core dark, and ¾-cell spacing always puts a sample in that core. For the default 32 px
+minimum tag, that's one pixel in nine. Coarser copies of the rake (2×, 4×, 8×, …) catch larger tags; each is built
+from the one before, not from the image, and together they add only a third again to the cost.
+
+Each tag is handled at the level where it's between about 16 and 64 samples across. Below that, its one-cell white
+margin can fall between samples and the tag merges with a dark background; above it, the middle of its border is
+too far from any white to stand out. Every tag size has such a level.
+
+### 2. String search on a matrix: skip what can't match
+
+Fast string search (Boyer–Moore) doesn't compare every character. One cheap check can prove that no match starts in
+the next several positions, so the search jumps past them.
+
+Napa applies the same idea to the image. It splits the raked samples into small tiles and records each tile's
+darkest and brightest value. A tile without contrast can't contain a tag's edge, so Napa skips it and does no work
+on its pixels. The contrast needed rises automatically with sensor noise, measured from the frame itself and region
+by region, so a noisy or textured part of the frame doesn't blind the rest. On a very noisy frame, each rake sample
+averages the block of pixels it stands for instead, which divides the noise by the stride.
+
+The same idea speeds up decoding. A tag's 36 payload bits must be matched against 587 codes in 4 rotations, allowing
+up to 3 wrong bits. Any code within 3 bits of the payload must match at least one of four 9-bit blocks *exactly* (the
+pigeonhole principle). So Napa looks those blocks up in a table and compares only the handful of codes that share
+one, instead of all 2,348.
+
+### 3. Old-school vector math
+
+Every pass over the samples is written as whole-row vector operations, the classic Apple AltiVec/vDSP approach. One
+SSE2 or NEON instruction compares 16 samples with their thresholds and packs the results into a bit mask. Runs of
+dark samples then fall out of the masks with a count-trailing-zeros instruction per run, not a test per pixel.
+Runs that touch from row to row are joined into blobs with union-find, so the cost follows the number of runs, not
+the number of dark pixels. Gathering every third pixel uses a byte shuffle (SSSE3, chosen at run time) or NEON's
+de-interleaving load.
+
+### 4. Reject early, measure carefully
+
+Each blob of plausible size gets a rough quadrilateral from its extreme points. A blob can't be a tag if it's darker
+overall than any real code allows: every tag36h11 code has at least 10 white cells. Then Napa:
+
+1. Fits each side to its edge at full resolution.
+2. Decodes straight away with a loose tolerance, reading the border first. Text, texture, and checkerboards are
+   thrown out here, before any expensive refinement.
+3. Refines each side coarse to fine, then with a final pass that measures the edge every 1.5 px along it. Each
+   measurement is the centre of the edge's gradient, which is exact for real, pixel-integrated edges. Where blur is
+   wider than about half a cell, the edge is located instead where the image crosses halfway between the black and
+   white on either side.
+4. Intersects the four lines to get the corners, and decodes the payload.
+
+Some images fool a plain edge fit, so Napa checks for them:
+
+- **A grey quiet zone on a bright background** makes the margin look dark, so the first outline is the margin's.
+  If the decode fails, Napa tries the outline's inner 8/10, where the black square would be.
+- **A side fitted one cell out**, on the margin's outer edge, shows up as border cells that read white. Napa moves
+  that side in by a cell and refits it.
+- **Clipped (saturated) exposure** shrinks every black region by the same amount. The black border must be exactly
+  one cell wide, so Napa measures that shrinkage on the tag itself and undoes it.
+
+## Obstructions
+
+Napa corrects up to 3 wrong payload bits (standard AprilTag defaults to 2), so a hand, cable, or glare spot over part
+of a tag often still decodes. It accepts a third corrected bit only when the three wrong cells touch, as they do
+under a real obstruction: a random pattern that happens to fall within three bits of a code has its errors
+scattered, so this keeps chance matches out. In the benchmark's obstruction sweep (864 tags, each partly covered by
+a white or grey patch), Napa recovered 357 tags and standard AprilTag 330.
+
+No AprilTag detector can find a tag whose black border or corners are hidden, because the border is found before any
+bits are read. Obstruction tolerance is best-effort, with no guaranteed percentage.
+
+## Limits
+
+- Tags smaller than `min_tag_px` (default 32 px across the black square) may be missed. Lower it to find smaller tags,
+  at some cost in speed. A steeply tilted tag counts by its narrowest side.
+- Tags need their white quiet zone, as printed tags have. A tag whose quiet zone runs straight into dark, busy
+  texture can merge with it and be missed. Steep tilt makes this likelier, because it narrows the quiet zone: a small
+  tag tilted 60° can join a dark line that touches it.
+- Tags with less than `min_contrast` (default 20) grey levels between their black and white are skipped. Lower it for
+  washed-out scenes, at a cost in speed on every frame.
+- Motion blur longer than a cell (an eighth of the tag) is the hardest case for corner accuracy: most corners stay
+  within a tenth of a pixel, but the worst can be off by a few pixels.
+- Prebuilt wheels cover Linux (x86-64, ARM64), macOS (Apple silicon, Intel), and Windows x64. Elsewhere, pip builds
+  from source, which needs a C99 compiler.
+
+## Quick start
+
+Requires Python 3.11 or newer.
+
+```bash
+python -m pip install napa-vision              # the detector: needs only numpy
+python -m pip install "napa-vision[headless]"  # adds OpenCV, for poses, calibration, and napa-benchmark
+```
+
+```python
+from napa_vision import NapaDetector
+
+detector = NapaDetector()
+for tag in detector.detect(image):  # uint8 grayscale, BGR, or BGRA
+    print(tag.tag_id, tag.corners)
+```
+
+Each detection also has `tag.center` and `tag.homography`, as upstream AprilTag reports them.
+
+Already using `pupil_apriltags` or `dt-apriltags`? Change the import and keep the rest of your code:
+
+```python
+from napa_vision.compat import Detector  # was: from pupil_apriltags import Detector
+
+detector = Detector(families="tag36h11")
+detections = detector.detect(gray, estimate_tag_pose=True, camera_params=(fx, fy, cx, cy), tag_size=0.1651)
+```
+
+Results keep upstream's conventions (corner order, pixel origin, and pose frames), so code written against those
+libraries works unchanged.
+
+For metric poses, use `VisionProcessor(calibration=load_calibration_data("camera.json"), tag_size_m=...)`. Every pose
+comes with a covariance, so it can go straight into a Kalman filter, including WPILib's pose estimators. Use one
+detector per camera stream. The native call releases the GIL, so separate streams can run on separate threads.
+
+The C library has a plain C API (`src/napa_vision/_native/napa_core.h`), so other languages can call it directly.
+C and C++ projects can build and install it with CMake and link `napa::napa`; see
+[the guide](docs/guide.md#from-c-or-another-language).
+[The guide](docs/guide.md) covers tuning, poses, Kalman filters, coordinate conventions, and calibration, and
+[the API reference](docs/api.md) lists every class, method, and field.
+
+## Command-line tools
+
+| Command | Purpose |
+| --- | --- |
+| `napa-tag` | Write tags to print: SVG at an exact printed size, or PNG |
+| `napa-calibrate` | Measure camera intrinsics from checkerboard photographs |
+| `napa-benchmark` | Score Napa on your own annotated images, with optional recall, precision, and latency gates |
+
+## Development
+
+```bash
+python -m pip install -e ".[headless,dev,benchmark]"
+ruff format --check . && ruff check .
+pytest --cov=napa_vision
+```
+
+## License
+
+Copyright © 2026 Zachary Wilson. Napa is free for noncommercial use under the
+[PolyForm Noncommercial License 1.0.0](LICENSE): personal projects, research, education, student robotics teams,
+and other noncommercial organizations can use, modify, and share it. Copies, forks, and works based on Napa must
+include the license and its notices crediting Zachary Wilson. Commercial use, including selling Napa or products
+built on it, needs a separate license; ask through [the repository](https://github.com/zwatx/NAPA).
+
+The tag families' codewords come from [AprilTag](https://github.com/AprilRobotics/apriltag) under its BSD license; see
+[THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES).