### Install Dependencies

Source: https://github.com/magicleap/superpointpretrainednetwork/blob/master/README.md

Installs the necessary Python libraries, OpenCV and PyTorch, for running the SuperPoint demo.

```sh
pip install opencv-python
pip install torch
```

--------------------------------

### Run Live Demo via Webcam (CPU)

Source: https://github.com/magicleap/superpointpretrainednetwork/blob/master/README.md

Starts a live SuperPoint demo using a USB webcam (device ID 1) in CPU mode. This allows for real-time interest point detection and tracking.

```sh
./demo_superpoint.py camera --camid=1
```

--------------------------------

### PointTracker - Update and Get Tracks

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Manages a rolling window of frames for optical flow tracking. The `update` method processes new frames, and `get_tracks` retrieves tracks that meet a minimum length criterion.

```APIDOC
## `PointTracker` — Multi-Frame Sparse Optical Flow Tracker

`PointTracker` maintains a rolling window of `max_length` frames. On each call to `update()` it performs two-way nearest-neighbor matching between the previous frame's descriptors and the new ones, extending existing tracks or creating new single-point tracks. `get_tracks()` retrieves all tracks of at least `min_length` that have a live observation in the most recent frame.

### Methods

*   **`update(pts, desc)`**: Feeds new point observations and their descriptors into the tracker.
*   **`get_tracks(min_length)`**: Retrieves tracks that have been observed for at least `min_length` frames and are still active.

### Parameters

*   **`PointTracker(max_length, nn_thresh)`**:
    *   `max_length` (int): The maximum number of frames to keep track of.
    *   `nn_thresh` (float): The threshold for nearest-neighbor matching.
*   **`update(pts, desc)`**:
    *   `pts` (numpy.ndarray): Keypoint locations.
    *   `desc` (numpy.ndarray): Descriptors for the keypoints.
*   **`get_tracks(min_length)`**:
    *   `min_length` (int): The minimum number of frames a track must be observed to be returned.

### Returns

*   **`get_tracks()`**: Returns a numpy array of shape `M × (2 + max_length)` where M is the number of tracks. Column 0 is the track ID, column 1 is the average descriptor score, and subsequent columns are point IDs.
```

--------------------------------

### Run CLI Demo with Full Parameter Reference

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Demonstrates the SuperPoint demo script with a comprehensive set of parameters, including weights path, image glob pattern, resolution, display scaling, track length, confidence thresholds, and visualization options.

```bash
./demo_superpoint.py assets/icl_snippet/ \
    --weights_path superpoint_v1.pth \
    --img_glob '*.png' \
    --skip 1 \
    --H 120 --W 160 \
    --display_scale 2 \
    --min_length 2 \
    --max_length 5 \
    --nms_dist 4 \
    --conf_thresh 0.015 \
    --nn_thresh 0.7 \
    --show_extra
# Output: three panels — tracked points, raw detections, confidence heatmap
```

--------------------------------

### Run SuperPointFrontend for Keypoint and Descriptor Extraction

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Initializes the `SuperPointFrontend` wrapper, loads weights, and runs inference on a preprocessed grayscale image. The frontend handles NMS, thresholding, and descriptor sampling for ready-to-use keypoints and descriptors.

```python
from demo_superpoint import SuperPointFrontend
import cv2
import numpy as np

# Initialize frontend (CPU mode)
fe = SuperPointFrontend(
    weights_path='superpoint_v1.pth',
    nms_dist=4,          # NMS radius in pixels
    conf_thresh=0.015,   # minimum keypoint confidence
    nn_thresh=0.7,       # descriptor L2 distance threshold for matching
    cuda=False
)

# Load and preprocess image: must be float32 in [0, 1], single channel
raw = cv2.imread('assets/icl_snippet/250.png', 0)              # uint8 grayscale
img = cv2.resize(raw, (160, 120), interpolation=cv2.INTER_AREA)
img = img.astype('float32') / 255.0                            # HxW float32

# Run inference
pts, desc, heatmap = fe.run(img)
# pts     -> 3×N  [x, y, confidence]  (N detected keypoints after NMS)
# desc    -> 256×N unit-normalized descriptors
# heatmap -> H×W  float32 confidence map in [0, 1]

print(f'Detected {pts.shape[1]} keypoints')
print(f'Descriptor matrix: {desc.shape}')   # (256, N)
print(f'Top-5 confidences: {pts[2, :5]}')
```

--------------------------------

### Instantiate and Load SuperPointNet Weights (CPU)

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Instantiates the raw PyTorch `SuperPointNet` module and loads pretrained weights. Use this for direct network interaction, but prefer `SuperPointFrontend` for production inference.

```python
import torch
from demo_superpoint import SuperPointNet

# Instantiate and load weights manually (CPU)
net = SuperPointNet()
weights = torch.load('superpoint_v1.pth', map_location='cpu')
net.load_state_dict(weights)
net.eval()

# Single grayscale image forward pass: 1×1×120×160
img_tensor = torch.zeros(1, 1, 120, 160)  # replace with real image data
with torch.no_grad():
    semi, desc = net(img_tensor)

print(semi.shape)   # torch.Size([1, 65, 15, 20])
print(desc.shape)   # torch.Size([1, 256, 15, 20])
# desc is already L2-normalized along dim=1
```

--------------------------------

### Run Demo on Image Directory (CPU)

Source: https://github.com/magicleap/superpointpretrainednetwork/blob/master/README.md

Executes the SuperPoint demo on a directory of images using CPU mode. This is useful for processing static image sequences.

```sh
./demo_superpoint.py assets/icl_snippet/
```

--------------------------------

### Run CLI Demo Headless with Output Saving

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Runs the SuperPoint demo script in headless mode (no display) on a remote server. Allows specifying resolution, disabling display, and saving output frames to a directory.

```bash
./demo_superpoint.py assets/icl_snippet/ \
    --W=640 --H=480 \
    --no_display \
    --write \
    --write_dir=myoutput/
```

--------------------------------

### Run Demo on MP4 Video (GPU)

Source: https://github.com/magicleap/superpointpretrainednetwork/blob/master/README.md

Runs the SuperPoint demo on a provided MP4 video file, utilizing GPU acceleration for faster processing. This is suitable for analyzing video content.

```sh
./demo_superpoint.py assets/nyu_snippet.mp4 --cuda
```

--------------------------------

### Run Demo on Remote GPU with Output to Directory

Source: https://github.com/magicleap/superpointpretrainednetwork/blob/master/README.md

Executes the SuperPoint demo on a remote GPU, processing images of a specified resolution (640x480) and writing the output to a designated directory (`myoutput/`). This is useful for batch processing or when a local display is unavailable.

```sh
./demo_superpoint.py assets/icl_snippet/ --W=640 --H=480 --no_display --write --write_dir=myoutput/
```

--------------------------------

### Read and Resize Single Image with VideoStreamer

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Reads a single image, resizes it, and normalizes pixel values. Raises an exception if the file cannot be read. Ensure the image path is correct.

```python
from demo_superpoint import VideoStreamer

vs = VideoStreamer('assets/icl_snippet', camid=0,
                   height=120, width=160, skip=1, img_glob='*.png')

img = vs.read_image('assets/icl_snippet/250.png', img_size=(120, 160))
print(img.dtype)        # float32
print(img.shape)        # (120, 160)
print(img.min(), img.max())  # 0.0 ... ~1.0
```

--------------------------------

### VideoStreamer: Unified Input Source Abstraction

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Provides a uniform `next_frame()` interface for various input sources like image directories, video files, or webcams. Frames are returned as float32 numpy arrays in the range [0, 1] and resized to the specified dimensions.

```python
from demo_superpoint import VideoStreamer

# --- From an image directory ---
vs_dir = VideoStreamer(
    basedir='assets/icl_snippet',
    camid=0,
    height=120, width=160,
    skip=1,
    img_glob='*.png'
)
img, ok = vs_dir.next_frame()
while ok:
    # img: float32 HxW in [0,1]
    img, ok = vs_dir.next_frame()

# --- From a video file ---
vs_vid = VideoStreamer('assets/nyu_snippet.mp4', camid=0,
                       height=240, width=320, skip=2, img_glob='*.png')
frame, ok = vs_vid.next_frame()
print(f'Frame dtype: {frame.dtype}, shape: {frame.shape}')  # float32, (240, 320)

# --- From a webcam (id=0) ---
# vs_cam = VideoStreamer('camera', camid=0, height=480, width=640,
#                        skip=1, img_glob='*.png')

```

--------------------------------

### VideoStreamer

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Provides a unified interface for reading frames from various sources like image directories, video files, or webcams.

```APIDOC
## `VideoStreamer` — Unified Input Source Abstraction

`VideoStreamer` presents a uniform `next_frame()` interface regardless of whether the source is a directory of PNG/JPG images, an `.mp4`/`.avi` video file, or a live USB webcam. All frames are returned as float32 numpy arrays in `[0, 1]` resized to `(H, W)`.

### Methods

*   **`next_frame()`**: Returns the next frame from the video source.

### Parameters

*   **`VideoStreamer(source, camid, height, width, skip, img_glob)`**:
    *   `source` (str): Path to image directory, video file, or 'camera' for webcam.
    *   `camid` (int): Camera ID if `source` is 'camera'.
    *   `height` (int): Desired output frame height.
    *   `width` (int): Desired output frame width.
    *   `skip` (int): Number of frames to skip between reads.
    *   `img_glob` (str): Glob pattern for image files if `source` is a directory.

### Returns

*   **`next_frame()`**: A tuple containing:
    *   `img` (numpy.ndarray): The frame as a float32 HxW numpy array in the range [0, 1].
    *   `ok` (bool): True if a frame was successfully read, False otherwise.
```

--------------------------------

### PointTracker: Multi-Frame Sparse Optical Flow Tracking

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Maintains a rolling window of frames to track points across multiple frames. Use `update()` to feed new observations and `get_tracks()` to retrieve tracks of a minimum length that are present in the most recent frame.

```python
from demo_superpoint import SuperPointFrontend, PointTracker
import cv2
import numpy as np

fe = SuperPointFrontend('superpoint_v1.pth', nms_dist=4,
                        conf_thresh=0.015, nn_thresh=0.7)
tracker = PointTracker(max_length=5, nn_thresh=0.7)

image_paths = sorted(__import__('glob').glob('assets/icl_snippet/*.png'))

for path in image_paths:
    raw = cv2.imread(path, 0)
    img = cv2.resize(raw, (160, 120), interpolation=cv2.INTER_AREA)
    img = img.astype('float32') / 255.0

    pts, desc, _ = fe.run(img)
    tracker.update(pts, desc)         # feed new observations

tracks = tracker.get_tracks(min_length=3)  # only tracks seen in ≥3 frames
print(f'Active tracks (len≥3): {tracks.shape[0]}')
# tracks shape: M × (2 + max_length)
# col 0: unique track id, col 1: avg descriptor score, cols 2+: point ids
```

--------------------------------

### Fast Grid-Based Non-Maximum Suppression (NMS)

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Applies fast grid-based Non-Maximum Suppression to a set of candidate corners. Points are kept if they are the highest confidence within a specified radius, significantly speeding up keypoint selection.

```python
from demo_superpoint import SuperPointFrontend
import numpy as np

fe = SuperPointFrontend('superpoint_v1.pth', nms_dist=4,
                        conf_thresh=0.015, nn_thresh=0.7)

# Synthetic corners: shape 3×N  [x, y, confidence]
rng = np.random.default_rng(0)
N = 500
corners = np.vstack([
    rng.integers(10, 150, N).astype(float),   # x
    rng.integers(10, 110, N).astype(float),   # y
    rng.random(N)                              # confidence
])

H, W = 120, 160
nmsed, surviving_inds = fe.nms_fast(corners, H, W, dist_thresh=4)

print(f'Before NMS: {N} points')
print(f'After  NMS: {nmsed.shape[1]} points')
# surviving_inds contains the original column indices that survived
```

--------------------------------

### PointTracker.draw_tracks: Track Visualization

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Visualizes track segments on a given image using OpenCV. Tracks are colored by their average descriptor match score, and the most recent point is highlighted. Ensure the input canvas is a BGR uint8 image.

```python
from demo_superpoint import SuperPointFrontend, PointTracker
import cv2, glob, numpy as np

fe = SuperPointFrontend('superpoint_v1.pth', nms_dist=4,
                        conf_thresh=0.015, nn_thresh=0.7)
tracker = PointTracker(max_length=5, nn_thresh=0.7)

frames = []
for path in sorted(glob.glob('assets/icl_snippet/*.png'))[:10]:
    img = cv2.imread(path, 0)
    img = cv2.resize(img, (160, 120), interpolation=cv2.INTER_AREA).astype('float32') / 255.0
    pts, desc, _ = fe.run(img)
    tracker.update(pts, desc)
    frames.append(img)

tracks = tracker.get_tracks(min_length=2)
# Build a colour visualization on the last frame
last = frames[-1]
canvas = (np.dstack((last, last, last)) * 255.).astype('uint8')
tracks[:, 1] /= float(fe.nn_thresh)          # normalize scores to [0, 1]
tracker.draw_tracks(canvas, tracks)

cv2.imwrite('/tmp/tracks_output.png', canvas)
print('Saved visualization to /tmp/tracks_output.png')
```

--------------------------------

### BibTeX Citation for SuperPoint Paper

Source: https://github.com/magicleap/superpointpretrainednetwork/blob/master/README.md

Provides the BibTeX entry for citing the SuperPoint research paper, which details the self-supervised interest point detection and description method.

```bibtex
@inproceedings{detone18superpoint,
  author    = {Daniel DeTone and
               Tomasz Malisiewicz and
               Andrew Rabinovich},
  title     = {SuperPoint: Self-Supervised Interest Point Detection and Description},
  booktitle = {CVPR Deep Learning for Visual SLAM Workshop},
  year      = {2018},
  url       = {http://arxiv.org/abs/1712.07629}
}
```

--------------------------------

### PointTracker.draw_tracks

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Visualizes the tracked points on an image. Tracks are colored by their average descriptor score, and the most recent point is highlighted.

```APIDOC
## `PointTracker.draw_tracks` — Track Visualization

Renders all track segments onto an existing BGR uint8 image using OpenCV line drawing. Each track is colored by its average descriptor match score via a jet colormap (blue = weak, red = strong). The most recent endpoint is highlighted with a blue circle.

### Method

*   **`draw_tracks(canvas, tracks)`**

### Parameters

*   `canvas` (numpy.ndarray): The image (BGR uint8) to draw the tracks on.
*   `tracks` (numpy.ndarray): The tracks data, typically obtained from `get_tracks()`. Expected shape is `M × (2 + max_length)`.

### Returns

*   None. Modifies the `canvas` in-place.
```

--------------------------------

### PointTracker.nn_match_two_way: Bidirectional Descriptor Matching

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Performs bidirectional nearest-neighbor matching between two sets of descriptors. It keeps only mutually consistent pairs below a specified threshold. The output is an array of matching indices and their L2 distances.

```python
from demo_superpoint import PointTracker
import numpy as np

tracker = PointTracker(max_length=5, nn_thresh=0.7)

# Simulate two sets of unit-normalized descriptors
rng = np.random.default_rng(42)
D, N1, N2 = 256, 80, 90
desc1 = rng.standard_normal((D, N1)); desc1 /= np.linalg.norm(desc1, axis=0)
desc2 = rng.standard_normal((D, N2)); desc2 /= np.linalg.norm(desc2, axis=0)

matches = tracker.nn_match_two_way(desc1, desc2, nn_thresh=0.7)
# matches: 3×L  [idx1, idx2, l2_distance]
print(f'Mutual matches found: {matches.shape[1]}')
if matches.shape[1] > 0:
    print(f'Best match distance: {matches[2].min():.4f}')
    print(f'Worst kept distance: {matches[2].max():.4f}')
```

--------------------------------

### PointTracker.nn_match_two_way

Source: https://context7.com/magicleap/superpointpretrainednetwork/llms.txt

Performs bidirectional nearest-neighbor matching between two sets of descriptors, returning only mutually consistent matches below a specified threshold.

```APIDOC
## `PointTracker.nn_match_two_way` — Bidirectional Descriptor Matching

Computes L2 distances between two sets of unit-normalized 256-dimensional descriptors and keeps only mutually consistent nearest-neighbor pairs (A→B and B→A agree) below `nn_thresh`. Returns a `3×L` array of `[idx_in_desc1, idx_in_desc2, l2_distance]` for each surviving match.

### Method

*   **`nn_match_two_way(desc1, desc2, nn_thresh)`**

### Parameters

*   `desc1` (numpy.ndarray): The first set of descriptors (shape `D × N1`).
*   `desc2` (numpy.ndarray): The second set of descriptors (shape `D × N2`).
*   `nn_thresh` (float): The maximum allowed L2 distance for a match.

### Returns

*   numpy.ndarray: A `3×L` array where each column represents a match: `[index_in_desc1, index_in_desc2, l2_distance]`.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.