Icy Ewe: 3D scanning on the cheap with a scratched depth camera and a slow laptop
Second-hand depth cameras (an Intel RealSense SR305, the D415 hiding inside a Prowise MOVE 3in1) see depth 30 times a
second for the price of a takeaway. Turning one into a 3D scanner is easy right up to the point where you line the
frames up. Then the object grows a second nose.
I'm working on about 50 projects at once, so I don't have the time or brain capacity for humour; it cuts into my four
hours of sleep-eating time (efficiency). So, straight to it, apart from the title: Icy Ewe (say it out loud) is the write-up of how my app,
Scantastic, keeps a scan together on bad cameras and slow computers:
- Picture features check every step the 3D shape suggests, and veto it when the shape is fooling itself.
- Loop closures can't lie: one the pictures can't confirm may only move a frame as far as the chain could really
have drifted. On a plain test blob, 40 of 42 closures had been wrong.
- Turntable mode holds every frame to one fitted axis; a printed marker ring is optional.
- TRACKING LOST tells you while you can still do something about it.
- Slow PCs record now and stitch afterwards, in a separate process that just tries again on fewer frames if it
runs out of memory.
- Speed profiles, side-by-side alignment with identical answers, and a graphics card that has to pass a test first.
- A sensor check that maps where your camera's window is scratched.
The honest bit: all the measured results come from made-up scans with known answers, and the new methods haven't been
through a real camera yet. There's a test plan in section 8. If you have one of these cameras, please break it and tell
me what happened.
It's also a defensive publication: section 9 dedicates the methods and their variations to the public, so they stay
free for hobbyists.
Paper: The-Dorkknight/icy-ewe · App: The-Dorkknight/scantastic
---
The paper
---
title: "Icy Ewe"
subtitle: "3D scanning on the cheap: turning a scratched, second-hand depth camera and a slow laptop into a 3D scanner that doesn't lose the plot. A hobbyist's field guide and a defensive publication."
author: "Matthew Armstrong (The-Dorkknight)"
date: "Version 1.1, 13 November 2026 (first published as \"Depth Perception\", 2 November 2026)"
---
!"Icy Ewe", the cover art and the title of this paper: a sheep in a parka points a scanner at an icy rune stone. Say it out loud: icy ewe sounds like "I see you", which is a depth camera's whole job, and this one is doing it on the cheap, in the cold, with second-hand kit. (The ewe is wearing glasses because the camera's window is scratched.)
!A real scan on real hardware. A face, scanned with the depth camera inside a Prowise MOVE 3in1 (an Intel RealSense D415) and Scantastic 0.5.1 on 11 October 2026: 31 of 32 frames merged. Its owner called it "a lot better, still gloopy". Most of this paper is about what happened next.
The short version
- The goal: a free desktop app that turns a cheap depth camera into a tabletop 3D scanner. The cameras are an Intel
RealSense SR305 and the D415 inside a Prowise MOVE 3in1, both second-hand, one with a scratched window. The computer
is anything down to a 7th-generation Core i3 with no graphics card. The app is called Scantastic.
- The hard part isn't the camera, it's lining the frames up. A scan is dozens of snapshots taken from different
places. Put one snapshot a few degrees out and the object grows a second nose. Over 90% of the time a build takes is
spent lining frames up.
- What this paper describes (in enough detail to rebuild it):
- picture features (the patterns on the object and the room) used to check every step the 3D shape suggests;
- a rule that only lets a loop closure move a frame as far as the chain could really have drifted;
- a turntable mode that holds every frame to one fitted axis, with an optional printed marker ring;
- live tracking that says "TRACKING LOST" before you waste a scan;
- a "record now, stitch afterwards" style for slow PCs, where the slow part runs in its own process with a memory
budget and simply tries again on fewer frames if it runs out;
- speed profiles, alignments side by side in helper processes, and an exactly-the-same-answer shortcut
for the final polish;
- a sensor check that points the camera at a wall and maps where the window is scratched.
- How well it works: on made-up scans with known answers, the version before this work failed every handheld and
turntable scan. Now 0 of 40 turntable scans fail, and 1 of 20 held-out handheld scans does. No real camera has
been through the new methods yet. Section 8 is a test plan.
- Why a paper: it's a defensive publication. Section 9 describes the methods and many variations of them and
dedicates them to the public, so that they are prior art and nobody can easily patent them and charge hobbyists for
them later.
1. Why this exists
Proper 3D scanners cost hundreds of pounds. Second-hand depth cameras turn up in odd places: the RealSense SR305 was
sold for face login and gesture control, and a D415 sits inside a classroom document camera (the Prowise MOVE 3in1).
They see depth, 30 times a second, for the price of a takeaway.
The catch is everything else:
- The software that came with them was made for faces and gestures, not scanning. Intel's own SDK is a toolbox, not a
scanner.
- The cameras are noisy. One of them has a scratched window that makes part of the view flicker.
- The computer it has to run on is a 7th-gen i3 laptop: 2 cores, 4 threads, 8 GB, no graphics card worth the name.
- The existing free scanning software that does this well (SLAM systems such as ORB-SLAM3) is under the GPL. Scantastic
is under a noncommercial licence (free to use, not to sell), and the two licences can't be mixed (section 3).
I'm working on about 50 programming projects at the same time, so I don't have the time or the brain capacity for
humour. Each joke cuts into my four hours of sleep-eating time (efficiency). This paper will therefore keep the jokes
to a minimum and the pictures to a maximum.
!The first live picture, 1 October 2026: the colour view and, beside it, the depth the camera sees, with a "nothing in the middle of the view" warning. Everything after this started here.
2. How a depth-camera scanner works, in two minutes
A depth camera gives you a picture where each pixel says how far away that bit of the world is, as well as
what colour it is. One such picture is a frame: a patch of 3D surface seen from one side.
To scan a whole object you take frames from all round it (moving the camera, or turning the object), then:
1. Clean each frame. Throw away the unreliable pixels: the "flying pixels" along outlines, readings too near or too
far, and the room behind the object.
2. Line the frames up. Work out where the camera was for each frame, so all the patches land in the same place.
This is the hard part.
3. Fuse them. Every frame "votes" on where the surface is. The noise averages out and one smooth surface is left.
4. Save a mesh (STL, OBJ or PLY) for a slicer, Blender or FreeCAD.
!The whole pipeline. The lining-up stages (purple, red, teal) are where almost all of the time goes, and where almost all of the clever bits in this paper live.
Lining up, in one paragraph. The standard tool is ICP (Iterative Closest Point): slide one frame over another
until each point sits as close as possible to the other frame's surface. It's excellent when the frames start close
together, and it's fooled by smooth or symmetric shapes. A ball fits a ball in any orientation. A plain box fits itself
four ways round. You chain frame 1 to 2, 2 to 3 and so on, then add loop closures (frame 20 also overlaps frame 1:
tie them together) and let a pose graph spread out the leftover error. Each wrong link in that chain is a doubled
surface in the final model.
!Where the time goes, measured on one made-up 24-frame handheld scan (Scantastic 0.11.0, a 2-core computer). Lining up is 111 seconds; making the mesh is 16.
3. What already exists
This is a well-studied problem. What follows is a hobbyist's search, not a professional one, and not legal advice.
| What | What it does | Why Scantastic didn't just use it |
|---|---|---|
| KinectFusion (Newcombe et al., 2011) [1] | Live tracking against a fused volume, on a graphics card | Needs a GPU; the volume is the depth fusion Scantastic uses after lining up |
| ElasticFusion, BundleFusion and similar [2] | Dense live reconstruction with loop closure | GPU-only; research or non-commercial licences |
| ORB-SLAM3 [3] | Feature-based SLAM: keyframes, relocalisation, loop closing | GPLv3, which can't be combined with a noncommercial licence. Its authors offer a paid commercial licence |
| Open3D's reconstruction system (Choi, Zhou, Koltun, 2015) [4], colored ICP (Park et al., 2017) [5] | Fragments, pose graphs, loop closures checked by geometry; ICP that uses colour as well as shape | Used: Open3D (MIT licence) is the engine underneath. The checks in section 4 are built on top of it |
| Visual-plus-geometric loop-closure checks (e.g. Aalto, ICIP 2016) [6] | Accept a loop closure only if image features and shape agree | Same family of idea as section 4.5; the details differ |
| Commercial turntable scanners and photogrammetry rigs | Turntables, often with printed marker mats, to know each turn | Closed software; the marker idea itself is old and well known |
| Patents found with titles close to this work | e.g. scanning an object turned in the hand (US 9,639,943 B1) [7]; power-efficient depth sensing for live reconstruction (US 9,443,350 B2) [8]; turntable scanner calibration (US 2003/0202691) [9] | Not assessed. Listed so readers can look. Nothing here is a claim about what they cover |
The gap Scantastic fills is not a new algorithm. It's a set of plain, checkable rules that make standard tools
(ICP, ORB features, pose graphs, TSDF fusion) behave on bad cameras and slow computers, in a program anyone can
run by double-clicking. Section 9 writes those rules down as prior art.
4. The method, in enough detail to rebuild it
All numbers are Scantastic's defaults (0.9.0 to 0.11.0). Distances are in metres at the camera unless they say
otherwise.
4.1 Capturing a clean frame
- Depth confidence can be set stricter for a worn or scratched window ("Strict (worn / scratched glass)").
- Edge trim. Pixels next to a sudden depth jump are dropped: 2 pixels on the SR305, 5 on the D400s, whose outlines
are softer.
- Cut out the subject (on by default). Keep the surface nearest the camera in the middle of the view, plus
everything joined to it without a depth jump, within a slab of depth. The room goes. Why: without this, a still
room dominates the alignment. Turn yourself in front of a fixed camera and the room "doesn't move", so the frames get
lined up to the room and the face comes out doubled. (This is the "second nose" in section 6.)
- Average when still. If the camera has hardly moved (under 1 pixel of shift and 1.5 mm of depth change), up to 5
frames are averaged into one capture, pixel by pixel. A pixel from an earlier frame is only used where it agrees.
- Speed hints on the live picture: "Steady", "Moving quickly" (over 150 pixels a second at 640 wide) and "Too fast -
slow down" (over 350). Coded-light cameras smear when you rush them.
- Distance colours. The live depth picture is green in the best band (30 to 50 cm for the SR305, 35 to 65 cm for
the D400s) and fades to red outside it.
4.2 Picture features: a second opinion on every step
The 3D shape can't tell a ball from a rotated ball, but the pattern on it can. So every frame also gets:
- up to 1,500 ORB keypoints (corners in the picture), found on a contrast-boosted greyscale copy (CLAHE);
- keypoints kept only where there's depth (in turntable mode, also at least 6 pixels inside the depth outline:
outline points sit half on the still background and say "nothing moved");
- each keypoint lifted into 3D with its depth.
For two frames, keypoints are matched with Lowe's ratio test at 0.9 (0.8 kept too few right matches on plain
objects), then a RANSAC rigid fit: the 3D motion that the most matches agree with, to within 6 mm. That gives a
camera move with a confidence that rises from 0 at 12 agreeing matches to 1.0 at 52.
That estimate is the second opinion. It's used three ways:
1. As one more starting guess for ICP.
2. As a veto: if the pictures are confident (0.5 or more) and ICP's answer is more than 2.5° or 12 mm away from
theirs, ICP is wrong (a smooth surface fitting itself in the wrong place), and the frame is placed where the pictures
say, then fine-tuned from there.
3. As a vote in loop closures (section 4.5).
4.3 Chaining frames, with guards
Each new frame is aligned to the last frame that worked:
- Starting guesses: the tracker's or pictures' guess (if any), "the same move as last time", and "no move". ICP
(colour ICP, matching within 8.7 mm at the default quality) runs from each; the one with the best two-way overlap
wins. Two-way means checking that frame A's points find frame B's surface and B's find A's: a frame full of
noise, or of the whole room, finds something near almost every point one way, but not the other way round.
- If that's weak (under 60% overlap), the slower feature-based global alignment (FPFH + RANSAC) is tried too.
- If it's suspicious (overlap under 60%, or the surfaces sit more than 1.6 times further apart than usual) and the
pictures don't vouch for the step, the frame is also tried against 6 earlier frames spread across the scan. The
closest fit wins. This is how a quick swing back to the start re-attaches there.
- If nothing fits but the pictures are sure, the picture estimate is used and fine-tuned.
- A frame that fits nothing (under 35% overlap) is skipped, not glued on somewhere wrong.
4.4 The room check, for plain objects
A plain white box or mug gives the pictures almost nothing to match. But the room behind it doesn't move. So in
handheld mode, each frame also keeps a thinned (6 mm) copy of the whole view, before the subject was cut out. When the
pictures can't vouch for a step:
- the two whole-room views are aligned coarse to fine (30, 15, then 8 mm), from each starting guess;
- a fit counts only with at least 60% overlap and under 4 mm average error;
- tables and walls are flat and slide over each other, so among the fits that pass, the one most picture matches
agree with wins;
- if the room says the object's own fit is more than 2.5° or 12 mm out, and at least as many picture matches side
with the room, the room wins.
The same pictures catch a classic mistake. If they say the camera hardly moved for most steps (under 1° and 3 mm)
while the shape says it did, the object was turned by hand in front of a still camera. The pictures are right about the
room and wrong about the object. They're not allowed to overrule, and the report suggests Turntable mode.
4.5 Loop closures on a leash
Loop closures are where the 0.9.0 work found its worst errors. On a plain made-up blob, 40 of 42 accepted closures
were wrong, by tens of degrees: a smooth surface happily fitting itself in the wrong place, with plenty of overlap.
The candidates are: frames 2 to 4 steps apart, every frame against the first, and up to 4 earlier frames seen from
within 30° and 20 cm (a "revisit"). Each is aligned (coarse plain ICP at 4 times the match distance, then colour ICP),
and kept only with at least 50% two-way overlap and a surface error under 1.6 times the scan's typical step. Then:
1. Confirmed by the pictures? At least 12 picture matches agree with the closure and the pictures don't back
their own best estimate clearly better than this closure (0.10.0: a dozen chance matches had "confirmed" closures
18-24° out). Then it's in.
2. Not confirmed? It may only move a frame as far as the chain could have drifted:
- at most 2° + 0.25° for every step in between that the pictures vouched for + 5° for every step they couldn't;
- at most 8 mm + 2 mm per vouched step + 30 mm per unvouched step.
3. Either way, if the two frames' own picture features disagree with the closure by more than 2.5° or 12 mm, and
either the tracker's or the pictures' estimate for that pair was confident, or the pictures clearly prefer their
own answer, it's out.
!The loop-closure rule. Steps the pictures vouched for drift only a fraction of a degree each, so a closure that wants to move a frame by much more than that is a false fit.
4.6 Polish, and leaving out what moved
- Pose graph (Open3D's Levenberg-Marquardt optimiser) spreads the leftover error over the chain.
- Polish (handheld): every frame is aligned again against the model made from all frames together, in two
passes.
- Frames that disagree with their neighbours (median point-to-plane offset over 2 times the scan's typical offset,
and more than 0.8 mm) are left out, never more than 40% of them.
- Areas that moved (a blink, a mouth, a hand passing through, or a sensor defect that puts a bump at a fixed place in
the image) are cut out of just that frame: a patch at least 25 points big, over 3 times the typical offset and 3 mm
away, but under 35% of the frame. The other frames still cover it.
4.7 Turntable mode: one axis to rule them all
With the camera on a stand and the object on a turntable, every step is a turn about the same line. Scantastic
uses that hard:
- Remove what stands still. Either record the empty turntable first (any pixel within 8 mm of the empty scene is
background), or find the table plane and, on top of it, the turntable's top: a flat layer parallel to the table
and wider than the object. Left in, the turntable top looks identical at every turn and pulls every step short.
- Picture features on the object only. Keypoints near the object's outline are dropped in turntable mode (they sit
on the still background and said "nothing moved").
- Fit the axis to the steps. Each step's rotation axis is fitted to one line. A step that doesn't fit is tried
again at the angle the pictures or neighbouring steps suggest. Each frame's pose is then just its angle: the sum
of the turns before it. One bad step can't bend the rest of the scan.
- Fine-tune axis and turns together. Each small step measures its turn well but its axis badly (a 12° turn about a
line 5 mm away looks almost the same), and on a made-up scan that grew to about 6 mm on the far side of the object. So the axis (4
numbers) and every frame's turn are fitted together by Gauss-Newton on point-to-plane distances, using each frame
and its 4 nearest frames within 45°, with each turn held near what its step measured.
- Close the full turn. When the scan goes all the way round, the last frames are also matched to the first and the
angles are solved again with those closures in, so a little error per step can't add up to a gap.
- If the steps don't fit one axis (more than 3 mm from it), the scan is treated like a handheld one instead.
- No free polish. The handheld polish lets each frame move freely in any direction. On turntable scans of plain
objects that undid the axis fit (0.6 mm became 3.5 mm), so turntable scans skip it.
- Optional marker ring. A printed ring of ArUco markers lies on the turntable around the object. The object turns
with the ring, so the ring's pose in each frame gives the turn directly.
!Turntable mode from above. Each frame sits on the fitted axis at the sum of the turns before it; a step that doesn't fit is re-tried.
!A marker ring of the kind Scantastic prints (an illustration drawn for this paper with OpenCV's ArUco markers; the app's own ring has its own layout and a 50 mm check bar).
4.8 Live tracking: knowing you're lost while you can still do something about it
Version 0.10.0 added the parts of SLAM that help here (keyframes, and finding the way back when lost), written from
scratch on OpenCV's ORB features, so the licence stays the same:
- Keyframes. Each live picture is matched to the current keyframe, not the frame before, so small errors don't
pile up. A new keyframe is taken after 8°, 4 cm, or when fewer than 60 features still match. 40 recent keyframes are
kept.
- Finding the way back. When a picture can't be matched (camera covered, swung away), the tracker tries recent
keyframes, then a spread of older ones.
- TRACKING LOST appears on the live picture while it's lost.
- Each capture starts where the tracker said the camera was. These guesses carry where they came from and which
track (one START to STOP, or one recording) they belong to. Guesses from two different tracks are never compared:
the object may have been turned over in between. Live guesses may overrule ICP at 2.5° / 12 mm; an older recording's
chained guesses drift more and keep a looser 6° / 4 cm.
- The camera thread only copies and queues. Captures are worked out on their own thread, at most 2 waiting. If the
PC falls behind, a capture is skipped with a message rather than freezing the live picture.
!Keyframe tracking. Blue arcs: each frame is matched to its keyframe. Red: the camera was covered; the tracker found its way back by matching an older keyframe.
!The real banner, drawn by the app's own function over a made-up frame.
4.9 Slow PCs: slow, but never falling over
On a slow PC such as a 7th-gen i3, stitching while you scan should starve the camera: frames drop and the picture
freezes. (Expected from timings on a 2-core test computer; not yet tried on a real i3.) So there are two scan
styles:
!Two scan styles. On a slow PC, scanning only records; the heavy work runs afterwards in its own process.
- The speed check. The first time it starts, the app times one tracking step on a made-up 640 × 480 picture. With
4 processor threads or fewer, or a step slower than 150 ms, it picks "Record now, stitch afterwards". You can
change it.
- Recording saves the camera's frames to disk at most 10 a second, using the same cleaned depth a live capture
would get. The frame list (frames.json) is rewritten every 10 frames (every 50 on long recordings), to a temporary
file that then replaces the old one, so a crash leaves a usable recording minus its last few frames.
- Stitching runs in a separate process after STOP. It cleans the frames, follows the camera through all of them
with the live tracker, and keeps one frame per 6° or 3 cm of movement. On a made-up 116-frame recording,
aligning every frame took 14 minutes on the 2-core test computer; the 48 frames worth keeping took 4.
- Memory budget: at most 30% of free memory at 5 MB a frame, never fewer than 40 or more than 300 frames. A longer
recording is thinned to every n-th frame to fit.
- If it dies, only the stitching process dies. It's started again on every 2nd frame, twice at most. A process that
dies before doing any work isn't blamed on memory. The recording stays on disk whatever happens. Build Mesh turns
into Cancel while it runs, and the status bar shows the minutes left.
!Crash-proof stitching. Left: how many frames a stitch may hold. Right: what happens if it still runs out.
!Thinning a recording by motion. Frames that mostly repeat each other are skipped before the slow part.
4.10 Speed profiles, side-by-side alignment and the graphics card
Version 0.11.0 brought over the speed profiles from my STL-to-STEP converter, then measured what actually helps here.
!Speed profiles. Auto picks one from the computer's cores and memory.
- Priority. Building and stitching run at low priority on Potato ("nice 10" on Linux and macOS, "idle" on
Windows), so the computer should stay usable. It makes nothing faster; it stops the build hogging the computer.
- Alignments side by side (Moderate, and Extreme when no graphics card is in use: with a card, alignments queue on
it one at a time). The loop-closure alignments are independent of each other, and so are
the starting guesses of one chain step. Helper processes, each holding its own copy of the frames, run them while the
main build process works through them too. Answers are put back in the original order and the checks then run in that
order, so the result is the same (largest pose difference measured: 3 × 10^−13^, which is Open3D's own last-digit
noise).
- A helper ends when its pipe breaks or a watchdog sees the builder gone (Cancel).
- A helper that dies or fails a task only costs time: the builder does that task itself.
- The number of helpers is cut to fit in half the free memory (300 MB plus 1.5 times the frames each).
- Each process gets two Open3D threads per core's share.
- Exactly-the-same polish, quicker. Colour ICP works out a colour gradient for every point of the target, from its
neighbours within 2 times the match distance, on every call. In the polish the target is the whole model, and each
frame only sees part of it. So only the model within 5 times the match distance of the frame is used. Points
further than 3 times can't change the answer. If the frame moved more than the spare 2 times, or the answer scores
differently against the whole model, it's redone on the whole model. Poses matched the uncropped run to 10^−14^; the
polish took 18 seconds instead of 24 on one made-up scan.
- What the three margins are for: matches are only made within 1× of a point; each point's colour gradient
looks 2× further; so nothing beyond 3× can change the answer. 5× leaves 2× to spare for the frame moving.
- Repeatable fallback. The feature-based fallback alignment uses random sampling. It's now seeded, so the same
frames always give the same answer.
- The graphics card, with a gate. Open3D's newer "tensor" ICP and depth fusion can run on an Nvidia card (CUDA). The
standard Open3D for Linux already contains that part. Before a card is used, a separate process runs the actual
steps (colour ICP between two small made-up surfaces, and a depth fusion) on the card and on the processor, and
they must agree to 0.5 mm. During a build, any card error (out of memory, a driver fault) switches the card off and
the processor redoes that step; an error is never mistaken for "these frames don't overlap".
- Not used: Nvidia on Windows (Open3D's Windows CUDA build is a preview), Apple graphics (Open3D has no Metal
support), AMD and Intel graphics.
!Side by side. The answers come back in the original order, so the result is the same as one process.
!The exactly-the-same crop. Only the part of the model that can change the answer is used.
4.11 The sensor check: mapping a scratched window
Point the camera at a plain flat wall, hold still, and the app collects 30 frames. A flat wall seen by a pinhole camera
has 1/depth changing in a straight line across the picture, so a smooth low-order fit of 1/depth is the "true" wall.
That fit also absorbs lens distortion and a slightly bowed wall. (The fit is repeated with the worst pixels left out;
the written breakdown in the report uses an even more outlier-proof fit from 2,000 random trials.) A scratch then
stands out from it in one of three ways. These are the limits for pixels that get ignored while scanning:
| Fault | Ignored when (scaled to 40 cm) | Shown as |
|---|---|---|
| Flicker | a pixel's noise is over 2.5 times the typical noise, and over 1.5 mm | red on the noise map |
| Steady offset | a pixel is off the wall by over 5 times the typical spread, and over 2 mm | red (too far) or blue (too near) on the offset map |
| No depth | enclosed holes up to 5% of the view, and pixels that lose their depth more than a quarter of the time | purple |
The report's written diagnosis is more sensitive: it already counts an offset of 3 times the typical spread.
The marked pixels can then be ignored while scanning, all of them or only the no-depth ones, and shown live in
magenta.
!A real sensor check, on the D415 at 50 cm (11 October 2026): "noticeable damage", 8.1% of the view to ignore. Left, flicker; right, steady offset.
!The same check on a made-up wall with one scratch (flicker), one dent (steady offset) and one hole, as drawn by the app.
4.12 From frames to a mesh
- Smooth surface (default): TSDF fusion in an Open3D VoxelBlockGrid, sized from the scan itself because it reserves
its memory up front. On the SR305 the grid follows the Quality slider (2.5 mm at Low, about 1.5 mm in the middle,
1 mm at High) and is smoothed with 5 Taubin passes; the D400s start at a fixed 1 mm grid and 2 passes. Surface seen in
only one frame is dropped when there are enough frames.
- Watertight: Poisson reconstruction, trimmed back to within 2.5 grid cells of a scanned point.
- The 3D preview is coloured by how many frames saw each area, so thin spots show before you print.
- Cut and make solid: draw a line across the model to cut it, or let the app find the table. "Make solid" closes an
open scan by inside-outside voting along 9 directions.
5. A tour of the app
These screenshots come from the app itself, running on made-up data, because the camera wasn't at the computer the
paper was written on. They show version 0.10.0's window; 0.11.0 adds the Speed and graphics card box.
!The main window in its default "retro TV" look: live picture on the left (static when no camera is plugged in), settings on the right, and two big buttons.
!A made-up scan, coloured by height, with the view cube top right.
!Cutting: "Find the table" found the flat base; the part that will go is red, and the yellow handle drags the cut.
!Turntable mode in the Scan panel: record the empty turntable, save the marker ring, and the scan-style box.
!"Record now, stitch afterwards", chosen for a slow PC, with the honest expectations spelled out in the panel.
!The plain look, for anyone who doesn't want a wooden television.
6. The mistakes, for free
Every one of these happened. Most were caught by measuring, a few by a separate reviewer, and some by the owner of the
camera.
| What went wrong | What it looked like | The fix |
|---|---|---|
| The room was in every frame | A still room "won" the alignment, so turning in front of the camera gave a second nose | Cut out the subject (4.1) |
| A setting from an older Open3D | The fallback alignment's RANSAC got a "confidence" of 500, so it never stopped early: 400,000 iterations, every time | Proper (iterations, confidence) values |
| Open3D 0.20's one-line hole filling | Handed back vertices from memory that had already been freed: garbage in 19 of 30 tries | Keep every step alive and copy the arrays out: 0 of 30 |
| An outline trim made for the D415 | Silently cut 20% of the points from every SR305 frame | Trim per camera (2 px SR305, 5 px D400) |
| Loop closures on smooth shapes | 40 of 42 accepted closures on the plain blob were tens of degrees out | The drift rule (4.5) |
| Picture keypoints on the outline (turntable) | Background corners said "nothing moved", so every turn came out short | Drop outline keypoints, turntable only (it broke handheld scans when done there too) |
| The turntable's own top | Looks the same at every turn: pulled every step short | Find it and remove it (4.7) |
| The axis from small steps | About 7 mm out, 6 mm of error on the far side | Fit axis and turns together (4.7) |
| The free polish on turntable scans | 0.6 mm became 3.5 mm on the plain scan target | Turntable scans skip it |
| A dozen chance picture matches | "Confirmed" loop closures 18-24° out | Confirmed only if the pictures don't prefer their own answer (4.5) |
| The older recording tracker | One bad link put every later frame 0.7 m out, while reporting 0.65 confidence | Stitching uses the keyframe tracker |
| Aligning every recorded frame | 14 minutes for one 116-frame recording | Keep one frame per 6° or 3 cm: 4 minutes |
| Open3D 0.20 on Apple-silicon Macs | Needed Homebrew's libusb: "Library not loaded" | Macs use Open3D 0.19 (figure below) |
| A graphics-card error | Treated as "no overlap", so frames could be dropped silently | Switch the card off, redo on the processor |
| Helpers after Cancel | A busy helper kept running | A watchdog ends it within a second |
| A result file for 0.10.0 | Said 0 of 20 failed. Run again, the shipped code fails 1 of 20 | Corrected in 0.11.0's notes; the rerun is published next to it |
!Mistake, live: the first real run on an M5 Mac (24 October 2026). Open3D 0.20 couldn't find a library that only Homebrew installs. Fixed the same day.
!Building the camera driver from source on Linux (15 October 2026), before 0.8.0 switched to Intel's ready-made one. It took a while.
7. The numbers
Everything in this section comes from made-up scans with known answers (a benchmark that renders 5 objects with
rich and plain patterns, with an SR305-like noise model, from known camera paths). A scan fails if any kept frame
lands more than 3 mm from where it should. Tuning used seeds 0-1; the held-out seeds 1000-1001 were only used to check
finished code. Times are on a 2-core cloud computer.
!Results. Left: handheld held-out scans that failed, by version. Right: how far out the worst frame typically was, on scans that passed.
| Version, mode | Failed | Typical worst frame |
|---|---|---|
| 0.8.1 (before this work), handheld and turntable | every scan | — |
| 0.9.0 turntable (tuning + held-out) | 0 of 40 | 0.6 mm |
| 0.9.0 handheld, held-out | 0 of 20 (as recorded then; not re-run) | 0.9 mm |
| 0.10.0 live tracking (tuning + held-out) | 0 of 20 each | 1.0 mm |
| 0.10.0 record now, stitch later, held-out | 2 of 20 (one stray frame each, 6-8 mm) | 0.9 mm |
| 0.10.0 handheld held-out, re-run | 1 of 20 (the plain blob, 3.1 mm) | 0.93 mm |
| 0.11.0 handheld held-out | 1 of 20, the same scan, identical answers on all 20 | 0.93 mm |
| 0.11.0, graphics-card code run on the processor | 1 of 20 (the same scan) | 0.88 mm |
Speed, honestly. On a 7th-gen i3, expect several minutes from STOP to a mesh (estimated from the 2-core test
computer, which is in the same range; not timed on a real i3). The 0.11.0 speed-ups are small
on 2 cores: the polish about a quarter quicker, loop closures about 10% quicker with one helper. More cores and a
graphics card should help more, but neither has been measured.
8. A test plan, for anyone with a depth camera
If you have an SR305, SR300, a D400-series camera or a Prowise MOVE 3in1, please try these and report back (an issue
or discussion on the repository, with photos):
1. Sensor check on a plain wall at 40-50 cm. Post both maps and the percentage.
2. Scan target. Print the app's 70 mm test block, scan it in Turntable mode, and use "Compare mesh with scan target".
It reports the error in millimetres.
3. Turntable, with and without the printed ring, on a plain object (a mug) and a patterned one.
4. Handheld, both scan styles, on the same object. Note the time from STOP to mesh and whether TRACKING LOST
appeared.
5. A slow PC. On a 7th-gen i3 or similar: does "Record now, stitch afterwards" get picked, does it finish, and does
the computer stay usable while it works?
6. A many-core PC or an Nvidia card on Linux: Potato against Extreme, same scan, time to mesh.
9. Defensive disclosure
This section is written to be read as prior art. It describes methods implemented in Scantastic (versions 0.9.0 to
0.11.0, source published at the repository below), and variations of them. All of them are dedicated to the
public. Anyone may use them, free, for any purpose. The purpose of publishing them is to make it hard for anyone to
patent them and restrict their use. Where a number is given, any other value that does the same job is also disclosed.
Not legal advice.
D1. Choosing between live stitching and record-then-stitch by measuring the computer. On first start (or on
demand) the software times a representative step of its own live processing (feature extraction and matching on a
synthetic image; or any other step of the real pipeline) and reads the processor thread count (or, as a variation,
memory too). Below a threshold it selects a mode where scanning only records frames (optionally pre-cleaned, rate-limited) and all
alignment runs afterwards. The choice is shown to the user with an expected-time warning, and the user can override it.
Variations: re-measuring periodically or while scanning; switching modes mid-scan when frames start to drop;
thresholds on battery state, temperature or other load; recording at reduced resolution; recording only frames that
pass a motion or sharpness test.
D2. Crash-tolerant deferred stitching. The deferred alignment runs in a separate operating-system process with a
frame budget derived from free memory (a share of it divided by a per-frame cost, clamped to limits). If the process
dies, it is restarted on a subsampled set of frames (every 2nd, then every 4th; or any decreasing subset), a bounded
number of times. A process that dies before reporting any progress is treated as a different failure from running out
of memory. The recording's index is written atomically (to a temporary file, then renamed) at a decreasing frequency
as the recording grows, so a crash loses only the last few frames. Variations: splitting the recording into
overlapping chunks that are stitched and then joined; spilling to disk; any other subset rule (by motion, by time, by
sharpness).
D3. Motion-based thinning before global alignment. A lightweight tracker follows the camera through every
recorded frame; only frames that have turned or moved more than a threshold (6° or 3 cm; or any other threshold,
including one adapted to the object size or the overlap) from the last kept frame are passed to the expensive
alignment, together with their tracked poses as starting guesses. On a turntable, a fixed number of frames spread
evenly over the turn.
D4. Track-scoped, source-weighted pose priors. Each starting guess carries its source (live tracker, recording
tracker, picture features, marker ring) and a track identifier. Guesses from different tracks are never compared or
chained. The tolerance with which a guess may overrule a shape-based alignment depends on its source (tight for a
keyframe tracker, loose for a drifting frame-to-frame tracker). A guess with low confidence is replaced, for checking
purposes, by an independent pairwise estimate from the two frames' own picture features.
D5. Drift-bounded loop-closure acceptance. A loop closure between two frames is accepted without image-feature
confirmation only if it moves the frame by no more than a bound that grows with the number of chain steps between the
frames, with a small allowance per step that image features vouched for and a large allowance per step they couldn't
(2° + 0.25°/vouched + 5°/unvouched, and 8 mm + 2 mm/vouched + 30 mm/unvouched; or any monotonic function of those
counts, step lengths or step confidences). Image-feature confirmation requires both a minimum number of agreeing
matches and that the features do not clearly prefer their own best estimate; and any closure the two frames' own
features contradict is rejected. Variations: the same bound applied to chain steps or relocalisation; bounds expressed
as covariance in the pose graph instead of accept/reject.
D6. The still room as a referee. In handheld scanning of an isolated object, a down-sampled copy of the whole
scene (before the object is cut out) is kept per frame. Where image features can't vouch for a step, the scene copies
are aligned coarse to fine from several guesses. Among fits that pass overlap and error thresholds, the one most
image-feature matches agree with is chosen, and it overrules the object's own fit only if the features side with it at
least as much. Also: when image features say the camera stood still while the object's shape says it moved, the
software concludes the object was moved in front of a still camera, stops the features from overruling, and suggests a
turntable mode.
D7. Turntable poses as one axis plus angles. With a still camera, every pairwise step is treated as a rotation
about one common axis. The axis is fitted to all steps, off-axis steps are re-tried at an angle from image features or
neighbouring steps, and each frame's pose is the cumulative angle. Axis (tilt and position) and all angles are then
refined jointly by least squares over pairs of nearby frames (each frame's nearest few within 45°; or any other choice of pairs), together with full-turn closures where the scan goes all the way round, with each angle held near its measured
step. A free 6-degree-of-freedom refinement is skipped in this mode, and if the steps don't fit one axis the scan falls back to free handheld-style alignment. Static scenery is removed by an empty-scene
snapshot or by detecting the table plane and a turntable top (a flat layer parallel to and above the table, wider than
the object). Image keypoints near the object outline are excluded in this mode only. Variations: a printed marker ring
giving angles directly (ArUco, AprilTag, coded dots, a printed angle scale); a motorised turntable reporting angles; any
mix of these as priors.
D8. Exact cropping of the target in colour ICP. When aligning a frame to a much larger target (a fused model, a
previous scan), the target is cropped to the region within a margin of the frame's starting position, where the margin
is at least the colour-gradient neighbourhood radius plus the match distance plus an allowance for movement (5 times the
match distance in the implementation). The result is accepted only if the frame moved less than the allowance and its
fitness and error, re-scored against the whole target, are unchanged; otherwise the alignment is redone on the whole
target. Variations: caching target gradients instead; tiling the target; any margin derived the same way for other
neighbourhood-based ICP variants.
D9. Order-preserving parallel alignment with fail-safe helpers. Independent alignment tasks (loop-closure
candidates, multiple starting guesses for one step) are run in helper processes holding copies of the frames, with the
main process also working, and answers re-ordered to the original task order so the result equals a single-process
run. Helpers are tied to the main process by a pipe and a watchdog; a task that fails in a helper is run only by the
main process thereafter; the helper count is limited by free memory; random number generators used in alignment are
seeded per call so results don't depend on which process ran which task.
D10. A graphics-card gate made of the real work. Before an accelerator is used, a separate process runs the same
alignment and fusion steps on it and on the processor with synthetic input, and the accelerator is enabled only if the
answers agree within a tolerance. During use, any accelerator error disables it for the rest of the job and the
affected step is redone on the processor; an accelerator error is never interpreted as a negative result (such as "no
overlap"). The card list shown to the user gives, per card, whether it can be used and why not.
D11. A flat-wall sensor map for depth cameras. The camera is held still in front of a flat wall; a smooth low-order
surface is fitted to 1/depth across the image, robustly; pixels are classified as flicker (temporal noise well above
typical), steady offset (bias well above typical spread) or missing (enclosed holes), each with an absolute floor scaled
to a reference distance. The classes are shown as separate maps and can be excluded from scanning, together or
individually. Variations: other reference targets (a sphere, a printed pattern); repeating the check over time to track
wear.
D12. Live-scanning feedback. A "tracking lost" banner on the live picture when a keyframe tracker can't place the
current frame; speed warnings from image motion and depth change; distance colouring towards a best working band;
automatic averaging of frames when the camera is still; and captures queued off the camera's thread, bounded, with a
generation counter so cleared scans don't receive stale captures.
D13. Per-frame removal of areas that moved. After alignment, a coherent patch of one frame (a minimum point count
and maximum share of the frame) that sits much further from the other frames than the scan's typical offset, while the
rest of that frame agrees, is excluded from that frame only, and the corresponding pixels are excluded from fusion.
10. Limits, and what hasn't been tested
- None of the 0.9.0 to 0.11.0 methods has been run on a real camera yet. The real photos in this paper are from
earlier versions.
- All measured results are from made-up scans with a made-up noise model and texture.
- Not run: a real 7th-gen i3, a computer with more than 2 cores, any graphics card, a real out-of-memory death of the
stitching process, the Windows launcher, a printed marker ring, a printed scan target.
- 1 of 20 held-out handheld scans still fails (a plain blob), and record-now-stitch-later had 2 of 20 with a stray
frame.
11. Credits and how this was made
- Built on: Open3D (MIT) [10], OpenCV (Apache-2.0) [11], Intel's librealsense (Apache-2.0), NumPy, Pillow and
Python's tkinter.
- Written with help from Claude (Anthropic's AI assistant), which wrote much of the code, ran the benchmarks and
drafted this paper. The camera, the scratches, the bug reports from real hardware and the decisions are mine. Every
number above came from code that was run, and the made-up ones say so.
- Not affiliated with Intel, Prowise, or anyone else named here. RealSense is a trademark of Intel.
- Everyone who sends a test result, a correction or prior art I missed will be credited in the next version.
References
1. R. A. Newcombe et al., "KinectFusion: Real-time dense surface mapping and tracking", ISMAR 2011.
2. T. Whelan et al., "ElasticFusion: Dense SLAM without a pose graph", RSS 2015; A. Dai et al., "BundleFusion", ACM TOG 2017.
3. C. Campos et al., "ORB-SLAM3", IEEE T-RO 2021. <UZ-SLAMLab/ORB_SLAM3>
4. S. Choi, Q.-Y. Zhou, V. Koltun, "Robust Reconstruction of Indoor Scenes", CVPR 2015. <openaccess.thecvf.com>
5. J. Park, Q.-Y. Zhou, V. Koltun, "Colored Point Cloud Registration Revisited", ICCV 2017.
6. "Robust loop closures for scene reconstruction by combining odometry and visual correspondences", ICIP 2016. <users.aalto.fi
2 comments
Handheld Ops
Copyright Matthew Armstrong. Source-available under the
PolyForm Noncommercial License 1.0.0: free to use and change for
non-commercial purposes. Provided as is, with no warranty and no liability.
Not affiliated with Activision, Infinity Ward, Treyarch, Valve, ASUS, the
Bazzite project or any of the mod teams below.
One tap-friendly app that gets three classic shooters ready for handheld PCs
(ROG Ally, Steam Deck, Legion Go) on Bazzite or SteamOS (and Windows):
| Game | Campaign | Multiplayer |
|---|---|---|
| Call of Duty: Black Ops (2010) | Hidden gamepad mode switched on | Same, plus Plutonium's configs |
| Call of Duty 4: Modern Warfare (2007) | IW3SP-MOD installed: gamepad + aim assist | CoD4x: steps and official page (assisted) |
| Call of Duty: Modern Warfare 2 (2009) | IW-Pad installed: full controller support | IW4x installed: native controller + aim assist |
Plus, for all three:
- Steam launch options written for you (with Steam closed), so the normal
Steam Play button starts the modded game under Proton. Your own launch
options are never overwritten without asking.
- Full HD locked at every start (or 1440p / 4K): set in the game's config
files and again on the command line, so a game that falls back to "safe" or
"recommended" settings (MW2's 640-pixel habit) comes straight back.
- Five one-tap graphics tiers per game (Off, Battery saver, Balanced,
Quality, Ultra): the game's own settings plus a matching SweetFX preset, so
you never have to dig through the effects overlay.
- Look: ReShade/SweetFX-style sharpening and colour through vkBasalt on
Linux, switched on per game.
- Touchscreen help for the menus.
Every replaced game file is backed up and Remove puts it back.
!MW2 page
Step by step
1. Install the games in Steam and start each once (Black Ops needs that to
write its config files).
2. Open Handheld Ops and pick a game tab.
3. Press Install (or Controller ON for Black Ops). Downloads come
straight from each mod's official release page; the log shows every step.
4. Quit Steam (Steam menu > Exit), then press Write to Steam. Or press
Copy and paste each line into Steam > game > Properties > General >
Launch Options yourself.
5. Start Steam again and play from your library as usual. In Steam Input, use a
Gamepad layout for these games.
!CoD4 page
What the launch options look like
bash -c 'exec "${@/iw4mp.exe/iw4x.exe}"' -- %command%
Steam fills in %command% with its own Proton command; bash swaps the stock
.exe for the mod's. The same form is documented by IW-Pad. With the look on,
ENABLE_VKBASALT=1 VKBASALT_CONFIG_FILE="..." goes in front.
Graphics tiers
!Graphics tiers
Tap a tier on the game's page. It is applied straight away (quit the game
first) and again whenever you press Write to Steam.
| Tier | Game settings (only those the game already has) | Effects |
|---|---|---|
| Off | left as they are | none |
| Battery saver | 60 fps cap, vsync off, AA off, shadows off, 4x texture filtering, depth of field off, textures one step lower | light CAS sharpening |
| Balanced (default) | 60 fps cap, vsync off, 2x AA, shadows on, 8x filtering, best textures | SMAA + CAS sharpening |
| Quality | 90 fps cap, vsync off, 4x AA, shadows on, 16x filtering, best textures | SMAA + vibrance + luma sharpen |
| Ultra (SweetFX) | 120 fps cap, vsync off, 4x AA, shadows on, 16x filtering, best textures | SMAA + vibrance + contrast curve + luma sharpen |
- Bazzite / Linux: each game gets its own vkBasalt file; the Steam launch
option points at it. Quality and Ultra download the SweetFX shaders the first
time (automatically).
- Windows: press Install ReShade essentials for the game on the
Look tab. That installs ReShade without its long effect-package list,
adds only the 5 effects the tiers use (10 small files) and applies the tier.
ReShade's own list then shows just those 5, the start-up tutorial is off,
and Home still opens it. Effects you installed before stay on disk,
hidden; Show my other effects brings them back.
- Already have ReShade? It is never reinstalled or overwritten: the
button keeps your d3d9.dll, your own presets and effect packages, and only
changes five lines of ReShade.ini (which preset, the two shader folders,
skip unused effects, tutorial done). The original ReShade.ini is saved
the first time; Restore my ReShade puts it back exactly. A d3d9.dll
that is not ReShade (another mod) is left alone and reported.
- The fps caps suit a 120 Hz handheld screen; in Steam Gaming Mode you can
also cap frames in the Quick Access menu. Leave the Steam scaling filter (FSR)
alone: with the Full HD lock the game already runs at the screen's resolution,
and FSR only helps when a game renders below it.
Conflicting settings are removed
!Conflict warning, then Put back
Picking a tier (or Write to Steam) first clears anything that would undo it:
- Extra game config files such as an autoexec.cfg in the game's
players or main folder: lines that set vsync, the fps cap,
anti-aliasing, shadows, texture settings or the resolution are turned off
(commented out with a // handheld-ops off: marker, backup first). Other
lines, key binds, the game's own config.cfg and files a mod installed are
left alone. The Graphics card warns before and shows Put back after.
- ReShade settings that override a tier (Windows): a start-up preset,
NoReloadOnInit, preset-switch hotkeys and preset shortcut keys are set to
off; Handheld Ops' own presets for other tiers are removed. Your own preset
files are kept. Restore my ReShade undoes everything in ReShade.ini.
- Old launch options that contain only vkBasalt, an exe swap or the
resolution are replaced (and remembered for Put back). Launch options
with anything else of yours still ask first.
Aim feel (Black Ops)
If aim feels floaty: every graphics tier turns vsync off, the usual cause
of input lag. Then check Steam Input for the game (Controller settings > right
stick: smaller deadzone, Linear or Aggressive response curve). The Black Ops
page also has an experimental Look speed button that changes the game's
input_viewSensitivity (1, 1.25, 1.5, 2); it is not confirmed that the PC
game uses that setting for the gamepad.
Screen resolution (Full HD as the minimum)
!Screen resolution card
On by default for all three games at 1920x1080; tap to choose 2560x1440 or
3840x2160, or switch it off. It is set in two places:
1. The config files: r_mode in every engine config under the game's
players folder (CoD4 keeps them in players/profiles/<name>/), plus
r_fullscreen 1, r_aspectRatio "wide 16:9" and com_recommendedSet 1
where the game already has those lines. com_recommendedSet 1 tells the
game its recommended settings were already applied, so it stops replacing
yours with auto-detected ones.
2. The launch option: +set r_mode 1920x1080 +set r_fullscreen 1 after
%command%. These engines apply command-line settings after reading the
config, so the resolution comes back even if the config was reset.
If a game asks "Run in safe mode?" after a crash, answer No. In Gaming
Mode, also check the game's Steam properties for a Game Resolution option and
choose Native.
Black Ops
!Black Ops page
Controller ON sets the game's hidden gpad_enabled in the Singleplayer/
Zombies and Multiplayer configs (and Plutonium's copies). Optional aim
slowdown (campaign/Zombies only, experimental, never Multiplayer).
CoD4x (CoD4 multiplayer)
CoD4x comes with its own installer, and how the Steam copy behaves with it is
unclear (see RESEARCH.md), so the app gives the steps and opens
the official release page instead of installing it.
Controller in IW3SP-MOD (CoD4 campaign)
IW3SP-MOD's gamepad code comes from IW4x: it is switched on by
gpad_enabled (Handheld Ops adds +set gpad_enabled 1 at every start) and
reads Xbox-style (XInput) pads. If yours is a PlayStation, Switch or other
pad, start the game from Steam with Steam Input on (after Write to Steam),
so Steam presents it as an Xbox pad. Starting iw3sp_mod.exe outside Steam
(an old shortcut, Explorer) gets no Steam Input. Fallback: in Steam, Games >
Add a Non-Steam Game > iw3sp_mod.exe, and play that entry.
CoD4: stick works in menus but not in the game: IW3SP-MOD stops reading
the sticks for moving and looking whenever the mouse moves even a little
(or a keyboard key is pressed). Mouse in the game on the Controller card
is set to Off for CoD4 by default (+set in_mouse 0), so the pad stays in
charge; the pad drives the menus. Tap Write to Steam once. Use Steam
Input's Xbox controller layout.
CoD4: left trigger latches aim on until pressed again: that is the
toggle-aim bind. Turn Controller override on (Controller card), keep
Aim: Hold to aim, tap Write to Steam. In the game console (~) look
for "Handheld Ops controller file loaded".
Close Steam: next to Write to Steam. Steam is asked to close cleanly and
ended after 30 seconds if needed. Use it in Desktop Mode (in Gaming Mode
Steam is the whole screen, so the app refuses).
Controller override (CoD4 IW3SP-MOD, MW2 IW4x): tick Controller
override on the game's page and Handheld Ops writes its own controller file
(handheld_pad.cfg, in the game's main folder) and loads it at every start,
so you set the bindings here and never touch the mod. Defaults are IW4x's
own: hold to aim, normal sticks. Pick from the dropdowns: Button layout
(Default, Tactical, Lefty, Nomad, Default Alt), Aim (hold or toggle), Sticks
(Default = left moves, right looks; Southpaw swaps them), Look speed, and
any single button. Put the defaults back undoes it; I edit the
file myself keeps your hand-edited file. After tapping, press Write to
Steam once, then start from Steam. Proof it loaded: open the game console
with ~, it prints "Handheld Ops controller file loaded". Controller
report lists what the game saved and what Handheld Ops will start with
(also saved as a text file to send).
Left trigger latches aim on until pressed again / look feels heavy: the
Controller sticks card shows what the left trigger is bound to. Hold to
aim fix (on by default) changes a toggle bind to hold. Look speed steps
x1, x1.5, x2, x3. Tap Write to Steam, then start from Steam.
Right stick works in menus but not in the game: first set Steam Input to
Xbox controller (CoD4 > Controller settings > Browse configs / choose the
Xbox controller layout). That is what fixed it on the Ally; the default
"controller" layout did not. If it is still dead: the view turns by the
stick times the game's turn speed settings, and 0 means no turning. The
Controller sticks card shows the saved values and Turn speed fix (on by
default) sets standard ones at every start. Tap Write to Steam, then start
from Steam. Still nothing: tell me what the card shows.
Right stick does nothing (left stick and buttons work): the sticks are
tied to moving and looking by bindaxis lines the game keeps in its profile
config (players/profiles/<name>/config.cfg). A config without right-stick
lines leaves the right stick dead. The Controller sticks card on the CoD4
page shows whether the right stick is bound, and Right stick fix (on by
default) adds IW4x's default lines for a stick with no binding at all (a
custom layout such as southpaw is kept); switched off it takes out
exactly the lines it added. It runs on Write to Steam, Start, and the button
itself:
bindaxis A_LSTICK_X VA_SIDE MAP_SQUARED
bindaxis A_LSTICK_Y VA_FORWARD MAP_SQUARED
bindaxis A_RSTICK_X VA_YAW MAP_LINEAR
bindaxis A_RSTICK_Y VA_PITCH MAP_LINEAR
0.4.2 also put these four on the start command line (+bindaxis ...), and
with 0.4.2 the controller stopped working altogether in IW3SP-MOD. 0.4.3 takes
them off the command line. Show last start log (Windows) shows the exact
command the game was started with.
Display: borderless window (Windows)
!Display mode
Switching away (Alt+Tab) from these DirectX 9 games in exclusive fullscreen
can end in "DirectX encountered an unrecoverable error". On Windows the
default for IW4x is a borderless window at the locked resolution
(+set r_fullscreen 0 +set r_noborder 1 +set vid_xpos 0 +set vid_ypos 0),
which switches away cleanly. Tap Display to go back to fullscreen.
IW3SP-MOD (CoD4 campaign) starts in fullscreen by default (0.4.2+).
Started borderless it opened as a 1280x720 window in the top-left corner
whatever the locked resolution was. Borderless can still be picked for it
(Display button) to test. If Alt+Tab crashes CoD4 in fullscreen, avoid
switching away in game for now. Stock games keep fullscreen (they have no
borderless mode).
Safety
- MW2 campaign / Special Ops: play offline only. IW-Pad warns that the
Steam build's singleplayer still has remote-code-execution holes. The app
shows this before installing.
- IW4x is about 800 MB; the app checks free space first.
The look (Linux)
!Look tab
1. Pick a graphics tier on each game's page (see Graphics tiers above).
2. Press Write to Steam so the Play button uses that game's vkBasalt file.
3. In game, Home switches the effects off and on.
On Windows, use the normal ReShade installer (all three
games are DirectX 9).
On Windows
Handheld Ops runs on Windows too (tested so far only by pretending, on Linux;
see Known limitations). The differences:
- Steam's Play button starts the mod through a small Handheld Ops
launcher ("pythonw.exe" "...\steam-launch.pyw" %command%, no console
window). It starts the mod for the right mode (e.g. CoD4 Singleplayer ->
IW3SP-MOD) and the stock game otherwise (CoD4 Multiplayer). Because Steam
started it, Steam Input can turn any controller into an Xbox pad, which
is what IW3SP-MOD and IW4x read. The desktop / Start menu shortcuts start
the mod directly (fine for Xbox-style pads).
- The resolution lock still works from Steam: "Write to Steam" (Steam
closed) sets each game's launch option to `+set r_mode 1920x1080 +set
r_fullscreen 1`, which Steam adds to the game's command line. The Start
buttons and shortcuts pass the same, and the config files are set too.
- Look: vkBasalt is Linux-only, so the Look tab installs ReShade from
reshade.me with just the essentials (see Graphics tiers).
!Look tab on Windows
Touchscreen
!Help tab
- Steam Gaming Mode: a tap is a left mouse click where you touched.
- If taps do nothing: hold the Armoury Crate button for Mouse Mode.
- Desktop Mode: the touchscreen is a normal mouse.
Command line
HandheldOps-Linux.sh --list
HandheldOps-Linux.sh --install iw3sp # also: iwpad, iw4x, bo1-gamepad
HandheldOps-Linux.sh --remove iw4x
HandheldOps-Linux.sh --install bo1-gamepad --aim-slowdown
HandheldOps-Linux.sh --get-shaders --look sweetfx --look-for mw2
HandheldOps-Linux.sh --screen mw2=1920x1080 # or 2560x1440, 3840x2160, off
HandheldOps-Linux.sh --steam cod4 --steam mw2 # resolution + launch options (Steam closed)
HandheldOps-Linux.sh --tier mw2=quality # off, battery, balanced, quality, ultra
HandheldOps-Linux.sh --put-back bo1 # undo removed conflicts
HandheldOps-Windows.bat --display mw2=borderless # or fullscreen
HandheldOps-Linux.sh --stick-fix cod4=off # take the stick lines out (on = add)
HandheldOps-Linux.sh --look-speed 1.25 # Black Ops gamepad look speed (experimental)
HandheldOps-Linux.sh --show-options
HandheldOps-Windows.bat --reshade mw2 # Windows: official ReShade setup on MW2
HandheldOps-Windows.bat --shortcuts cod4 # Windows: shortcuts for installed mods
HandheldOps-Linux.sh --game-dir "/path/to/Call of Duty 4" --list
HandheldOps-Linux.sh --ui web # the web page (also: gui, dialogs, text)
HandheldOps-Linux.sh --version
What exists and what doesn't
| Part | State |
|---|---|
| Finds the three games in every Steam library (SD card too) | Works on test data |
| Black Ops controller ON/OFF, backups, undo | Works on test data |
| IW-Pad install / update / remove | Real download and install done (simulated MW2 folder) |
| IW4x install / update / remove from its update.json manifests | Real 787 MB install, no-change update and full removal done (simulated MW2 folder) |
| IW3SP-MOD install / update / remove | Works against a stand-in server; the real host (gitea.com) is blocked from the build machine |
| CoD4x | Steps + official page only |
| Writing Steam launch options | Works on a test copy of Steam's file; exe swap checked in bash |
| Resolution lock (configs + launch option) | Works on test configs; arguments checked in bash to reach the game after the exe swap; not yet seen in the real games |
| Look (vkBasalt) presets | Loaded by real vkBasalt on software Vulkan |
| Graphics tiers (Linux) | All four vkBasalt files loaded by real vkBasalt with the real SweetFX shaders; values read in; game-setting changes tested on Black Ops-style configs |
| Graphics tiers (Windows ReShade preset) | Preset and ReShade.ini format taken from ReShade's source; tested against sample files; not yet seen in ReShade itself |
| Windows Steam launcher (mod via Play, Steam Input) | The launcher script run end to end with stand-in .exe files: SP starts the mod with its settings, MP stays stock; Steam Input through it not yet seen on Windows |
| Borderless window (IW4x / IW3SP-MOD) | r_noborder confirmed in IW4x's source; not yet seen in IW4x. IW3SP-MOD: tried on Windows, opened at 1280x720 in a corner, so it defaults to fullscreen |
| Controller override file (handheld_pad.cfg + +exec) | Written, rewritten and kept when hand-edited, and the launch option only when ticked, all tested; the file name and main folder are what CoD4 normally searches, not yet seen loading in the game |
| IW3SP-MOD turn speed (in-game look) | Values are the usual console ones; added as +set, skipped when the config has a value above zero; not yet seen in the game |
| IW3SP-MOD stick bindings (right stick) | Names taken from IW4x's source and its thumbstick_default.cfg; config add/take-out tested on sample files. 0.4.2 (lines in the config and on the command line) left the controller dead on Windows; 0.4.3 uses the config only, not yet seen in the game |
| Removing conflicts (autoexec-style files, ReShade overrides, old launch options) and Put back | Tested on sample files; byte-for-byte put back |
| Existing ReShade kept, exact restore | Tested with a full existing install (DLL, own preset, effect package): nothing overwritten, ReShade.ini restored byte for byte |
| ReShade essentials install (headless setup + 10 files) | Headless behaviour read from ReShade's setup source; the 10 files downloaded for real; SweetFX SMAA compiled through vkBasalt; headless setup not yet run on Windows |
| Aim feel: vsync off / look speed | Written; effect on the feel not yet tested |
| SweetFX shader download | Real download with git done; the zip route (no git) works against a stand-in server |
| Windows: resolution launch option, Start buttons, shortcuts, ReShade setup | Logic tested on Linux by pretending to be Windows; not yet run on Windows (reshade.me and GitHub zip links are blocked from the build machine) |
| Tested on a real ROG Ally / with the real games | Not yet |
| HD textures, new lighting | Back burner (see RESEARCH.md) |
More
- HOW_IT_WORKS.md: exactly what is read, changed and backed up
- RESEARCH.md: all research notes, sources and decisions
- CHANGELOG.md, CONTRIBUTING.md,
SECURITY.md, THIRD_PARTY.md
---
Source code: The-Dorkknight/handheld-ops on GitHub
1 reaction
Scantastic
> WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN.
> Version 0.11.0-wip. Source-available and free for non-commercial use
> (PolyForm Noncommercial 1.0.0). No warranty.
Scantastic (until 0.7.0 called RealSense 3D Scanner) is a desktop app that turns an
Intel RealSense depth camera into a tabletop 3D scanner: live preview → scan while you turn the object → build a mesh → save
.stl / .obj / .ply. It can also record the raw camera streams and clean them
up in several passes before the mesh is built.
Works with the SR305 / SR300 (coded light) and D400-series cameras such as
the D415 inside the Prowise MOVE 3in1. The camera is detected automatically.
A Kinect v1 or v2 can be used too, as an experimental option that has not been
tried on real hardware yet (KINECT.md).
It is designed for modest hardware (a 7th-gen i3 with no GPU is the target);
everything has a CPU path.
!Main window
What has actually been tested
Being straight about this, because it is a work in progress:
| Area | Status |
|---|---|
| Whole app on a real camera | 0.2.0 has been run on real hardware (i5 U-series laptop, 8 GB). It scans and runs light, but the scans lack definition. 0.5.1 has been run on a D415 (sensor check and a face scan). The rest of 0.2.1 to 0.11.0 has not been run on a camera yet. |
| Stream clean-up pipeline (stream_pipeline.py) | Unit-tested on synthetic scenes (8 tests, run in CI). Not yet tried on real footage. |
| Sensor check breakdown and surface-detail options (new in 0.2.1) | Unit-tested on synthetic walls and scans (17 tests with the 3D-view ones; they need Open3D, so CI skips them). Not yet tried on a real camera. |
| 3D view colours, backgrounds, remembered settings, cancelling a build (0.2.2, merged from an older fork) | Exercised headless on synthetic scans, plus 4 unit tests. Not yet tried on a real camera. |
| Kinect v1 / v2 (new in 0.3.0, optional modules) | Untested on real hardware and against real drivers. 25 unit tests with stand-in drivers and a headless run of the app with a stand-in Kinect. |
| Retro TV look (new in 0.3.0, optional module) | Exercised headless on Linux, plus 5 unit tests. Not checked on Windows or macOS. --plain switches it off. |
| Cutting on the model (new in 0.4.0) | 25 unit tests on made-up shapes, and a headless run of the app that draws, drags, applies and undoes cuts on a noisy made-up scan of a ball on a table. Not yet tried on a real scan, or by a real hand on a real mouse. |
| Double-click launchers (new in 0.4.1) | The Linux launcher: 9 tests with a stand-in Python, and started for real under a headless display. The Windows launcher has not been run on Windows. The Mac launcher was run by the owner on an M5 Mac with 0.9.0: set-up ran, then Open3D 0.20 failed to load (Homebrew libusb). Fixed in 0.9.1, which is not yet tried on a Mac. |
| Live picture by itself, camera on/off, Rotate (new in 0.5.0) | 13 tests, 6 of them running the whole window with a stand-in camera and a stand-in "what is plugged in" answer (plugging in, turning off and on, turning off while starting, unplugging, a camera that will not start, turning the picture). Not yet tried with a real camera being plugged in and out. |
| D400 settings (0.5.1, 0.5.2) | 18 tests with a stand-in RealSense driver. 0.5.1 tried on a real D415: much better than 0.5.0, still soft. 0.5.2 not yet tried. |
| Handheld and turntable stitching, picture features, marker ring, scan target (new in 0.9.0) | Measured on made-up scans with known answers: turntable 0 of 40 failed, typical worst frame 0.6 mm; handheld 0 of 20 held-out and 3 of 20 tuning scans failed (0.8.1 failed every one). 21 tests. Not yet tried on a real camera, a real turntable, a printed ring or a printed target. See the results. |
| Live tracking, scan styles, record-now-stitch-later, captures off the camera thread (new in 0.10.0) | Made-up video-rate scans: live tracking 0 of 20 failed (tuning and held-out); record-now-stitch-later 2 of 20 held-out scans had one stray frame 6–8 mm out (of about 50 kept); the rest had a typical worst frame of 0.9 mm. 18 tests, including end-to-end window runs with a stand-in camera. Not yet tried on a real camera or a real 7th-gen i3. See the write-up. |
| Speed profiles, alignments side by side, graphics card (new in 0.11.0) | Held-out made-up handheld scans: the same answer as 0.10.0 on all 20 (1 of 20 fails, as 0.10.0 does when run again; its earlier "0 of 20" was not from its final code). The graphics-card method, run on the processor: also 1 of 20, worst frames within 0.04 mm. Final polish about a quarter quicker; side by side only about 10% quicker on the 2-core test machine. 23 tests. No real graphics card, no PC with more than 2 cores, and Windows and macOS not tried. See the write-up. |
| SR305 unchanged by the D400 work (0.8.1) | Compared with 0.5.0 on the same inputs: camera set-up, window settings and mesh match, the last within run-to-run noise. 3 tests keep it so. |
| Ready-made Intel driver, private Python 3.11, driver reuse (new in 0.8.0) | A real first run from nothing, here, with only Python 3.12 on the path: Python 3.11 downloaded, Intel's driver installed and hash-checked, app started. The suite passes on that Python (Tk 9). Not yet tried with a camera plugged in, or on your laptop. |
| Advanced-mode switch, firmware note, review fixes (new in 0.7.1) | 20 tests with stand-in drivers, cameras and meshes. The advanced-mode switch matches librealsense 2.54.2's source, but has not been tried on a real D415. |
| Magenta mask overlay, no-depth-only mask, fill small holes (new in 0.6.1) | 10 tests on made-up walls, a stand-in camera and a synthetic mesh with holes. Not yet tried on a real camera. |
| Settings per camera, Reset, camera badge (new in 0.6.0) | 8 tests, 4 running the whole window with stand-in cameras that are swapped. Not yet tried with two real cameras. |
| Optional ErrCode hook (new in 0.4.1) | Tried with stand-ins only, not with the real plugin. |
| Laser power option (new in 0.2.1) | Checked against a fake sensor only. What value 1 does on SR305 firmware is unconfirmed. |
| Recording infrared; opening .bag files; the optional AI mask; the GitHub workflows | Untested with real data. |
All screenshots here come from synthetic test data, not a real object. The Kinect one
uses a stand-in driver, not a real Kinect.
If something breaks on your camera, please [open an issue](../../issues/new/choose).
Kinect (0.3.0, experimental)
!The app showing a stand-in Kinect
Camera type at the top of the Camera panel switches between RealSense and Kinect.
Kinect support is untested on real hardware, its drivers have to be installed by hand, and
the sensor check, depth confidence and laser settings do not apply to it. The Kinect runs
in its own process, so a driver crash cannot close the app; it is restarted automatically
if it crashes, hangs or stops sending pictures.
Everything is in KINECT.md.
The look (0.3.0)
The window is dressed as a wood-panelled television: walnut cabinet, black bezel, a
rounded screen, and static on the screen while the camera is off. The static stops the
moment the first camera picture arrives, and a lamp under the screen shows whether the
camera is on standby or live.
Everything is drawn by the app; there are no picture files. The static is a few pictures
made once and swapped on a timer. In a headless test the whole app used about 4% of one
processor core while showing it.
Look (bottom of the right-hand panel) chooses Retro TV, Retro TV, still screen (no
movement) or Plain. It applies the next time the app starts. --plain on the command
line forces the plain look, and the app falls back to it by itself if the skin fails.
!Plain look
Using it
1. Plug the camera in. The live picture appears by itself (the app looks for a camera every
few seconds while the live view is showing). Point it at the subject; the live distance
guide shows the sweet spot.
2. START SCAN (green). In Handheld mode, move the camera slowly round the object; in
Turntable mode, keep the camera still and turn the object ([below](#handheld-or-turntable-new-in-090)). STOP when done.
Capture Frame takes single frames instead.
3. BUILD MESH. Choose Smooth surface (fuses depth images, recommended) or
Watertight (Poisson; fills unscanned gaps so it can be printed). While it builds,
the same button turns into CANCEL.
4. Save mesh… as STL/OBJ/PLY, in millimetres or metres.
Other controls: near/far range, depth confidence, laser power, average-when-still,
keep-only-the-subject, a CAD-style view cube, and cutting (next section) to remove
the table or split overlapping scans. While scanning, the STOP
button shows the elapsed time and the number of frames. Clear captured frames
asks first if it would throw away a mesh you have not saved.
Handheld or turntable (new in 0.9.0)
Pick the Scan mode in the Scan panel. Frames are cut out differently in each mode, so
changing it clears the frames captured so far (it asks first).
| Mode | You move | Best for |
|---|---|---|
| Handheld | the camera, slowly round the object | big or fixed things, faces |
| Turntable | the object, on a turntable or lazy Susan, a little between captures. The camera stays on a stand and must not move. | small objects; the most reliable |
Turntable mode in four steps:
1. Put the camera on a stand, 30–50 cm from the turntable, looking down at it a little.
2. Optional, but best: with nothing on the turntable, press Record empty turntable.
Everything that is there now (table, wall, the turntable itself) is left out of the scan.
Without it, the table and the turntable's top are found and removed instead.
3. For a plain or round object (a mug, a smooth figure, anything with little pattern),
press Save marker ring to print (PDF). Print it at 100% (the 50 mm bar must measure
50 mm), lay it flat on the turntable and put the object in the middle. The markers say
exactly how far the turntable turned.
4. START SCAN and turn the object slowly through a full turn, or Capture Frame every
10–20 degrees.
How it lines frames up: every frame is a turn about the same axis, so instead of six
unknowns per frame there is one. A step that doesn't fit the axis is re-checked. A full
turn is checked against the start, and the axis and every turn are then fine-tuned
together against all the frames that see the same side. The build report says what it
found, for example "Turntable: one axis fits the steps (0.4 mm typical); 24 frames over
345 degrees; full-turn check from 1 closure(s)". If the steps don't fit one axis (the
object slid, or the camera was knocked) it says so and aligns as a handheld scan instead.
Picture features (tick box, on by default): every step between frames is also worked
out from the colour picture, using ORB corners on a greyscale copy, lifted to 3D with the
depth. A shape match that the picture clearly contradicts is overruled. This is what stops
a round object being glued on at the wrong turn. Untick it to compare.
Slow PCs, live tracking, and what to expect (new in 0.10.0)
The Scan style box (Scan panel) chooses when the heavy work happens.
| Scan style | While you scan | After STOP | For |
|---|---|---|---|
| Stitch while scanning | Every capture is lined up as it comes. Handheld, the camera is also followed on the live picture (up to 10 frames a second), and a red banner says TRACKING LOST - move back slowly if it loses its way. | Build Mesh | a reasonably quick PC |
| Record now, stitch afterwards | Only the camera's frames are saved to disk (about 10 a second), which even a slow PC keeps up with. | Stitching starts by itself and shows how long is left. Then Build Mesh. | slower PCs, such as a 7th-gen Core i3 |
The first time it starts, the app times one tracking step on your PC (about a third of
a second). With 4 processor threads or fewer, or a slow step, it picks *Record now,
stitch afterwards*. You can change it at any time when not scanning.
On a 7th-gen i3, be ready for slow. It won't freeze or crash, but it takes a while.
- Stitching runs as a separate program with a memory limit. If it runs out of memory,
only that program stops, and it starts again on every 2nd frame (twice at most). The
recording stays safe on disk whatever happens. A recording cut short by a crash keeps
all but its last few frames.
- Expect minutes, not seconds. On a 2-core test machine, about as fast as a 7th-gen
i3, a 40-second handheld recording (about 120 frames) took about half a minute to
clean and track. Then lining up the 48 frames it kept took 2–4 minutes, and Build Mesh
takes longer again. A turntable scan is much quicker to line up. These are measured
on made-up scans, not timed on a real i3.
- While stitching, the status bar shows the progress and the minutes left. You can
leave it running.
Whichever style you choose, captures are now worked out away from the camera's own
thread. If the PC falls behind, a capture is skipped with a message rather than freezing
the live picture.
Speed profiles and the graphics card (new in 0.11.0)
The Speed and graphics card box (right-hand panel) is taken from STL2STEP. It sets how
hard Build Mesh and stitching work the computer.
| Profile | Alignments at once | Priority | Graphics card | Auto picks it for |
|---|---|---|---|---|
| Potato | 1 | lowest: the PC stays usable | no | under 4 cores or 12 GB, such as a 7th-gen i3 |
| Moderate | half the cores | below normal | no | most laptops |
| Extreme | every core | normal | yes, where it passed its test | 8+ cores and 16 GB |
!Speed and graphics card box
Be realistic about what it gains.
- Lining the frames up is over 90% of Build Mesh, and that is Open3D's ICP alignment.
- On a 7th-gen i3, Potato makes nothing faster. It keeps the computer usable while it
works.
- Alignments side by side give the same results. On the 2-core test machine they were
only about 10% faster; a PC with more cores should gain more, but that hasn't been
measured.
- The final polish is now about a quarter quicker, with the same results.
Graphics cards:
- Nvidia on Linux: the standard Open3D already contains Nvidia (CUDA) support, so
nothing extra is installed. Press Test the card; the card is only used if a real
alignment and depth fusion on it give the right answers. Otherwise the processor does the
work, as before.
- Nvidia on Windows: not used. Open3D's Windows graphics-card build is an experimental
preview that isn't on the normal download site.
- Apple M1–M5 Macs: not used. Open3D can't use Apple's graphics chip; Extreme uses all
the processor cores instead.
- AMD and Intel graphics: not used. Open3D supports Nvidia cards only.
- No real graphics card has been tried. The card's code was run on the processor
instead; see the write-up.
python3 scantastic.py --speed-check prints the same information and tests the card.
Scan target and compare (new in 0.9.0)
Save printable target (STL) writes a 70 x 70 mm test block, shown below. Each corner
has one feature:
- steps 2, 4, 6 and 8 mm high;
- a dome 30 mm across;
- grooves 1, 2 and 3 mm wide;
- a ramp.
An L-shaped notch on one side means it only fits one way round. Print it in a matt
colour, scan it on the turntable and build the mesh. Then Compare mesh with scan target
reports:
- the typical error and the error that 9 points in 10 stay within, in mm;
- how much of the top was covered;
- each step height as scanned.
The same can be run outside the app:
python scan_target.py target.stl # the STL
python scan_target.py --ring ring.pdf # the marker ring
python scan_target.py --compare scan.stl # compare a scan with the target
!Scan target
!Turntable mode
The camera on and off, and turning the picture (new in 0.5.0)
| Control | What it does |
|---|---|
| Turn camera off / Turn camera on (Camera panel) | Off stops the camera and keeps it off, also the next time the app starts, until you turn it on. The line under the button says what the camera is doing: live, waiting for one to be plugged in, or off. |
| Rotate (above the picture) | Turns the live picture a quarter turn clockwise each press, for a camera mounted on its side or upside down. The 3D model's default view and the sensor check's pictures turn with it. The scan data itself is not changed. Remembered. |
Unplug the camera and the app notices (at once on Linux, within about 8 seconds
elsewhere), says so, and starts the picture again when the camera is back. A camera that is
plugged in but will not start is reported once in the status line, with no dialog; press
Capture Frame to see the full reason. START SCAN and Capture Frame still start the camera
themselves, and turn it on if it was off.
A Kinect is looked for in the same way on Linux. On Windows and macOS there is no quick way
to look for one, so a Kinect starts when you press START SCAN or Capture Frame.
Settings for each camera, and which camera is running (new in 0.6.0)
Each kind of camera has its own settings. When a camera starts, the app puts that
camera's settings in the window, and anything you change is remembered for that camera
only. So a D415 and an SR305 can be swapped without retuning. Reset ... settings in
the Camera panel puts the starting values back for the camera in use. The line under it
lists what you have changed.
The coloured badge at the top of the Camera panel says which camera is running: blue for
an SR305 / SR300, orange for a D400, purple for a Kinect, grey for none. The model name is
also shown in that colour on the live picture and in the window title.
Starting values (best guesses; the reasons are in DESIGN_NOTES section 3):
| Setting | SR305 / SR300 | D400 (D415) | Kinect |
|---|---|---|---|
| Near / Far | 0.20 / 1.00 m | 0.25 / 1.00 m | 0.5 / 3.0 m |
| Depth confidence | Standard | (no such setting) | (no such setting) |
| Laser power | Maximum | Maximum | (no such setting) |
| Quality | 60 | 60 | 60 |
| Surface detail | Standard | Fine (1.0 mm grid) | Standard |
| Narrow band / 3+ frames | off / off | off / off | off / off |
| Final smoothing passes | 5 | 2 | 5 |
| Fill holes smaller than | off | 8 mm | off |
| Sensor-check mask: only no-depth patches | off | on | off |
| Only keep the subject / Average when still | on / on | on / on | on / on |
Black spots in the same place on the screen (0.6.1)
A black spot that stays put whatever you scan is one of two things, and the live depth
picture now tells them apart:
- Magenta: the sensor-check mask. You ran the sensor check and the app ignores those
pixels on purpose. Untick Ignore damaged sensor areas to see what the camera gives
there, or tick ...only patches with no depth to keep the merely noisy parts
(run the sensor check again once, to save that smaller mask).
- Black: the camera gives no depth there (a scratch, mark or smear on the window,
or a dark or shiny patch). Clean the window with a blower and a dry, soft cloth (no liquids).
Either way, move the object (or yourself) between frames. A spot at a fixed place on
the screen falls on a different part of a turning object in the next frame, so the
other frames fill it in. And Fill holes smaller than ... mm (Quality panel) closes
what is left in the finished mesh with flat patches. It starts at 8 mm for a D400.
D400 advanced mode and firmware (0.7.1)
Advanced mode. A D400 has a setting stored in the camera called "advanced mode".
Intel's driver only offers the High Accuracy preset and 0.1 mm depth steps while it is on,
and the ripple correction needs it too. The first time a D400 with it off starts, the app
asks whether it may switch it on. The camera restarts once, a few seconds, and it stays
on. The tick box "Let the app switch on a D400's advanced mode" in the Camera panel
changes your answer. Intel RealSense Viewer can switch it off again.
D400 firmware. The app uses Intel's driver 2.54.2. It has to: 2.55 and later dropped the
SR305. That driver is fine for a D415, because the depth is worked out inside the
camera, but Intel recommends D400 firmware 5.15.0.2 or later with it. The status line
says when a camera's firmware is older. The D415 tested here reports 5.11.10, from 2019.
It works. Updating is optional, done with Intel's tools rather than this app:
- Intel RealSense Viewer, under More, Update Firmware;
- or rs-fw-update.
Read the D400 firmware release notes first. Keep the camera plugged in and don't
interrupt the update.
D400 cameras such as the D415 (0.5.1)
Before 0.5.1 a D400 shared the SR305's settings, and scans looked coated in a thick soft
skin. Now a D400 gets its own:
- depth at 848x480 instead of 640x480 (sharper; still works from about 30 cm);
- 0.1 mm depth steps instead of 1 mm;
- Intel's ripple correction (A-factor 0.08), if the camera's advanced mode is on. If
it is off, the log says so. Intel RealSense Viewer can switch it on once and it stays on;
- a wider trim along object outlines, where stereo depth spills past the real edge;
- (0.5.2) the colour laid onto the depth, so the depth is never resampled;
- (0.5.2) 2 smoothing passes to start with instead of 5; (0.6.0) its own remembered settings.
The status line and the sensor check report say whether the ripple correction is on.
Scan at the close end of the guide, about 35 to 45 cm. If a white or shiny object still
looks blobby, try Laser Reduced. A sensor-check mask made before 0.5.1 is ignored on a
D400 (wrong resolution), so run the check again.
Cutting: point at where the cut goes (new in 0.4.0)
!A cut set on the model
The cut is set on the model itself, in the 3D view. The part that will be cut off turns
red before anything is changed.
1. Press Draw a cut (in the 3D view, or Draw the cut on the model in the Edit
panel) and drag a line across the model. The cut follows the line and goes straight
into the screen. Hold Shift for a level, upright or 15-degree line. Esc cancels.
2. Adjust it if needed: drag the yellow dot to move the cut, drag the red arrow to
turn it. The arrow points at the part that goes. Or press Redraw and draw the line
again.
3. Flip side if the wrong part is red. Apply cut when it looks right. Undo last
edit brings back both the mesh and the cut, so you can nudge it and apply again.
Three shortcuts, in the Edit panel:
| Button | What it does |
|---|---|
| Find the table / flat base | Finds the biggest flat area of the model and puts the cut just above it, so the table goes and the subject stays. It is a suggestion: check the red part first. |
| Top, Bottom, Left, Right, Near, Far | Cuts off that side of the model as you see it now. Turn the view first (the view cube snaps to a face) and these give exactly level or upright cuts. |
| How much | Slides the cut through the model, from nothing cut off to everything. |
"Cap the cut" (on by default) closes the cut with a flat face, which makes a solid you can
print; untick it to simply trim the surface. A scan seen from one side only is filled in
straight back to a flat back, just behind the deepest point of the part you keep.
This replaces the earlier orientation list, position slider and tilt joystick. A line drawn
on the model removes whichever part is the thinner slice; if you meant the other, Flip side.
Looking at the result: colours and background (0.2.2)
!Height colours in the 3D view
Above the 3D view, Colours chooses how the mesh is painted:
| Colours | Shows |
|---|---|
| Scan colours | The colours the camera saw. |
| Plain | Grey, shaded only. Best for judging the shape without the texture distracting. |
| Height (low - high) | Blue at the bottom to red at the top, with the range in millimetres and the highest and lowest points marked. |
| Relief (back - front) | The same map, front to back. Small bumps and dents stand out. |
| Coverage (rescan hints) | How many frames saw each part, so you know where to scan again. |
Background switches the 3D view between dark, grey, light, white, navy or a colour
you pick. Both choices are remembered in settings.json next to the script.
Sensor check: what kind of fault is it? (new in 0.2.1)
!Sensor check result
Sensor check (point at a wall)… looks at a plain, matt wall for about two
seconds and finds the parts of the view that misbehave, so scans can ignore them.
Since 0.2.1 it also says what kind of fault it found, because the cures differ:
- Flicker (noise): the reading jumps about from frame to frame. Left picture.
It cannot be subtracted; those pixels can only be trusted less.
- Steady offset: the reading is wrong by the same amount every frame. Right
picture (red = reads too far, blue = too near). An offset can in principle be subtracted.
- Missing depth: purple in both pictures.
It also reports how curved the camera sees the flat wall (calibration error, or a
wall that is not flat) and whether a suspicious ring is only smooth calibration
error. Every run saves two pictures, the two maps (.npz) and a text report in
sensor_check/, named by wall distance and laser setting, so runs can be compared.
Useful comparisons, each one a fresh run of the check:
| Change | If the pattern changes | If it stays the same |
|---|---|---|
| Laser power Maximum → Reduced | Glare or saturation | Calibration or the window |
| Wall at about 30, 40 and 60 cm | Glare or saturation | Calibration or optics |
| Camera turned 10–20° off square | Glare off the wall | The camera |
| Camera upside down or slid sideways | Stays with the wall: the wall is not flat | Stays with the image: the camera |
Which pixels are ignored is decided exactly as in 0.2.0. One thing the breakdown
shows that the ignore-mask misses: a large area with a steady offset (a third of
the view reading 4 mm off, in the tests) is not ignored, because the old rule
compares each pixel with the spread across the whole view. The report says so when it happens.
Surface detail options (new in 0.2.1)
Under Quality, for the Smooth surface method. The defaults give exactly the
surface earlier versions gave.
| Option | What it does |
|---|---|
| Surface detail | Grid size for fusing. Standard follows the Quality slider (2.5 mm at Low, about 1.5 mm in the middle, 1 mm at High). Fine / Finer / Finest fix it at 1.0 / 0.75 / 0.5 mm. |
| Narrow fusion band | Sharper, but may leave holes where depth is noisy. |
| Only surface seen in 3+ frames | Less noise, more holes. Needs 6 or more frames. |
| Final smoothing passes | 0 = sharpest, 5 = as before. |
Measured on a synthetic test object (a ball with 1 mm ripples, 40 frames, 1.5 mm
depth noise, subject isolated), with the camera positions known exactly:
| Setting | 6 mm ripples kept | 3 mm ripples kept | Fusing time |
|---|---|---|---|
| Standard, Quality in the middle (as before) | 64% | 48% | 0.7 s |
| Standard, smoothing 0 | 70% | 66% | 0.7 s |
| Fine 1.0 mm, smoothing 0 | 73% | 71% | 1.1 s |
| Fine 1.0 mm, narrow band, smoothing 0 | 77% | 73% | 1.1 s |
| Finest 0.5 mm, smoothing 0 | 76% | 75% | 5.0 s |
So these options help, modestly. How accurately the frames are lined up matters
far more. The same test with small errors added to every camera position:
| Error per frame | 6 mm ripples kept (Fine, smoothing 0) | 3 mm ripples kept |
|---|---|---|
| none | 73% | 71% |
| 0.1° and 0.3 mm | 71% | 63% |
| 0.25° and 0.5 mm | 65% | 46% |
| 0.5° and 1 mm | 48% | 7% |
Fine grids need more memory. If a scan would need too much, the app uses the
finest grid that fits and says so. Scanning only the subject ("Only keep the
subject in the middle") keeps the volume small.
Raw stream and clean-up
!Clean-up dialog
Tick Record every camera frame before scanning to keep the raw colour and depth
(and optionally infrared) on disk. Afterwards, Open recording and clean up…
replays a recording folder (or a RealSense .bag) through these passes, each optional:
- Depth gate: drop anything outside the near/far range.
- Remove the table: finds the flat supporting surface (RANSAC) and removes it and everything below.
- Edge-aware smoothing: smooths depth noise but stops at edges the colour picture shows.
- Track camera movement from the picture: matches features in infrared first, then colour, and lifts them to 3D using the depth. The resulting poses guide the mesh alignment: they seed the ICP, rescue frames ICP can't verify, and veto an ICP result that contradicts confident tracking.
- Compare neighbouring frames: re-projects neighbours into each frame, drops depth that disagrees (noise) and fills small holes.
- Small AI background mask (optional, off by default): needs pip install onnxruntime into rs_env and models/u2netp.onnx.
Then it loads the result as normal scan frames, ready for BUILD MESH. How each pass
works, and where it can go wrong, is in HOW_IT_WORKS.md.
!Quality and detail options
<!-- Hardware photos: add docs/images/unit.jpg, unit-2.jpg and real-feed.jpg and
they will appear on the project web page automatically. -->
Notes, research and tools
| Where | What |
|---|---|
| DESIGN_NOTES.md | What was looked into, what was measured, what was decided and why, what is untested, what to build next. Start here. |
| docs/research | The full research report on soft scans and damaged sensors (68 sources), the working notes behind it, a printable PDF in plain English, and the Kinect driver bug report. |
| HOW_IT_WORKS.md | What the app does, step by step, written from the code. |
| PROJECT_NOTES.md | Short hand-over notes: where things stand and what is open. |
| tools | detail_test.py repeats the surface-detail measurements; make_screenshots.py retakes every picture here from made-up data; make_research_pdf.py rebuilds the PDF; bench/ is the stitching benchmark (python tools/bench/bench.py --mode rotary --seeds 0-1). |
| scan_target.py | The printable scan target, its compare report, and the turntable marker ring. |
---
Source code: The-Dorkknight/scantastic on GitHub
Blip
WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN — proof of concept, v0.2.2-wip
Turn a tiny radar chip and an old phone into a people-spotting radar 📡
Ever wanted to know who is walking about, and how far away they are, without a camera? Blip does it with a tiny radar chip and a spare phone. The chip sends out invisible radio waves and listens for the echoes. When someone moves, the echo changes, and Blip works out where they are.
The phone is the screen. Blip makes its own Wi-Fi network; you join it, open a web page, and a glowing green radar scope appears, like something from a submarine film. Up to three people show up as dots with their distance, direction and speed. No app to install, no internet needed, no cloud, no camera.
How it works, in three steps
1. Plug a little ESP32 board into a radar chip (the Ai-Thinker RD-03D) and power it from USB.
2. Join the Wi-Fi network called Blip-Radar on any old phone, tablet or laptop.
3. Open the page and watch the dots move. Walk about and see yourself on the scope!
Good things to know
- It only sees things that move. Someone sitting very still fades from the scope.
- It also bounces off big metal things such as fridges, so a small room can look busy.
- A tiny optional screen (an OLED) can sit on the board and show the same picture. Blip finds it by itself when it starts.
- You can switch between tracking the one nearest person or up to three.
It is a slimmed-down take on Stevee87's Arduino-ESP32-Radarproject, which pairs the same radar with a XIAO ESP32-S3 and an Arduino GIGA R1 + display shield. The drawing is the easy part; a phone already does it.
> Required Notice: Copyright Matthew Armstrong (github.com/The-Dorkknight).
> Licensed under the PolyForm Noncommercial License 1.0.0 — source-available, free for non-commercial use. Provided as-is with no warranty and no liability. Not a medical device. Radar can see motion through thin walls: respect other people's privacy and the 24 GHz rules where you live.
Project started 2026-11-05 10:24.
📘 The whole manual and research notes as one PDF: docs/Blip-manual.pdf (also attached to every release).
<p align="center">
<img src="raw.githubusercontent.com" alt="Blip radar scope on a phone" width="260" style="height:auto">
</p>
<p align="center"><i>Phone screenshot from the simulator (tools/sim_radar.py).</i></p>
Bonus experiment: the Stetho add-on (parked)
The idea: use a second, very cheap radar-style module (a £3 CDM324 or HB100 Doppler sensor) as a stethoscope that listens to a heartbeat from a distance. A modded MAX4466 microphone board boosts the signal, and the ESP32 cleans up the sound (ducks knocks, lifts heart, lung and throat sounds, cuts hiss) and plays it live to the phone, to 3.5 mm earphones, or to a small speaker.
> Status: abandoned, but kept as an optional install. The radar and phone scope are the project; the stethoscope is parked. The firmware, page and tests are still in the repo and still build, and you can switch it on in Settings, but nobody is working on it. Why, in the author's words: "Needing to build an ultra-low-noise, ultra-high-gain, fast-slew-rate instrumentation amplifier is just too much work for a 'fun' 30-minute project, but I encourage anyone gifted enough with analogue, or mad enough, to carry on my research 😉" Findings and test recordings are in docs/STETHO_SIGNAL_NOTES.md.
<p align="center">
<img src="raw.githubusercontent.com" alt="Stetho screen" width="260" style="height:auto">
</p>
<p align="center"><i>Simulator screenshot. The real thing never got past the noise floor.</i></p>
What exists vs what doesn't
| Part | State |
|---|---|
| RD-03D frame parser (sign bits, resync, ACK tolerance) | Done; unit-tested natively in C++ and Python (tests/) |
| Single/multi-target mode command | Fixed in v0.2.1: now wrapped in enable/end-config like the original project (earlier versions probably did nothing) |
| "Smart" target filter (own track ids, smoothing, hides flickers, wall reflections, fans) | Experimental, opt-in. Native tests on synthetic scenes pass; not tried in a real room |
| Auto-sleep + optional power switches for the RD-03D and the CDM324 | Written, compiles; not tried on hardware |
| Phone web UI: scope, targets table, tracker ping, settings, about | Done; tested in Chromium against the simulator |
| Flasher page the launcher opens (Quick flash of bundled firmware, or build from source; serial output; error tips) | Done; tested end to end with stand-ins for esptool and PlatformIO (tests/test_flasher.py); the bundled images and the esptool command were checked with the real esptool (image_info: valid); not yet used on a real board |
| Wi-Fi hotspot + captive portal + WebSocket/HTTP API | Running on the author's bench (Nov 2026): the page loads and shows live targets |
| ESP32-C3 Super Mini and Waveshare ESP32-S3-Pico builds | Compile cleanly (pioarduino, Arduino-ESP32 3.3.12); not yet flashed |
| OLED mirror (0.91" 128×32 / 0.96" 128×64 SSD1306) | Works on the author's bench; found automatically at boot. The previews below are rendered by the firmware's own drawing code on a PC |
| Stetho audio clean-up on the ESP32 (bump gate, heart/lungs/voice presets, noise suppression, AGC) | Done in fixed point; native test on a synthetic scene passes (knocks −38 dB vs heart sounds, hiss −11 dB) |
| Live low-latency audio to the phone, chest-motion trace, heart/breath estimates | Done; tested in Chromium against the simulator (54–83 ms delay there) |
| Earphone (delta-sigma) and I2S amp outputs on the node | Written, compiles; not heard yet |
| CDM324 + modded MAX4466 front end | Built and tried on a bench (Nov 2026): static fixed by supply caps, but the heartbeat sits at the noise floor even at 2 cm. Abandoned: it needs a custom ultra-low-noise, high-gain instrumentation amplifier (and ideally an I/Q module) |
| Making the RD-03D itself into a Doppler stethoscope | Not possible through its UART — see DESIGN_NOTES.md |
| RD-03D tracking in a real room | Tracks up to 3 targets, and also big metal objects as you walk towards them; noisy in a small house, outdoor test still to do |
| Enclosure | None yet |
Bill of materials
| Qty | Part | Notes |
|---|---|---|
| 1 | ESP32-C3 Super Mini or Waveshare ESP32-S3-Pico | Either; both envs in firmware/platformio.ini |
| 1 | Ai-Thinker RD-03D — or an HLK-LD2450 (see Radar options) | 5 V, ≥200 mA, UART 256000 baud, 3.3 V logic |
| 1 | Old phone / tablet / laptop with a browser | The display |
| 0–1 | SSD1306 I2C OLED, 0.91" 128×32 or 0.96" 128×64 | Optional second display |
| 0–1 | CDM324 (24 GHz) or HB100 (10.5 GHz) CW Doppler module | Optional "Stetho"; HB100 if you want to run it alongside the RD-03D (see below) |
| 0–2 | MAX4466 electret-mic amp board (Adafruit 1063 / GY-MAX4466) | The Stetho amplifier, modded: hardware/max4466-mod.md |
| 0–1 | 470 Ω, 100 nF, 220 µF, 3.5 mm socket | Earphone output, hardware/audio-out.md |
| 0–1 | MAX98357A I2S amp board + 4–8 Ω speaker | Speaker output |
| — | USB-C cable / 5 V supply, wire | The C3's 5V pin can feed the radar for bench tests |
Wiring
!Wiring, ESP32-C3 Super Mini
!Wiring, Waveshare ESP32-S3-Pico
| Signal | C3 Super Mini | S3-Pico | Note |
|---|---|---|---|
| Radar TX → ESP RX | GPIO20 | GPIO12 | UART1, 256000 8N1 |
| Radar RX ← ESP TX | GPIO21 | GPIO11 | only used to send the single/multi-target command |
| OLED SDA / SCL | GPIO6 / GPIO7 | GPIO17 / GPIO18 | I2C 0x3C |
| Stetho: MAX4466 OUT | GPIO1 (ADC1) | GPIO7 (ADC1) | MAX4466 powered from 3V3 |
| Earphones (delta-sigma) | GPIO10 | GPIO16 | via 470 Ω / 100 nF / 220 µF |
| I2S amp BCLK / LRC / DIN | GPIO3 / 4 / 5 | GPIO13 / 14 / 15 | MAX98357A |
| Radar 5V / GND | 5V / GND | VBUS / GND | never 3V3 |
Pin numbers live in one place, firmware/platformio.ini; the diagrams are drawn from it.
Stetho front end: CDM324 → modded MAX4466
!CDM324 into a modded MAX4466 board
> ⚠ DC warning. When you desolder the mic capsule and wire the radar's IF pin onto its pads, also remove the mic bias resistor, or put a 10–47 µF DC-blocking cap in series with the IF lead. Otherwise ~1.5 mA of DC from VCC is pushed into the CDM324's mixer diode. Power the MAX4466 from 3V3, never 5 V. Full steps: hardware/max4466-mod.md.
> RD-03D + CDM324 at the same time? They share the 24 GHz band. The RD-03D's sweep passes right over the CDM324's frequency, so expect a buzz in the Stetho audio and possibly a noisier RD-03D. Use an HB100 (10.5 GHz) for the Stetho, or fit a 5 V switch on the radar and choose Radar off while listening (PIN_RADAR_PWR). Details in DESIGN_NOTES.md §11.5.
One launcher: flash it, or try it first (double-click)
1. Unzip, then double-click Blip-Linux.sh (choose Run), Blip-Windows.bat or Blip-Mac.command (first time on a Mac: right-click → Open).
2. Your browser opens the Blip Flasher at http://127.0.0.1:8080/ (the red page). Only Python 3 is needed to open it.
- Want to look around before you have hardware? The small Radar simulator › button (top right) opens the normal Blip page at /sim, with three pretend people wandering about and a synthetic Stetho signal; its ⚡ Flasher button brings you back. Start the launcher with --lan to open the simulator from your phone too (the terminal prints the address).
3. To flash a real board: plug the board in with a USB data cable, pick the board (C3 Super Mini / S3-Pico), the radar (RD-03D / LD2450) and how to flash, pick the port (or leave Auto-detect), press ⚡ Flash firmware.
- Quick flash (default, recommended): writes the firmware that ships in firmware/prebuilt/. Nothing is hidden: the page shows the file, version, build date, size and full SHA-256, checks the file against manifest.json before writing, says whether it was built from exactly the source in your folder, and shows the exact esptool command. The first run installs only esptool into .venv (about 40 MB). No Git, no compiler.
- Build from source: compiles your folder with PlatformIO so your own changes go in. The first build downloads the ESP32 toolchain (a few GB; needs the internet and Git; 5–15 minutes), later builds are quick.
- The steps light up as it goes (Quick: Firmware → Flash tool → Upload → Boot; Source: Prepare → PlatformIO → Build → Upload → Boot) with a progress bar for the upload and the full log underneath (Copy puts it on the clipboard for a bug report).
- If something fails, a tip explains the usual cause: serial-port permission on Linux, the board not in flashing mode (hold BOOT, tap RESET), no board or several boards found, no internet on the first run, Git missing, a port held by another program, your source newer than the bundled firmware.
- Afterwards it shows the board's serial output (no terminal needed). Cancel stops any step.
- Rather use another tool? Any ESP32 flasher can write firmware/prebuilt/blip-<env>-full.bin at address 0x0 (they are also attached to each GitHub release).
4. Wire the radar as above and power up. The LED on the C3 blinks slowly until frames arrive, then fast.
5. On the phone: join Wi-Fi Blip-Radar, password blipblip. The captive portal should open the scope; if not, browse to http://192.168.4.1/. It is the same green page as the simulator.
!Blip Flasher
The flasher only answers this computer (127.0.0.1 / localhost): starting a flash needs a per-run token only the page has, and the board, radar and port are checked against fixed lists before anything runs. --no-flash hides it entirely.
Prefer the terminal? cd firmware && pio run -e c3-supermini -t upload (envs: c3-supermini, s3-pico, c3-supermini-ld2450, s3-pico-ld2450). After editing web/index.html run python3 tools/embed_web.py (the Flash tab does this for you).
Using it
| Screen | What it does |
|---|---|
| !Scope | Scope — ±60° sector, rings every 2 m to 8 m, one coloured blip per tracked person with distance and radial speed. Trails fade over 4 s. Tracker ping is the original project's buzzer, done in the phone's speaker: faster and higher as the nearest person approaches. Mirror L/R flips the picture if you mount the radar the other way round. With the Smart filter on, Show filtered draws what it is hiding as dashed rings (ghost / clutter). |
| !Targets | Targets — the numbers behind the blips plus the raw JSON, handy when checking orientation. |
| !Stetho | Stetho — the optional CW Doppler channel. Presets: Heart (S1/S2 heart sounds, 20–150 Hz), Lungs (breath hiss), Voice (throat/larynx buzz), Wide, Raw (plain Doppler warble). Listen on phone plays it live; Delay shows how far behind real time you are. Knocks are ducked and limited (red in the trace). Beat lock quietens the gaps between beats once a rhythm is found; Record 10 s → WAV saves a recording for tools/analyze_wav.py; Experiments has ADC averaging and the burst blanker (see docs/STETHO_SIGNAL_NOTES.md). Not a medical device. |
| !Chest motion | Chest motion view — the 100 Hz motion trace with heart-rate and breathing rates from the pattern trackers (a ? means only roughly steady); Beat thumps adds a synthetic thump on each detected beat. |
| !Clean-up | Clean-up on the node — noise suppression, bump rejection, AGC or manual gain; Sound out of the node — earphones or I2S amp, with its own volume. |
| !Settings | Settings — single/multi target mode (also on the Radar page as Track 1 / Track 3), Target filter (Raw / Smart, experimental) with Forget learned clutter, Auto-sleep, OLED (Auto-detect, or a fixed size), Stetho on/off, radar-off-while-listening, hotspot name and password (reboots). |
| !About | About — version, build date, board, pin map and counters. |
| !Flash | Flash (simulator on a PC only) — pick board, radar, Quick flash or Build from source, and port; see exactly what will be written; watch the board boot. |
OLED mirror. Each person is a circle with their distance inside: big digit = metres, small raised digit = tenths, so "1⁹" = 1.9 m. The nearest person is solid. There's no status row, so the scope fills the panel. ◆ top-left = Smart filter on; Wi-Fi icon + number top-right = phones connected; the IP shows bottom-left only until a phone joins. These are exact renders of the firmware's drawing code, not photos:
!OLED 128x64 !OLED 128x64, no phone yet
!OLED 128x32
How it works
Short version: the ESP32 parses 30-byte frames from the radar, keeps the latest three targets, and pushes them as JSON over a WebSocket 20 times a second to whoever is on the hotspot; the browser draws the scope on a canvas. The long version, including the frame format, is in HOW_IT_WORKS.md. The research — radar physics, why the RD-03D can't be a stethoscope and what can, pin choices — is in DESIGN_NOTES.md.
Radar options
Blip was written for the Ai-Thinker RD-03D (1.25 mm 4-pin socket, 8 m, up to 3 targets). The HLK-LD2450 (Hi-Link, 24 GHz, about 6 m, up to 3 targets with X/Y position) is supported too:
- It sends the same 30-byte frame (AA FF 03 00, three 8-byte slots, 55 CC), so the same parser reads it.
- It has no RD-03D configuration commands, so Blip skips the mode command. Single (nearest) is picked in firmware instead.
- Use the c3-supermini-ld2450 or s3-pico-ld2450 build environment (or add -DRADAR_LD2450=1). /api/status reports "model":"ld2450" while it is running.
- Its pins are on a 2.54 mm header, so jumper wires work. Check the labels on the module: its TX goes to the board's RX pin, and its RX to the board's TX.
- Weaker than the RD-03D on people who sit very still (the vendor notes this beyond about 2 m), and range is about 6 m.
- Still 24 GHz, so it clashes with a CDM324 in the same way. Use an HB100 for Stetho, or the radar power switch.
- Not tested on hardware yet. Check the angle direction on the Scope first (Mirror L/R in Settings if left and right are swapped).
Repository map
firmware/ PlatformIO project (src/main.cpp, include/rd03d.h, tracker.h, audio_dsp.h, stetho.h, oled.h, oled_draw.h, web_ui.h)
firmware/prebuilt/ bundled whole-chip images for the four builds + manifest.json (checksums, version, source hash)
web/index.html the phone UI (single file; embedded gzipped into the firmware)
web/flasher.html the flasher (served by the PC tool only; never in the firmware)
web/flash_home.html the red home page the launcher opens, with the flasher inlined
tools/ sim_radar.py, flasher.py, serial_tail.py, make_prebuilt.py, make_pdf.py, embed_web.py, draw_illustrations.py, rd03d_py.py, tracker_py.py
tests/ native C++ tests (parser, audio DSP, tracker, OLED render), Python parser + tracker cross-check, flasher (with fake_pio.py), launcher test
hardware/ wiring, MAX4466 mod (with the DC warning), earphone / I2S amp outputs
examples/ synthetic RD-03D frames for replay; dsp_before.wav / dsp_after.wav
docs/ GitHub Pages site + images + Blip-manual.pdf (built by tools/make_pdf.py)
---
Source code: The-Dorkknight/blip-radar on GitHub
Bat Tree-Bar Proe
!The Bat Tree-Bar Saloon
WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN · version 0.2.0-wip · source-available · non-commercial
Battery percentage and time left at a glance, with a click for the details: charge/discharge current, power, voltage and battery health. In the spirit of BatteryBar, built to run on Windows 11 and Linux (and, experimentally, macOS).
> Licence and no warranty. Source-available under the PolyForm Noncommercial License 1.0.0: free to use, change and share for non-commercial purposes; commercial use needs separate permission. Provided as is, with no warranty and no liability. This is not legal advice. Bat Tree-Bar Proe only reads your battery; it never changes a setting.
📘 The whole manual and research notes as one PDF: docs/BatTreeBarProe-manual.pdf · Changelog · Build history · How it works · Design notes
A tribute to BatteryBar
The name is a pun on BatteryBar Pro, the Windows taskbar battery meter made by Osiris Development (osirisdevelopment.com). It showed the battery level and the time left or time to full right on the taskbar, with a Pro version adding graphs, warnings and more. That is the idea this project follows, rebuilt from scratch for Windows 11 and Linux (the author reports the original does not run there). This project is not affiliated with Osiris Development, shares no code with BatteryBar and is not a substitute for it; if BatteryBar still works for you, please go and use the original.
Project started 2026-11-11 11:01. Renamed from "ChargeGlance" the same day, before any public release.
!The bar while charging
What it looks like
A tiny always-on-top bar shows the battery icon, the percentage and the time left (or time until full). Click it and the details open. Drag it anywhere; it remembers where you left it. Right-click for the menu.
| On battery | Charging |
|---|---|
| !popup on battery | !popup charging |
These screenshots use the built-in simulated battery (--demo), because they were taken in a sandbox with no battery. The layout is the real one.
Using it
| You do | You get |
|---|---|
| Look at the bar | 73% 4h 24m on battery; 64% 34m (blue icon with a bolt) while charging; 100% full when full; 80% on AC when plugged in but not charging |
| Click the bar | Popup: charge or discharge current, power, voltage, energy now/full, health (full-charge capacity vs new), cycle count, temperature, mains status, a 30-minute power graph. Click again or press Esc to close |
| Drag the bar | Moves it; position is saved |
| Right-click the bar | Details, Start at login, Always on top, Allow over the taskbar (experimental), Move to bottom right, Quit |
The popup says in brackets where the time estimate came from: rate (energy left divided by smoothed power), trend (percent slope over the last few minutes) or os (the number your operating system reports).
Command line
python3 src/main.py --version
python3 src/main.py --once # one reading as JSON: paste this in bug reports
python3 src/main.py --text # no window, one line every 5 s
python3 src/main.py --demo # simulated battery (also: --demo charging, --demo full)
python3 src/main.py --autostart on|off|status # start at login
python3 src/main.py --force # start even if it thinks a copy is running
Settings and a small log live in ~/.config/bat-tree-bar-proe/ (Linux), %APPDATA%\Bat Tree-Bar Proe\ (Windows) or ~/Library/Application Support/Bat Tree-Bar Proe/ (Mac).
What works, what does not
| | Linux | Windows 11 | macOS |
|---|---|---|---|
| Code written | yes | yes | yes |
| Reading logic unit-tested | yes, with fake battery folders | parser only, on a hand-written sample | parser only, on a hand-written sample |
| Run on a real battery | not yet (built in a sandbox with no battery) | not yet | not yet |
| Window runs | yes (Xvfb, simulated battery) | not run | not run |
| Graphical installer / uninstaller | yes (Xvfb, into a temp folder) | code written, not run (Start Menu shortcuts, Run key, Apps list entry) | code written, not run (LaunchAgent, app folder) |
| Fuzz and edge-case tests (garbage readings, suspend, clock jumps, corrupt settings, HiDPI) | yes | parser only | parser only |
Project layout
src/main.py window and command line · src/battery_source.py Linux, Windows, macOS readers · src/estimator.py time estimates · tests/ unit tests · tools/ screenshot rig, PDF and history scripts.
Run the tests: python3 -m unittest discover -s tests -v
Created by Matthew Armstrong (The-Dorkknight).
---
Source code: The-Dorkknight/bat-tree-bar-proe on GitHub
Mentions
Icy Ewe: 3D scanning on the cheap with a scratched depth camera and a slow laptop Second-hand depth cameras (an Intel RealSense SR305, the D415 hiding inside a Prowise MOVE 3in1) see depth 30 times a second for the price of a takeaway. Turning one into a 3D scanner is easy right up to the point where you line the frames up. Then the object grows a second nose. I'm working on about 50 projects at once, so I don't have the time or brain capacity for humour; it cuts into my four hours of sleep-eating time (efficiency). So, straight to it, apart from the title: Icy Ewe (say it out loud) is the write-up of how my app, Scantastic, keeps a scan together on bad cameras and slow computers: - Picture features check every step the 3D shape suggests, and veto it when the shape is fooling itself. - Loop closures can't lie: one the pictures can't confirm may only move a frame as far as the chain could really have drifted. On a plain test blob, 40 of 42 closures had been wrong. - Turntable mode holds every frame to one fitted axis; a printed marker ring is optional. - TRACKING LOST tells you while you can still do something about it. - Slow PCs record now and stitch afterwards, in a separate process that just tries again on fewer frames if it runs out of memory. - Speed profiles, side-by-side alignment with identical answers, and a graphics card that has to pass a test first. - A sensor check that maps where your camera's window is scratched. The honest bit: all the measured results come from made-up scans with known answers, and the new methods haven't been through a real camera yet. There's a test plan in section 8. If you have one of these cameras, please break it and tell me what happened. It's also a defensive publication: section 9 dedicates the methods and their variations to the public, so they stay free for hobbyists. Paper: The-Dorkknight/icy-ewe · App: The-Dorkknight/scantastic --- The paper --- title: "Icy Ewe" subtitle: "3D scanning on the cheap: turning a scratched, second-hand depth camera and a slow laptop into a 3D scanner that doesn't lose the plot. A hobbyist's field guide and a defensive publication." author: "Matthew Armstrong (The-Dorkknight)" date: "Version 1.1, 13 November 2026 (first published as \"Depth Perception\", 2 November 2026)" --- !"Icy Ewe", the cover art and the title of this paper: a sheep in a parka points a scanner at an icy rune stone. Say it out loud: icy ewe sounds like "I see you", which is a depth camera's whole job, and this one is doing it on the cheap, in the cold, with second-hand kit. (The ewe is wearing glasses because the camera's window is scratched.) !A real scan on real hardware. A face, scanned with the depth camera inside a Prowise MOVE 3in1 (an Intel RealSense D415) and Scantastic 0.5.1 on 11 October 2026: 31 of 32 frames merged. Its owner called it "a lot better, still gloopy". Most of this paper is about what happened next. The short version - The goal: a free desktop app that turns a cheap depth camera into a tabletop 3D scanner. The cameras are an Intel RealSense SR305 and the D415 inside a Prowise MOVE 3in1, both second-hand, one with a scratched window. The computer is anything down to a 7th-generation Core i3 with no graphics card. The app is called Scantastic. - The hard part isn't the camera, it's lining the frames up. A scan is dozens of snapshots taken from different places. Put one snapshot a few degrees out and the object grows a second nose. Over 90% of the time a build takes is spent lining frames up. - What this paper describes (in enough detail to rebuild it): - picture features (the patterns on the object and the room) used to check every step the 3D shape suggests; - a rule that only lets a loop closure move a frame as far as the chain could really have drifted; - a turntable mode that holds every frame to one fitted axis, with an optional printed marker ring; - live tracking that says "TRACKING LOST" before you waste a scan; - a "record now, stitch afterwards" style for slow PCs, where the slow part runs in its own process with a memory budget and simply tries again on fewer frames if it runs out; - speed profiles, alignments side by side in helper processes, and an exactly-the-same-answer shortcut for the final polish; - a sensor check that points the camera at a wall and maps where the window is scratched. - How well it works: on made-up scans with known answers, the version before this work failed every handheld and turntable scan. Now 0 of 40 turntable scans fail, and 1 of 20 held-out handheld scans does. No real camera has been through the new methods yet. Section 8 is a test plan. - Why a paper: it's a defensive publication. Section 9 describes the methods and many variations of them and dedicates them to the public, so that they are prior art and nobody can easily patent them and charge hobbyists for them later. 1. Why this exists Proper 3D scanners cost hundreds of pounds. Second-hand depth cameras turn up in odd places: the RealSense SR305 was sold for face login and gesture control, and a D415 sits inside a classroom document camera (the Prowise MOVE 3in1). They see depth, 30 times a second, for the price of a takeaway. The catch is everything else: - The software that came with them was made for faces and gestures, not scanning. Intel's own SDK is a toolbox, not a scanner. - The cameras are noisy. One of them has a scratched window that makes part of the view flicker. - The computer it has to run on is a 7th-gen i3 laptop: 2 cores, 4 threads, 8 GB, no graphics card worth the name. - The existing free scanning software that does this well (SLAM systems such as ORB-SLAM3) is under the GPL. Scantastic is under a noncommercial licence (free to use, not to sell), and the two licences can't be mixed (section 3). I'm working on about 50 programming projects at the same time, so I don't have the time or the brain capacity for humour. Each joke cuts into my four hours of sleep-eating time (efficiency). This paper will therefore keep the jokes to a minimum and the pictures to a maximum. !The first live picture, 1 October 2026: the colour view and, beside it, the depth the camera sees, with a "nothing in the middle of the view" warning. Everything after this started here. 2. How a depth-camera scanner works, in two minutes A depth camera gives you a picture where each pixel says how far away that bit of the world is, as well as what colour it is. One such picture is a frame: a patch of 3D surface seen from one side. To scan a whole object you take frames from all round it (moving the camera, or turning the object), then: 1. Clean each frame. Throw away the unreliable pixels: the "flying pixels" along outlines, readings too near or too far, and the room behind the object. 2. Line the frames up. Work out where the camera was for each frame, so all the patches land in the same place. This is the hard part. 3. Fuse them. Every frame "votes" on where the surface is. The noise averages out and one smooth surface is left. 4. Save a mesh (STL, OBJ or PLY) for a slicer, Blender or FreeCAD. !The whole pipeline. The lining-up stages (purple, red, teal) are where almost all of the time goes, and where almost all of the clever bits in this paper live. Lining up, in one paragraph. The standard tool is ICP (Iterative Closest Point): slide one frame over another until each point sits as close as possible to the other frame's surface. It's excellent when the frames start close together, and it's fooled by smooth or symmetric shapes. A ball fits a ball in any orientation. A plain box fits itself four ways round. You chain frame 1 to 2, 2 to 3 and so on, then add loop closures (frame 20 also overlaps frame 1: tie them together) and let a pose graph spread out the leftover error. Each wrong link in that chain is a doubled surface in the final model. !Where the time goes, measured on one made-up 24-frame handheld scan (Scantastic 0.11.0, a 2-core computer). Lining up is 111 seconds; making the mesh is 16. 3. What already exists This is a well-studied problem. What follows is a hobbyist's search, not a professional one, and not legal advice. | What | What it does | Why Scantastic didn't just use it | |---|---|---| | KinectFusion (Newcombe et al., 2011) [1] | Live tracking against a fused volume, on a graphics card | Needs a GPU; the volume is the depth fusion Scantastic uses after lining up | | ElasticFusion, BundleFusion and similar [2] | Dense live reconstruction with loop closure | GPU-only; research or non-commercial licences | | ORB-SLAM3 [3] | Feature-based SLAM: keyframes, relocalisation, loop closing | GPLv3, which can't be combined with a noncommercial licence. Its authors offer a paid commercial licence | | Open3D's reconstruction system (Choi, Zhou, Koltun, 2015) [4], colored ICP (Park et al., 2017) [5] | Fragments, pose graphs, loop closures checked by geometry; ICP that uses colour as well as shape | Used: Open3D (MIT licence) is the engine underneath. The checks in section 4 are built on top of it | | Visual-plus-geometric loop-closure checks (e.g. Aalto, ICIP 2016) [6] | Accept a loop closure only if image features and shape agree | Same family of idea as section 4.5; the details differ | | Commercial turntable scanners and photogrammetry rigs | Turntables, often with printed marker mats, to know each turn | Closed software; the marker idea itself is old and well known | | Patents found with titles close to this work | e.g. scanning an object turned in the hand (US 9,639,943 B1) [7]; power-efficient depth sensing for live reconstruction (US 9,443,350 B2) [8]; turntable scanner calibration (US 2003/0202691) [9] | Not assessed. Listed so readers can look. Nothing here is a claim about what they cover | The gap Scantastic fills is not a new algorithm. It's a set of plain, checkable rules that make standard tools (ICP, ORB features, pose graphs, TSDF fusion) behave on bad cameras and slow computers, in a program anyone can run by double-clicking. Section 9 writes those rules down as prior art. 4. The method, in enough detail to rebuild it All numbers are Scantastic's defaults (0.9.0 to 0.11.0). Distances are in metres at the camera unless they say otherwise. 4.1 Capturing a clean frame - Depth confidence can be set stricter for a worn or scratched window ("Strict (worn / scratched glass)"). - Edge trim. Pixels next to a sudden depth jump are dropped: 2 pixels on the SR305, 5 on the D400s, whose outlines are softer. - Cut out the subject (on by default). Keep the surface nearest the camera in the middle of the view, plus everything joined to it without a depth jump, within a slab of depth. The room goes. Why: without this, a still room dominates the alignment. Turn yourself in front of a fixed camera and the room "doesn't move", so the frames get lined up to the room and the face comes out doubled. (This is the "second nose" in section 6.) - Average when still. If the camera has hardly moved (under 1 pixel of shift and 1.5 mm of depth change), up to 5 frames are averaged into one capture, pixel by pixel. A pixel from an earlier frame is only used where it agrees. - Speed hints on the live picture: "Steady", "Moving quickly" (over 150 pixels a second at 640 wide) and "Too fast - slow down" (over 350). Coded-light cameras smear when you rush them. - Distance colours. The live depth picture is green in the best band (30 to 50 cm for the SR305, 35 to 65 cm for the D400s) and fades to red outside it. 4.2 Picture features: a second opinion on every step The 3D shape can't tell a ball from a rotated ball, but the pattern on it can. So every frame also gets: - up to 1,500 ORB keypoints (corners in the picture), found on a contrast-boosted greyscale copy (CLAHE); - keypoints kept only where there's depth (in turntable mode, also at least 6 pixels inside the depth outline: outline points sit half on the still background and say "nothing moved"); - each keypoint lifted into 3D with its depth. For two frames, keypoints are matched with Lowe's ratio test at 0.9 (0.8 kept too few right matches on plain objects), then a RANSAC rigid fit: the 3D motion that the most matches agree with, to within 6 mm. That gives a camera move with a confidence that rises from 0 at 12 agreeing matches to 1.0 at 52. That estimate is the second opinion. It's used three ways: 1. As one more starting guess for ICP. 2. As a veto: if the pictures are confident (0.5 or more) and ICP's answer is more than 2.5° or 12 mm away from theirs, ICP is wrong (a smooth surface fitting itself in the wrong place), and the frame is placed where the pictures say, then fine-tuned from there. 3. As a vote in loop closures (section 4.5). 4.3 Chaining frames, with guards Each new frame is aligned to the last frame that worked: - Starting guesses: the tracker's or pictures' guess (if any), "the same move as last time", and "no move". ICP (colour ICP, matching within 8.7 mm at the default quality) runs from each; the one with the best two-way overlap wins. Two-way means checking that frame A's points find frame B's surface and B's find A's: a frame full of noise, or of the whole room, finds something near almost every point one way, but not the other way round. - If that's weak (under 60% overlap), the slower feature-based global alignment (FPFH + RANSAC) is tried too. - If it's suspicious (overlap under 60%, or the surfaces sit more than 1.6 times further apart than usual) and the pictures don't vouch for the step, the frame is also tried against 6 earlier frames spread across the scan. The closest fit wins. This is how a quick swing back to the start re-attaches there. - If nothing fits but the pictures are sure, the picture estimate is used and fine-tuned. - A frame that fits nothing (under 35% overlap) is skipped, not glued on somewhere wrong. 4.4 The room check, for plain objects A plain white box or mug gives the pictures almost nothing to match. But the room behind it doesn't move. So in handheld mode, each frame also keeps a thinned (6 mm) copy of the whole view, before the subject was cut out. When the pictures can't vouch for a step: - the two whole-room views are aligned coarse to fine (30, 15, then 8 mm), from each starting guess; - a fit counts only with at least 60% overlap and under 4 mm average error; - tables and walls are flat and slide over each other, so among the fits that pass, the one most picture matches agree with wins; - if the room says the object's own fit is more than 2.5° or 12 mm out, and at least as many picture matches side with the room, the room wins. The same pictures catch a classic mistake. If they say the camera hardly moved for most steps (under 1° and 3 mm) while the shape says it did, the object was turned by hand in front of a still camera. The pictures are right about the room and wrong about the object. They're not allowed to overrule, and the report suggests Turntable mode. 4.5 Loop closures on a leash Loop closures are where the 0.9.0 work found its worst errors. On a plain made-up blob, 40 of 42 accepted closures were wrong, by tens of degrees: a smooth surface happily fitting itself in the wrong place, with plenty of overlap. The candidates are: frames 2 to 4 steps apart, every frame against the first, and up to 4 earlier frames seen from within 30° and 20 cm (a "revisit"). Each is aligned (coarse plain ICP at 4 times the match distance, then colour ICP), and kept only with at least 50% two-way overlap and a surface error under 1.6 times the scan's typical step. Then: 1. Confirmed by the pictures? At least 12 picture matches agree with the closure and the pictures don't back their own best estimate clearly better than this closure (0.10.0: a dozen chance matches had "confirmed" closures 18-24° out). Then it's in. 2. Not confirmed? It may only move a frame as far as the chain could have drifted: - at most 2° + 0.25° for every step in between that the pictures vouched for + 5° for every step they couldn't; - at most 8 mm + 2 mm per vouched step + 30 mm per unvouched step. 3. Either way, if the two frames' own picture features disagree with the closure by more than 2.5° or 12 mm, and either the tracker's or the pictures' estimate for that pair was confident, or the pictures clearly prefer their own answer, it's out. !The loop-closure rule. Steps the pictures vouched for drift only a fraction of a degree each, so a closure that wants to move a frame by much more than that is a false fit. 4.6 Polish, and leaving out what moved - Pose graph (Open3D's Levenberg-Marquardt optimiser) spreads the leftover error over the chain. - Polish (handheld): every frame is aligned again against the model made from all frames together, in two passes. - Frames that disagree with their neighbours (median point-to-plane offset over 2 times the scan's typical offset, and more than 0.8 mm) are left out, never more than 40% of them. - Areas that moved (a blink, a mouth, a hand passing through, or a sensor defect that puts a bump at a fixed place in the image) are cut out of just that frame: a patch at least 25 points big, over 3 times the typical offset and 3 mm away, but under 35% of the frame. The other frames still cover it. 4.7 Turntable mode: one axis to rule them all With the camera on a stand and the object on a turntable, every step is a turn about the same line. Scantastic uses that hard: - Remove what stands still. Either record the empty turntable first (any pixel within 8 mm of the empty scene is background), or find the table plane and, on top of it, the turntable's top: a flat layer parallel to the table and wider than the object. Left in, the turntable top looks identical at every turn and pulls every step short. - Picture features on the object only. Keypoints near the object's outline are dropped in turntable mode (they sit on the still background and said "nothing moved"). - Fit the axis to the steps. Each step's rotation axis is fitted to one line. A step that doesn't fit is tried again at the angle the pictures or neighbouring steps suggest. Each frame's pose is then just its angle: the sum of the turns before it. One bad step can't bend the rest of the scan. - Fine-tune axis and turns together. Each small step measures its turn well but its axis badly (a 12° turn about a line 5 mm away looks almost the same), and on a made-up scan that grew to about 6 mm on the far side of the object. So the axis (4 numbers) and every frame's turn are fitted together by Gauss-Newton on point-to-plane distances, using each frame and its 4 nearest frames within 45°, with each turn held near what its step measured. - Close the full turn. When the scan goes all the way round, the last frames are also matched to the first and the angles are solved again with those closures in, so a little error per step can't add up to a gap. - If the steps don't fit one axis (more than 3 mm from it), the scan is treated like a handheld one instead. - No free polish. The handheld polish lets each frame move freely in any direction. On turntable scans of plain objects that undid the axis fit (0.6 mm became 3.5 mm), so turntable scans skip it. - Optional marker ring. A printed ring of ArUco markers lies on the turntable around the object. The object turns with the ring, so the ring's pose in each frame gives the turn directly. !Turntable mode from above. Each frame sits on the fitted axis at the sum of the turns before it; a step that doesn't fit is re-tried. !A marker ring of the kind Scantastic prints (an illustration drawn for this paper with OpenCV's ArUco markers; the app's own ring has its own layout and a 50 mm check bar). 4.8 Live tracking: knowing you're lost while you can still do something about it Version 0.10.0 added the parts of SLAM that help here (keyframes, and finding the way back when lost), written from scratch on OpenCV's ORB features, so the licence stays the same: - Keyframes. Each live picture is matched to the current keyframe, not the frame before, so small errors don't pile up. A new keyframe is taken after 8°, 4 cm, or when fewer than 60 features still match. 40 recent keyframes are kept. - Finding the way back. When a picture can't be matched (camera covered, swung away), the tracker tries recent keyframes, then a spread of older ones. - TRACKING LOST appears on the live picture while it's lost. - Each capture starts where the tracker said the camera was. These guesses carry where they came from and which track (one START to STOP, or one recording) they belong to. Guesses from two different tracks are never compared: the object may have been turned over in between. Live guesses may overrule ICP at 2.5° / 12 mm; an older recording's chained guesses drift more and keep a looser 6° / 4 cm. - The camera thread only copies and queues. Captures are worked out on their own thread, at most 2 waiting. If the PC falls behind, a capture is skipped with a message rather than freezing the live picture. !Keyframe tracking. Blue arcs: each frame is matched to its keyframe. Red: the camera was covered; the tracker found its way back by matching an older keyframe. !The real banner, drawn by the app's own function over a made-up frame. 4.9 Slow PCs: slow, but never falling over On a slow PC such as a 7th-gen i3, stitching while you scan should starve the camera: frames drop and the picture freezes. (Expected from timings on a 2-core test computer; not yet tried on a real i3.) So there are two scan styles: !Two scan styles. On a slow PC, scanning only records; the heavy work runs afterwards in its own process. - The speed check. The first time it starts, the app times one tracking step on a made-up 640 × 480 picture. With 4 processor threads or fewer, or a step slower than 150 ms, it picks "Record now, stitch afterwards". You can change it. - Recording saves the camera's frames to disk at most 10 a second, using the same cleaned depth a live capture would get. The frame list (frames.json) is rewritten every 10 frames (every 50 on long recordings), to a temporary file that then replaces the old one, so a crash leaves a usable recording minus its last few frames. - Stitching runs in a separate process after STOP. It cleans the frames, follows the camera through all of them with the live tracker, and keeps one frame per 6° or 3 cm of movement. On a made-up 116-frame recording, aligning every frame took 14 minutes on the 2-core test computer; the 48 frames worth keeping took 4. - Memory budget: at most 30% of free memory at 5 MB a frame, never fewer than 40 or more than 300 frames. A longer recording is thinned to every n-th frame to fit. - If it dies, only the stitching process dies. It's started again on every 2nd frame, twice at most. A process that dies before doing any work isn't blamed on memory. The recording stays on disk whatever happens. Build Mesh turns into Cancel while it runs, and the status bar shows the minutes left. !Crash-proof stitching. Left: how many frames a stitch may hold. Right: what happens if it still runs out. !Thinning a recording by motion. Frames that mostly repeat each other are skipped before the slow part. 4.10 Speed profiles, side-by-side alignment and the graphics card Version 0.11.0 brought over the speed profiles from my STL-to-STEP converter, then measured what actually helps here. !Speed profiles. Auto picks one from the computer's cores and memory. - Priority. Building and stitching run at low priority on Potato ("nice 10" on Linux and macOS, "idle" on Windows), so the computer should stay usable. It makes nothing faster; it stops the build hogging the computer. - Alignments side by side (Moderate, and Extreme when no graphics card is in use: with a card, alignments queue on it one at a time). The loop-closure alignments are independent of each other, and so are the starting guesses of one chain step. Helper processes, each holding its own copy of the frames, run them while the main build process works through them too. Answers are put back in the original order and the checks then run in that order, so the result is the same (largest pose difference measured: 3 × 10^−13^, which is Open3D's own last-digit noise). - A helper ends when its pipe breaks or a watchdog sees the builder gone (Cancel). - A helper that dies or fails a task only costs time: the builder does that task itself. - The number of helpers is cut to fit in half the free memory (300 MB plus 1.5 times the frames each). - Each process gets two Open3D threads per core's share. - Exactly-the-same polish, quicker. Colour ICP works out a colour gradient for every point of the target, from its neighbours within 2 times the match distance, on every call. In the polish the target is the whole model, and each frame only sees part of it. So only the model within 5 times the match distance of the frame is used. Points further than 3 times can't change the answer. If the frame moved more than the spare 2 times, or the answer scores differently against the whole model, it's redone on the whole model. Poses matched the uncropped run to 10^−14^; the polish took 18 seconds instead of 24 on one made-up scan. - What the three margins are for: matches are only made within 1× of a point; each point's colour gradient looks 2× further; so nothing beyond 3× can change the answer. 5× leaves 2× to spare for the frame moving. - Repeatable fallback. The feature-based fallback alignment uses random sampling. It's now seeded, so the same frames always give the same answer. - The graphics card, with a gate. Open3D's newer "tensor" ICP and depth fusion can run on an Nvidia card (CUDA). The standard Open3D for Linux already contains that part. Before a card is used, a separate process runs the actual steps (colour ICP between two small made-up surfaces, and a depth fusion) on the card and on the processor, and they must agree to 0.5 mm. During a build, any card error (out of memory, a driver fault) switches the card off and the processor redoes that step; an error is never mistaken for "these frames don't overlap". - Not used: Nvidia on Windows (Open3D's Windows CUDA build is a preview), Apple graphics (Open3D has no Metal support), AMD and Intel graphics. !Side by side. The answers come back in the original order, so the result is the same as one process. !The exactly-the-same crop. Only the part of the model that can change the answer is used. 4.11 The sensor check: mapping a scratched window Point the camera at a plain flat wall, hold still, and the app collects 30 frames. A flat wall seen by a pinhole camera has 1/depth changing in a straight line across the picture, so a smooth low-order fit of 1/depth is the "true" wall. That fit also absorbs lens distortion and a slightly bowed wall. (The fit is repeated with the worst pixels left out; the written breakdown in the report uses an even more outlier-proof fit from 2,000 random trials.) A scratch then stands out from it in one of three ways. These are the limits for pixels that get ignored while scanning: | Fault | Ignored when (scaled to 40 cm) | Shown as | |---|---|---| | Flicker | a pixel's noise is over 2.5 times the typical noise, and over 1.5 mm | red on the noise map | | Steady offset | a pixel is off the wall by over 5 times the typical spread, and over 2 mm | red (too far) or blue (too near) on the offset map | | No depth | enclosed holes up to 5% of the view, and pixels that lose their depth more than a quarter of the time | purple | The report's written diagnosis is more sensitive: it already counts an offset of 3 times the typical spread. The marked pixels can then be ignored while scanning, all of them or only the no-depth ones, and shown live in magenta. !A real sensor check, on the D415 at 50 cm (11 October 2026): "noticeable damage", 8.1% of the view to ignore. Left, flicker; right, steady offset. !The same check on a made-up wall with one scratch (flicker), one dent (steady offset) and one hole, as drawn by the app. 4.12 From frames to a mesh - Smooth surface (default): TSDF fusion in an Open3D VoxelBlockGrid, sized from the scan itself because it reserves its memory up front. On the SR305 the grid follows the Quality slider (2.5 mm at Low, about 1.5 mm in the middle, 1 mm at High) and is smoothed with 5 Taubin passes; the D400s start at a fixed 1 mm grid and 2 passes. Surface seen in only one frame is dropped when there are enough frames. - Watertight: Poisson reconstruction, trimmed back to within 2.5 grid cells of a scanned point. - The 3D preview is coloured by how many frames saw each area, so thin spots show before you print. - Cut and make solid: draw a line across the model to cut it, or let the app find the table. "Make solid" closes an open scan by inside-outside voting along 9 directions. 5. A tour of the app These screenshots come from the app itself, running on made-up data, because the camera wasn't at the computer the paper was written on. They show version 0.10.0's window; 0.11.0 adds the Speed and graphics card box. !The main window in its default "retro TV" look: live picture on the left (static when no camera is plugged in), settings on the right, and two big buttons. !A made-up scan, coloured by height, with the view cube top right. !Cutting: "Find the table" found the flat base; the part that will go is red, and the yellow handle drags the cut. !Turntable mode in the Scan panel: record the empty turntable, save the marker ring, and the scan-style box. !"Record now, stitch afterwards", chosen for a slow PC, with the honest expectations spelled out in the panel. !The plain look, for anyone who doesn't want a wooden television. 6. The mistakes, for free Every one of these happened. Most were caught by measuring, a few by a separate reviewer, and some by the owner of the camera. | What went wrong | What it looked like | The fix | |---|---|---| | The room was in every frame | A still room "won" the alignment, so turning in front of the camera gave a second nose | Cut out the subject (4.1) | | A setting from an older Open3D | The fallback alignment's RANSAC got a "confidence" of 500, so it never stopped early: 400,000 iterations, every time | Proper (iterations, confidence) values | | Open3D 0.20's one-line hole filling | Handed back vertices from memory that had already been freed: garbage in 19 of 30 tries | Keep every step alive and copy the arrays out: 0 of 30 | | An outline trim made for the D415 | Silently cut 20% of the points from every SR305 frame | Trim per camera (2 px SR305, 5 px D400) | | Loop closures on smooth shapes | 40 of 42 accepted closures on the plain blob were tens of degrees out | The drift rule (4.5) | | Picture keypoints on the outline (turntable) | Background corners said "nothing moved", so every turn came out short | Drop outline keypoints, turntable only (it broke handheld scans when done there too) | | The turntable's own top | Looks the same at every turn: pulled every step short | Find it and remove it (4.7) | | The axis from small steps | About 7 mm out, 6 mm of error on the far side | Fit axis and turns together (4.7) | | The free polish on turntable scans | 0.6 mm became 3.5 mm on the plain scan target | Turntable scans skip it | | A dozen chance picture matches | "Confirmed" loop closures 18-24° out | Confirmed only if the pictures don't prefer their own answer (4.5) | | The older recording tracker | One bad link put every later frame 0.7 m out, while reporting 0.65 confidence | Stitching uses the keyframe tracker | | Aligning every recorded frame | 14 minutes for one 116-frame recording | Keep one frame per 6° or 3 cm: 4 minutes | | Open3D 0.20 on Apple-silicon Macs | Needed Homebrew's libusb: "Library not loaded" | Macs use Open3D 0.19 (figure below) | | A graphics-card error | Treated as "no overlap", so frames could be dropped silently | Switch the card off, redo on the processor | | Helpers after Cancel | A busy helper kept running | A watchdog ends it within a second | | A result file for 0.10.0 | Said 0 of 20 failed. Run again, the shipped code fails 1 of 20 | Corrected in 0.11.0's notes; the rerun is published next to it | !Mistake, live: the first real run on an M5 Mac (24 October 2026). Open3D 0.20 couldn't find a library that only Homebrew installs. Fixed the same day. !Building the camera driver from source on Linux (15 October 2026), before 0.8.0 switched to Intel's ready-made one. It took a while. 7. The numbers Everything in this section comes from made-up scans with known answers (a benchmark that renders 5 objects with rich and plain patterns, with an SR305-like noise model, from known camera paths). A scan fails if any kept frame lands more than 3 mm from where it should. Tuning used seeds 0-1; the held-out seeds 1000-1001 were only used to check finished code. Times are on a 2-core cloud computer. !Results. Left: handheld held-out scans that failed, by version. Right: how far out the worst frame typically was, on scans that passed. | Version, mode | Failed | Typical worst frame | |---|---|---| | 0.8.1 (before this work), handheld and turntable | every scan | — | | 0.9.0 turntable (tuning + held-out) | 0 of 40 | 0.6 mm | | 0.9.0 handheld, held-out | 0 of 20 (as recorded then; not re-run) | 0.9 mm | | 0.10.0 live tracking (tuning + held-out) | 0 of 20 each | 1.0 mm | | 0.10.0 record now, stitch later, held-out | 2 of 20 (one stray frame each, 6-8 mm) | 0.9 mm | | 0.10.0 handheld held-out, re-run | 1 of 20 (the plain blob, 3.1 mm) | 0.93 mm | | 0.11.0 handheld held-out | 1 of 20, the same scan, identical answers on all 20 | 0.93 mm | | 0.11.0, graphics-card code run on the processor | 1 of 20 (the same scan) | 0.88 mm | Speed, honestly. On a 7th-gen i3, expect several minutes from STOP to a mesh (estimated from the 2-core test computer, which is in the same range; not timed on a real i3). The 0.11.0 speed-ups are small on 2 cores: the polish about a quarter quicker, loop closures about 10% quicker with one helper. More cores and a graphics card should help more, but neither has been measured. 8. A test plan, for anyone with a depth camera If you have an SR305, SR300, a D400-series camera or a Prowise MOVE 3in1, please try these and report back (an issue or discussion on the repository, with photos): 1. Sensor check on a plain wall at 40-50 cm. Post both maps and the percentage. 2. Scan target. Print the app's 70 mm test block, scan it in Turntable mode, and use "Compare mesh with scan target". It reports the error in millimetres. 3. Turntable, with and without the printed ring, on a plain object (a mug) and a patterned one. 4. Handheld, both scan styles, on the same object. Note the time from STOP to mesh and whether TRACKING LOST appeared. 5. A slow PC. On a 7th-gen i3 or similar: does "Record now, stitch afterwards" get picked, does it finish, and does the computer stay usable while it works? 6. A many-core PC or an Nvidia card on Linux: Potato against Extreme, same scan, time to mesh. 9. Defensive disclosure This section is written to be read as prior art. It describes methods implemented in Scantastic (versions 0.9.0 to 0.11.0, source published at the repository below), and variations of them. All of them are dedicated to the public. Anyone may use them, free, for any purpose. The purpose of publishing them is to make it hard for anyone to patent them and restrict their use. Where a number is given, any other value that does the same job is also disclosed. Not legal advice. D1. Choosing between live stitching and record-then-stitch by measuring the computer. On first start (or on demand) the software times a representative step of its own live processing (feature extraction and matching on a synthetic image; or any other step of the real pipeline) and reads the processor thread count (or, as a variation, memory too). Below a threshold it selects a mode where scanning only records frames (optionally pre-cleaned, rate-limited) and all alignment runs afterwards. The choice is shown to the user with an expected-time warning, and the user can override it. Variations: re-measuring periodically or while scanning; switching modes mid-scan when frames start to drop; thresholds on battery state, temperature or other load; recording at reduced resolution; recording only frames that pass a motion or sharpness test. D2. Crash-tolerant deferred stitching. The deferred alignment runs in a separate operating-system process with a frame budget derived from free memory (a share of it divided by a per-frame cost, clamped to limits). If the process dies, it is restarted on a subsampled set of frames (every 2nd, then every 4th; or any decreasing subset), a bounded number of times. A process that dies before reporting any progress is treated as a different failure from running out of memory. The recording's index is written atomically (to a temporary file, then renamed) at a decreasing frequency as the recording grows, so a crash loses only the last few frames. Variations: splitting the recording into overlapping chunks that are stitched and then joined; spilling to disk; any other subset rule (by motion, by time, by sharpness). D3. Motion-based thinning before global alignment. A lightweight tracker follows the camera through every recorded frame; only frames that have turned or moved more than a threshold (6° or 3 cm; or any other threshold, including one adapted to the object size or the overlap) from the last kept frame are passed to the expensive alignment, together with their tracked poses as starting guesses. On a turntable, a fixed number of frames spread evenly over the turn. D4. Track-scoped, source-weighted pose priors. Each starting guess carries its source (live tracker, recording tracker, picture features, marker ring) and a track identifier. Guesses from different tracks are never compared or chained. The tolerance with which a guess may overrule a shape-based alignment depends on its source (tight for a keyframe tracker, loose for a drifting frame-to-frame tracker). A guess with low confidence is replaced, for checking purposes, by an independent pairwise estimate from the two frames' own picture features. D5. Drift-bounded loop-closure acceptance. A loop closure between two frames is accepted without image-feature confirmation only if it moves the frame by no more than a bound that grows with the number of chain steps between the frames, with a small allowance per step that image features vouched for and a large allowance per step they couldn't (2° + 0.25°/vouched + 5°/unvouched, and 8 mm + 2 mm/vouched + 30 mm/unvouched; or any monotonic function of those counts, step lengths or step confidences). Image-feature confirmation requires both a minimum number of agreeing matches and that the features do not clearly prefer their own best estimate; and any closure the two frames' own features contradict is rejected. Variations: the same bound applied to chain steps or relocalisation; bounds expressed as covariance in the pose graph instead of accept/reject. D6. The still room as a referee. In handheld scanning of an isolated object, a down-sampled copy of the whole scene (before the object is cut out) is kept per frame. Where image features can't vouch for a step, the scene copies are aligned coarse to fine from several guesses. Among fits that pass overlap and error thresholds, the one most image-feature matches agree with is chosen, and it overrules the object's own fit only if the features side with it at least as much. Also: when image features say the camera stood still while the object's shape says it moved, the software concludes the object was moved in front of a still camera, stops the features from overruling, and suggests a turntable mode. D7. Turntable poses as one axis plus angles. With a still camera, every pairwise step is treated as a rotation about one common axis. The axis is fitted to all steps, off-axis steps are re-tried at an angle from image features or neighbouring steps, and each frame's pose is the cumulative angle. Axis (tilt and position) and all angles are then refined jointly by least squares over pairs of nearby frames (each frame's nearest few within 45°; or any other choice of pairs), together with full-turn closures where the scan goes all the way round, with each angle held near its measured step. A free 6-degree-of-freedom refinement is skipped in this mode, and if the steps don't fit one axis the scan falls back to free handheld-style alignment. Static scenery is removed by an empty-scene snapshot or by detecting the table plane and a turntable top (a flat layer parallel to and above the table, wider than the object). Image keypoints near the object outline are excluded in this mode only. Variations: a printed marker ring giving angles directly (ArUco, AprilTag, coded dots, a printed angle scale); a motorised turntable reporting angles; any mix of these as priors. D8. Exact cropping of the target in colour ICP. When aligning a frame to a much larger target (a fused model, a previous scan), the target is cropped to the region within a margin of the frame's starting position, where the margin is at least the colour-gradient neighbourhood radius plus the match distance plus an allowance for movement (5 times the match distance in the implementation). The result is accepted only if the frame moved less than the allowance and its fitness and error, re-scored against the whole target, are unchanged; otherwise the alignment is redone on the whole target. Variations: caching target gradients instead; tiling the target; any margin derived the same way for other neighbourhood-based ICP variants. D9. Order-preserving parallel alignment with fail-safe helpers. Independent alignment tasks (loop-closure candidates, multiple starting guesses for one step) are run in helper processes holding copies of the frames, with the main process also working, and answers re-ordered to the original task order so the result equals a single-process run. Helpers are tied to the main process by a pipe and a watchdog; a task that fails in a helper is run only by the main process thereafter; the helper count is limited by free memory; random number generators used in alignment are seeded per call so results don't depend on which process ran which task. D10. A graphics-card gate made of the real work. Before an accelerator is used, a separate process runs the same alignment and fusion steps on it and on the processor with synthetic input, and the accelerator is enabled only if the answers agree within a tolerance. During use, any accelerator error disables it for the rest of the job and the affected step is redone on the processor; an accelerator error is never interpreted as a negative result (such as "no overlap"). The card list shown to the user gives, per card, whether it can be used and why not. D11. A flat-wall sensor map for depth cameras. The camera is held still in front of a flat wall; a smooth low-order surface is fitted to 1/depth across the image, robustly; pixels are classified as flicker (temporal noise well above typical), steady offset (bias well above typical spread) or missing (enclosed holes), each with an absolute floor scaled to a reference distance. The classes are shown as separate maps and can be excluded from scanning, together or individually. Variations: other reference targets (a sphere, a printed pattern); repeating the check over time to track wear. D12. Live-scanning feedback. A "tracking lost" banner on the live picture when a keyframe tracker can't place the current frame; speed warnings from image motion and depth change; distance colouring towards a best working band; automatic averaging of frames when the camera is still; and captures queued off the camera's thread, bounded, with a generation counter so cleared scans don't receive stale captures. D13. Per-frame removal of areas that moved. After alignment, a coherent patch of one frame (a minimum point count and maximum share of the frame) that sits much further from the other frames than the scan's typical offset, while the rest of that frame agrees, is excluded from that frame only, and the corresponding pixels are excluded from fusion. 10. Limits, and what hasn't been tested - None of the 0.9.0 to 0.11.0 methods has been run on a real camera yet. The real photos in this paper are from earlier versions. - All measured results are from made-up scans with a made-up noise model and texture. - Not run: a real 7th-gen i3, a computer with more than 2 cores, any graphics card, a real out-of-memory death of the stitching process, the Windows launcher, a printed marker ring, a printed scan target. - 1 of 20 held-out handheld scans still fails (a plain blob), and record-now-stitch-later had 2 of 20 with a stray frame. 11. Credits and how this was made - Built on: Open3D (MIT) [10], OpenCV (Apache-2.0) [11], Intel's librealsense (Apache-2.0), NumPy, Pillow and Python's tkinter. - Written with help from Claude (Anthropic's AI assistant), which wrote much of the code, ran the benchmarks and drafted this paper. The camera, the scratches, the bug reports from real hardware and the decisions are mine. Every number above came from code that was run, and the made-up ones say so. - Not affiliated with Intel, Prowise, or anyone else named here. RealSense is a trademark of Intel. - Everyone who sends a test result, a correction or prior art I missed will be credited in the next version. References 1. R. A. Newcombe et al., "KinectFusion: Real-time dense surface mapping and tracking", ISMAR 2011. 2. T. Whelan et al., "ElasticFusion: Dense SLAM without a pose graph", RSS 2015; A. Dai et al., "BundleFusion", ACM TOG 2017. 3. C. Campos et al., "ORB-SLAM3", IEEE T-RO 2021. <UZ-SLAMLab/ORB_SLAM3> 4. S. Choi, Q.-Y. Zhou, V. Koltun, "Robust Reconstruction of Indoor Scenes", CVPR 2015. <openaccess.thecvf.com> 5. J. Park, Q.-Y. Zhou, V. Koltun, "Colored Point Cloud Registration Revisited", ICCV 2017. 6. "Robust loop closures for scene reconstruction by combining odometry and visual correspondences", ICIP 2016. <users.aalto.fi
Handheld Ops Copyright Matthew Armstrong. Source-available under the PolyForm Noncommercial License 1.0.0: free to use and change for non-commercial purposes. Provided as is, with no warranty and no liability. Not affiliated with Activision, Infinity Ward, Treyarch, Valve, ASUS, the Bazzite project or any of the mod teams below. One tap-friendly app that gets three classic shooters ready for handheld PCs (ROG Ally, Steam Deck, Legion Go) on Bazzite or SteamOS (and Windows): | Game | Campaign | Multiplayer | |---|---|---| | Call of Duty: Black Ops (2010) | Hidden gamepad mode switched on | Same, plus Plutonium's configs | | Call of Duty 4: Modern Warfare (2007) | IW3SP-MOD installed: gamepad + aim assist | CoD4x: steps and official page (assisted) | | Call of Duty: Modern Warfare 2 (2009) | IW-Pad installed: full controller support | IW4x installed: native controller + aim assist | Plus, for all three: - Steam launch options written for you (with Steam closed), so the normal Steam Play button starts the modded game under Proton. Your own launch options are never overwritten without asking. - Full HD locked at every start (or 1440p / 4K): set in the game's config files and again on the command line, so a game that falls back to "safe" or "recommended" settings (MW2's 640-pixel habit) comes straight back. - Five one-tap graphics tiers per game (Off, Battery saver, Balanced, Quality, Ultra): the game's own settings plus a matching SweetFX preset, so you never have to dig through the effects overlay. - Look: ReShade/SweetFX-style sharpening and colour through vkBasalt on Linux, switched on per game. - Touchscreen help for the menus. Every replaced game file is backed up and Remove puts it back. !MW2 page Step by step 1. Install the games in Steam and start each once (Black Ops needs that to write its config files). 2. Open Handheld Ops and pick a game tab. 3. Press Install (or Controller ON for Black Ops). Downloads come straight from each mod's official release page; the log shows every step. 4. Quit Steam (Steam menu > Exit), then press Write to Steam. Or press Copy and paste each line into Steam > game > Properties > General > Launch Options yourself. 5. Start Steam again and play from your library as usual. In Steam Input, use a Gamepad layout for these games. !CoD4 page What the launch options look like bash -c 'exec "${@/iw4mp.exe/iw4x.exe}"' -- %command% Steam fills in %command% with its own Proton command; bash swaps the stock .exe for the mod's. The same form is documented by IW-Pad. With the look on, ENABLE_VKBASALT=1 VKBASALT_CONFIG_FILE="..." goes in front. Graphics tiers !Graphics tiers Tap a tier on the game's page. It is applied straight away (quit the game first) and again whenever you press Write to Steam. | Tier | Game settings (only those the game already has) | Effects | |---|---|---| | Off | left as they are | none | | Battery saver | 60 fps cap, vsync off, AA off, shadows off, 4x texture filtering, depth of field off, textures one step lower | light CAS sharpening | | Balanced (default) | 60 fps cap, vsync off, 2x AA, shadows on, 8x filtering, best textures | SMAA + CAS sharpening | | Quality | 90 fps cap, vsync off, 4x AA, shadows on, 16x filtering, best textures | SMAA + vibrance + luma sharpen | | Ultra (SweetFX) | 120 fps cap, vsync off, 4x AA, shadows on, 16x filtering, best textures | SMAA + vibrance + contrast curve + luma sharpen | - Bazzite / Linux: each game gets its own vkBasalt file; the Steam launch option points at it. Quality and Ultra download the SweetFX shaders the first time (automatically). - Windows: press Install ReShade essentials for the game on the Look tab. That installs ReShade without its long effect-package list, adds only the 5 effects the tiers use (10 small files) and applies the tier. ReShade's own list then shows just those 5, the start-up tutorial is off, and Home still opens it. Effects you installed before stay on disk, hidden; Show my other effects brings them back. - Already have ReShade? It is never reinstalled or overwritten: the button keeps your d3d9.dll, your own presets and effect packages, and only changes five lines of ReShade.ini (which preset, the two shader folders, skip unused effects, tutorial done). The original ReShade.ini is saved the first time; Restore my ReShade puts it back exactly. A d3d9.dll that is not ReShade (another mod) is left alone and reported. - The fps caps suit a 120 Hz handheld screen; in Steam Gaming Mode you can also cap frames in the Quick Access menu. Leave the Steam scaling filter (FSR) alone: with the Full HD lock the game already runs at the screen's resolution, and FSR only helps when a game renders below it. Conflicting settings are removed !Conflict warning, then Put back Picking a tier (or Write to Steam) first clears anything that would undo it: - Extra game config files such as an autoexec.cfg in the game's players or main folder: lines that set vsync, the fps cap, anti-aliasing, shadows, texture settings or the resolution are turned off (commented out with a // handheld-ops off: marker, backup first). Other lines, key binds, the game's own config.cfg and files a mod installed are left alone. The Graphics card warns before and shows Put back after. - ReShade settings that override a tier (Windows): a start-up preset, NoReloadOnInit, preset-switch hotkeys and preset shortcut keys are set to off; Handheld Ops' own presets for other tiers are removed. Your own preset files are kept. Restore my ReShade undoes everything in ReShade.ini. - Old launch options that contain only vkBasalt, an exe swap or the resolution are replaced (and remembered for Put back). Launch options with anything else of yours still ask first. Aim feel (Black Ops) If aim feels floaty: every graphics tier turns vsync off, the usual cause of input lag. Then check Steam Input for the game (Controller settings > right stick: smaller deadzone, Linear or Aggressive response curve). The Black Ops page also has an experimental Look speed button that changes the game's input_viewSensitivity (1, 1.25, 1.5, 2); it is not confirmed that the PC game uses that setting for the gamepad. Screen resolution (Full HD as the minimum) !Screen resolution card On by default for all three games at 1920x1080; tap to choose 2560x1440 or 3840x2160, or switch it off. It is set in two places: 1. The config files: r_mode in every engine config under the game's players folder (CoD4 keeps them in players/profiles/<name>/), plus r_fullscreen 1, r_aspectRatio "wide 16:9" and com_recommendedSet 1 where the game already has those lines. com_recommendedSet 1 tells the game its recommended settings were already applied, so it stops replacing yours with auto-detected ones. 2. The launch option: +set r_mode 1920x1080 +set r_fullscreen 1 after %command%. These engines apply command-line settings after reading the config, so the resolution comes back even if the config was reset. If a game asks "Run in safe mode?" after a crash, answer No. In Gaming Mode, also check the game's Steam properties for a Game Resolution option and choose Native. Black Ops !Black Ops page Controller ON sets the game's hidden gpad_enabled in the Singleplayer/ Zombies and Multiplayer configs (and Plutonium's copies). Optional aim slowdown (campaign/Zombies only, experimental, never Multiplayer). CoD4x (CoD4 multiplayer) CoD4x comes with its own installer, and how the Steam copy behaves with it is unclear (see RESEARCH.md), so the app gives the steps and opens the official release page instead of installing it. Controller in IW3SP-MOD (CoD4 campaign) IW3SP-MOD's gamepad code comes from IW4x: it is switched on by gpad_enabled (Handheld Ops adds +set gpad_enabled 1 at every start) and reads Xbox-style (XInput) pads. If yours is a PlayStation, Switch or other pad, start the game from Steam with Steam Input on (after Write to Steam), so Steam presents it as an Xbox pad. Starting iw3sp_mod.exe outside Steam (an old shortcut, Explorer) gets no Steam Input. Fallback: in Steam, Games > Add a Non-Steam Game > iw3sp_mod.exe, and play that entry. CoD4: stick works in menus but not in the game: IW3SP-MOD stops reading the sticks for moving and looking whenever the mouse moves even a little (or a keyboard key is pressed). Mouse in the game on the Controller card is set to Off for CoD4 by default (+set in_mouse 0), so the pad stays in charge; the pad drives the menus. Tap Write to Steam once. Use Steam Input's Xbox controller layout. CoD4: left trigger latches aim on until pressed again: that is the toggle-aim bind. Turn Controller override on (Controller card), keep Aim: Hold to aim, tap Write to Steam. In the game console (~) look for "Handheld Ops controller file loaded". Close Steam: next to Write to Steam. Steam is asked to close cleanly and ended after 30 seconds if needed. Use it in Desktop Mode (in Gaming Mode Steam is the whole screen, so the app refuses). Controller override (CoD4 IW3SP-MOD, MW2 IW4x): tick Controller override on the game's page and Handheld Ops writes its own controller file (handheld_pad.cfg, in the game's main folder) and loads it at every start, so you set the bindings here and never touch the mod. Defaults are IW4x's own: hold to aim, normal sticks. Pick from the dropdowns: Button layout (Default, Tactical, Lefty, Nomad, Default Alt), Aim (hold or toggle), Sticks (Default = left moves, right looks; Southpaw swaps them), Look speed, and any single button. Put the defaults back undoes it; I edit the file myself keeps your hand-edited file. After tapping, press Write to Steam once, then start from Steam. Proof it loaded: open the game console with ~, it prints "Handheld Ops controller file loaded". Controller report lists what the game saved and what Handheld Ops will start with (also saved as a text file to send). Left trigger latches aim on until pressed again / look feels heavy: the Controller sticks card shows what the left trigger is bound to. Hold to aim fix (on by default) changes a toggle bind to hold. Look speed steps x1, x1.5, x2, x3. Tap Write to Steam, then start from Steam. Right stick works in menus but not in the game: first set Steam Input to Xbox controller (CoD4 > Controller settings > Browse configs / choose the Xbox controller layout). That is what fixed it on the Ally; the default "controller" layout did not. If it is still dead: the view turns by the stick times the game's turn speed settings, and 0 means no turning. The Controller sticks card shows the saved values and Turn speed fix (on by default) sets standard ones at every start. Tap Write to Steam, then start from Steam. Still nothing: tell me what the card shows. Right stick does nothing (left stick and buttons work): the sticks are tied to moving and looking by bindaxis lines the game keeps in its profile config (players/profiles/<name>/config.cfg). A config without right-stick lines leaves the right stick dead. The Controller sticks card on the CoD4 page shows whether the right stick is bound, and Right stick fix (on by default) adds IW4x's default lines for a stick with no binding at all (a custom layout such as southpaw is kept); switched off it takes out exactly the lines it added. It runs on Write to Steam, Start, and the button itself: bindaxis A_LSTICK_X VA_SIDE MAP_SQUARED bindaxis A_LSTICK_Y VA_FORWARD MAP_SQUARED bindaxis A_RSTICK_X VA_YAW MAP_LINEAR bindaxis A_RSTICK_Y VA_PITCH MAP_LINEAR 0.4.2 also put these four on the start command line (+bindaxis ...), and with 0.4.2 the controller stopped working altogether in IW3SP-MOD. 0.4.3 takes them off the command line. Show last start log (Windows) shows the exact command the game was started with. Display: borderless window (Windows) !Display mode Switching away (Alt+Tab) from these DirectX 9 games in exclusive fullscreen can end in "DirectX encountered an unrecoverable error". On Windows the default for IW4x is a borderless window at the locked resolution (+set r_fullscreen 0 +set r_noborder 1 +set vid_xpos 0 +set vid_ypos 0), which switches away cleanly. Tap Display to go back to fullscreen. IW3SP-MOD (CoD4 campaign) starts in fullscreen by default (0.4.2+). Started borderless it opened as a 1280x720 window in the top-left corner whatever the locked resolution was. Borderless can still be picked for it (Display button) to test. If Alt+Tab crashes CoD4 in fullscreen, avoid switching away in game for now. Stock games keep fullscreen (they have no borderless mode). Safety - MW2 campaign / Special Ops: play offline only. IW-Pad warns that the Steam build's singleplayer still has remote-code-execution holes. The app shows this before installing. - IW4x is about 800 MB; the app checks free space first. The look (Linux) !Look tab 1. Pick a graphics tier on each game's page (see Graphics tiers above). 2. Press Write to Steam so the Play button uses that game's vkBasalt file. 3. In game, Home switches the effects off and on. On Windows, use the normal ReShade installer (all three games are DirectX 9). On Windows Handheld Ops runs on Windows too (tested so far only by pretending, on Linux; see Known limitations). The differences: - Steam's Play button starts the mod through a small Handheld Ops launcher ("pythonw.exe" "...\steam-launch.pyw" %command%, no console window). It starts the mod for the right mode (e.g. CoD4 Singleplayer -> IW3SP-MOD) and the stock game otherwise (CoD4 Multiplayer). Because Steam started it, Steam Input can turn any controller into an Xbox pad, which is what IW3SP-MOD and IW4x read. The desktop / Start menu shortcuts start the mod directly (fine for Xbox-style pads). - The resolution lock still works from Steam: "Write to Steam" (Steam closed) sets each game's launch option to `+set r_mode 1920x1080 +set r_fullscreen 1`, which Steam adds to the game's command line. The Start buttons and shortcuts pass the same, and the config files are set too. - Look: vkBasalt is Linux-only, so the Look tab installs ReShade from reshade.me with just the essentials (see Graphics tiers). !Look tab on Windows Touchscreen !Help tab - Steam Gaming Mode: a tap is a left mouse click where you touched. - If taps do nothing: hold the Armoury Crate button for Mouse Mode. - Desktop Mode: the touchscreen is a normal mouse. Command line HandheldOps-Linux.sh --list HandheldOps-Linux.sh --install iw3sp # also: iwpad, iw4x, bo1-gamepad HandheldOps-Linux.sh --remove iw4x HandheldOps-Linux.sh --install bo1-gamepad --aim-slowdown HandheldOps-Linux.sh --get-shaders --look sweetfx --look-for mw2 HandheldOps-Linux.sh --screen mw2=1920x1080 # or 2560x1440, 3840x2160, off HandheldOps-Linux.sh --steam cod4 --steam mw2 # resolution + launch options (Steam closed) HandheldOps-Linux.sh --tier mw2=quality # off, battery, balanced, quality, ultra HandheldOps-Linux.sh --put-back bo1 # undo removed conflicts HandheldOps-Windows.bat --display mw2=borderless # or fullscreen HandheldOps-Linux.sh --stick-fix cod4=off # take the stick lines out (on = add) HandheldOps-Linux.sh --look-speed 1.25 # Black Ops gamepad look speed (experimental) HandheldOps-Linux.sh --show-options HandheldOps-Windows.bat --reshade mw2 # Windows: official ReShade setup on MW2 HandheldOps-Windows.bat --shortcuts cod4 # Windows: shortcuts for installed mods HandheldOps-Linux.sh --game-dir "/path/to/Call of Duty 4" --list HandheldOps-Linux.sh --ui web # the web page (also: gui, dialogs, text) HandheldOps-Linux.sh --version What exists and what doesn't | Part | State | |---|---| | Finds the three games in every Steam library (SD card too) | Works on test data | | Black Ops controller ON/OFF, backups, undo | Works on test data | | IW-Pad install / update / remove | Real download and install done (simulated MW2 folder) | | IW4x install / update / remove from its update.json manifests | Real 787 MB install, no-change update and full removal done (simulated MW2 folder) | | IW3SP-MOD install / update / remove | Works against a stand-in server; the real host (gitea.com) is blocked from the build machine | | CoD4x | Steps + official page only | | Writing Steam launch options | Works on a test copy of Steam's file; exe swap checked in bash | | Resolution lock (configs + launch option) | Works on test configs; arguments checked in bash to reach the game after the exe swap; not yet seen in the real games | | Look (vkBasalt) presets | Loaded by real vkBasalt on software Vulkan | | Graphics tiers (Linux) | All four vkBasalt files loaded by real vkBasalt with the real SweetFX shaders; values read in; game-setting changes tested on Black Ops-style configs | | Graphics tiers (Windows ReShade preset) | Preset and ReShade.ini format taken from ReShade's source; tested against sample files; not yet seen in ReShade itself | | Windows Steam launcher (mod via Play, Steam Input) | The launcher script run end to end with stand-in .exe files: SP starts the mod with its settings, MP stays stock; Steam Input through it not yet seen on Windows | | Borderless window (IW4x / IW3SP-MOD) | r_noborder confirmed in IW4x's source; not yet seen in IW4x. IW3SP-MOD: tried on Windows, opened at 1280x720 in a corner, so it defaults to fullscreen | | Controller override file (handheld_pad.cfg + +exec) | Written, rewritten and kept when hand-edited, and the launch option only when ticked, all tested; the file name and main folder are what CoD4 normally searches, not yet seen loading in the game | | IW3SP-MOD turn speed (in-game look) | Values are the usual console ones; added as +set, skipped when the config has a value above zero; not yet seen in the game | | IW3SP-MOD stick bindings (right stick) | Names taken from IW4x's source and its thumbstick_default.cfg; config add/take-out tested on sample files. 0.4.2 (lines in the config and on the command line) left the controller dead on Windows; 0.4.3 uses the config only, not yet seen in the game | | Removing conflicts (autoexec-style files, ReShade overrides, old launch options) and Put back | Tested on sample files; byte-for-byte put back | | Existing ReShade kept, exact restore | Tested with a full existing install (DLL, own preset, effect package): nothing overwritten, ReShade.ini restored byte for byte | | ReShade essentials install (headless setup + 10 files) | Headless behaviour read from ReShade's setup source; the 10 files downloaded for real; SweetFX SMAA compiled through vkBasalt; headless setup not yet run on Windows | | Aim feel: vsync off / look speed | Written; effect on the feel not yet tested | | SweetFX shader download | Real download with git done; the zip route (no git) works against a stand-in server | | Windows: resolution launch option, Start buttons, shortcuts, ReShade setup | Logic tested on Linux by pretending to be Windows; not yet run on Windows (reshade.me and GitHub zip links are blocked from the build machine) | | Tested on a real ROG Ally / with the real games | Not yet | | HD textures, new lighting | Back burner (see RESEARCH.md) | More - HOW_IT_WORKS.md: exactly what is read, changed and backed up - RESEARCH.md: all research notes, sources and decisions - CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, THIRD_PARTY.md --- Source code: The-Dorkknight/handheld-ops on GitHub
Scantastic > WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN. > Version 0.11.0-wip. Source-available and free for non-commercial use > (PolyForm Noncommercial 1.0.0). No warranty. Scantastic (until 0.7.0 called RealSense 3D Scanner) is a desktop app that turns an Intel RealSense depth camera into a tabletop 3D scanner: live preview → scan while you turn the object → build a mesh → save .stl / .obj / .ply. It can also record the raw camera streams and clean them up in several passes before the mesh is built. Works with the SR305 / SR300 (coded light) and D400-series cameras such as the D415 inside the Prowise MOVE 3in1. The camera is detected automatically. A Kinect v1 or v2 can be used too, as an experimental option that has not been tried on real hardware yet (KINECT.md). It is designed for modest hardware (a 7th-gen i3 with no GPU is the target); everything has a CPU path. !Main window What has actually been tested Being straight about this, because it is a work in progress: | Area | Status | |---|---| | Whole app on a real camera | 0.2.0 has been run on real hardware (i5 U-series laptop, 8 GB). It scans and runs light, but the scans lack definition. 0.5.1 has been run on a D415 (sensor check and a face scan). The rest of 0.2.1 to 0.11.0 has not been run on a camera yet. | | Stream clean-up pipeline (stream_pipeline.py) | Unit-tested on synthetic scenes (8 tests, run in CI). Not yet tried on real footage. | | Sensor check breakdown and surface-detail options (new in 0.2.1) | Unit-tested on synthetic walls and scans (17 tests with the 3D-view ones; they need Open3D, so CI skips them). Not yet tried on a real camera. | | 3D view colours, backgrounds, remembered settings, cancelling a build (0.2.2, merged from an older fork) | Exercised headless on synthetic scans, plus 4 unit tests. Not yet tried on a real camera. | | Kinect v1 / v2 (new in 0.3.0, optional modules) | Untested on real hardware and against real drivers. 25 unit tests with stand-in drivers and a headless run of the app with a stand-in Kinect. | | Retro TV look (new in 0.3.0, optional module) | Exercised headless on Linux, plus 5 unit tests. Not checked on Windows or macOS. --plain switches it off. | | Cutting on the model (new in 0.4.0) | 25 unit tests on made-up shapes, and a headless run of the app that draws, drags, applies and undoes cuts on a noisy made-up scan of a ball on a table. Not yet tried on a real scan, or by a real hand on a real mouse. | | Double-click launchers (new in 0.4.1) | The Linux launcher: 9 tests with a stand-in Python, and started for real under a headless display. The Windows launcher has not been run on Windows. The Mac launcher was run by the owner on an M5 Mac with 0.9.0: set-up ran, then Open3D 0.20 failed to load (Homebrew libusb). Fixed in 0.9.1, which is not yet tried on a Mac. | | Live picture by itself, camera on/off, Rotate (new in 0.5.0) | 13 tests, 6 of them running the whole window with a stand-in camera and a stand-in "what is plugged in" answer (plugging in, turning off and on, turning off while starting, unplugging, a camera that will not start, turning the picture). Not yet tried with a real camera being plugged in and out. | | D400 settings (0.5.1, 0.5.2) | 18 tests with a stand-in RealSense driver. 0.5.1 tried on a real D415: much better than 0.5.0, still soft. 0.5.2 not yet tried. | | Handheld and turntable stitching, picture features, marker ring, scan target (new in 0.9.0) | Measured on made-up scans with known answers: turntable 0 of 40 failed, typical worst frame 0.6 mm; handheld 0 of 20 held-out and 3 of 20 tuning scans failed (0.8.1 failed every one). 21 tests. Not yet tried on a real camera, a real turntable, a printed ring or a printed target. See the results. | | Live tracking, scan styles, record-now-stitch-later, captures off the camera thread (new in 0.10.0) | Made-up video-rate scans: live tracking 0 of 20 failed (tuning and held-out); record-now-stitch-later 2 of 20 held-out scans had one stray frame 6–8 mm out (of about 50 kept); the rest had a typical worst frame of 0.9 mm. 18 tests, including end-to-end window runs with a stand-in camera. Not yet tried on a real camera or a real 7th-gen i3. See the write-up. | | Speed profiles, alignments side by side, graphics card (new in 0.11.0) | Held-out made-up handheld scans: the same answer as 0.10.0 on all 20 (1 of 20 fails, as 0.10.0 does when run again; its earlier "0 of 20" was not from its final code). The graphics-card method, run on the processor: also 1 of 20, worst frames within 0.04 mm. Final polish about a quarter quicker; side by side only about 10% quicker on the 2-core test machine. 23 tests. No real graphics card, no PC with more than 2 cores, and Windows and macOS not tried. See the write-up. | | SR305 unchanged by the D400 work (0.8.1) | Compared with 0.5.0 on the same inputs: camera set-up, window settings and mesh match, the last within run-to-run noise. 3 tests keep it so. | | Ready-made Intel driver, private Python 3.11, driver reuse (new in 0.8.0) | A real first run from nothing, here, with only Python 3.12 on the path: Python 3.11 downloaded, Intel's driver installed and hash-checked, app started. The suite passes on that Python (Tk 9). Not yet tried with a camera plugged in, or on your laptop. | | Advanced-mode switch, firmware note, review fixes (new in 0.7.1) | 20 tests with stand-in drivers, cameras and meshes. The advanced-mode switch matches librealsense 2.54.2's source, but has not been tried on a real D415. | | Magenta mask overlay, no-depth-only mask, fill small holes (new in 0.6.1) | 10 tests on made-up walls, a stand-in camera and a synthetic mesh with holes. Not yet tried on a real camera. | | Settings per camera, Reset, camera badge (new in 0.6.0) | 8 tests, 4 running the whole window with stand-in cameras that are swapped. Not yet tried with two real cameras. | | Optional ErrCode hook (new in 0.4.1) | Tried with stand-ins only, not with the real plugin. | | Laser power option (new in 0.2.1) | Checked against a fake sensor only. What value 1 does on SR305 firmware is unconfirmed. | | Recording infrared; opening .bag files; the optional AI mask; the GitHub workflows | Untested with real data. | All screenshots here come from synthetic test data, not a real object. The Kinect one uses a stand-in driver, not a real Kinect. If something breaks on your camera, please [open an issue](../../issues/new/choose). Kinect (0.3.0, experimental) !The app showing a stand-in Kinect Camera type at the top of the Camera panel switches between RealSense and Kinect. Kinect support is untested on real hardware, its drivers have to be installed by hand, and the sensor check, depth confidence and laser settings do not apply to it. The Kinect runs in its own process, so a driver crash cannot close the app; it is restarted automatically if it crashes, hangs or stops sending pictures. Everything is in KINECT.md. The look (0.3.0) The window is dressed as a wood-panelled television: walnut cabinet, black bezel, a rounded screen, and static on the screen while the camera is off. The static stops the moment the first camera picture arrives, and a lamp under the screen shows whether the camera is on standby or live. Everything is drawn by the app; there are no picture files. The static is a few pictures made once and swapped on a timer. In a headless test the whole app used about 4% of one processor core while showing it. Look (bottom of the right-hand panel) chooses Retro TV, Retro TV, still screen (no movement) or Plain. It applies the next time the app starts. --plain on the command line forces the plain look, and the app falls back to it by itself if the skin fails. !Plain look Using it 1. Plug the camera in. The live picture appears by itself (the app looks for a camera every few seconds while the live view is showing). Point it at the subject; the live distance guide shows the sweet spot. 2. START SCAN (green). In Handheld mode, move the camera slowly round the object; in Turntable mode, keep the camera still and turn the object ([below](#handheld-or-turntable-new-in-090)). STOP when done. Capture Frame takes single frames instead. 3. BUILD MESH. Choose Smooth surface (fuses depth images, recommended) or Watertight (Poisson; fills unscanned gaps so it can be printed). While it builds, the same button turns into CANCEL. 4. Save mesh… as STL/OBJ/PLY, in millimetres or metres. Other controls: near/far range, depth confidence, laser power, average-when-still, keep-only-the-subject, a CAD-style view cube, and cutting (next section) to remove the table or split overlapping scans. While scanning, the STOP button shows the elapsed time and the number of frames. Clear captured frames asks first if it would throw away a mesh you have not saved. Handheld or turntable (new in 0.9.0) Pick the Scan mode in the Scan panel. Frames are cut out differently in each mode, so changing it clears the frames captured so far (it asks first). | Mode | You move | Best for | |---|---|---| | Handheld | the camera, slowly round the object | big or fixed things, faces | | Turntable | the object, on a turntable or lazy Susan, a little between captures. The camera stays on a stand and must not move. | small objects; the most reliable | Turntable mode in four steps: 1. Put the camera on a stand, 30–50 cm from the turntable, looking down at it a little. 2. Optional, but best: with nothing on the turntable, press Record empty turntable. Everything that is there now (table, wall, the turntable itself) is left out of the scan. Without it, the table and the turntable's top are found and removed instead. 3. For a plain or round object (a mug, a smooth figure, anything with little pattern), press Save marker ring to print (PDF). Print it at 100% (the 50 mm bar must measure 50 mm), lay it flat on the turntable and put the object in the middle. The markers say exactly how far the turntable turned. 4. START SCAN and turn the object slowly through a full turn, or Capture Frame every 10–20 degrees. How it lines frames up: every frame is a turn about the same axis, so instead of six unknowns per frame there is one. A step that doesn't fit the axis is re-checked. A full turn is checked against the start, and the axis and every turn are then fine-tuned together against all the frames that see the same side. The build report says what it found, for example "Turntable: one axis fits the steps (0.4 mm typical); 24 frames over 345 degrees; full-turn check from 1 closure(s)". If the steps don't fit one axis (the object slid, or the camera was knocked) it says so and aligns as a handheld scan instead. Picture features (tick box, on by default): every step between frames is also worked out from the colour picture, using ORB corners on a greyscale copy, lifted to 3D with the depth. A shape match that the picture clearly contradicts is overruled. This is what stops a round object being glued on at the wrong turn. Untick it to compare. Slow PCs, live tracking, and what to expect (new in 0.10.0) The Scan style box (Scan panel) chooses when the heavy work happens. | Scan style | While you scan | After STOP | For | |---|---|---|---| | Stitch while scanning | Every capture is lined up as it comes. Handheld, the camera is also followed on the live picture (up to 10 frames a second), and a red banner says TRACKING LOST - move back slowly if it loses its way. | Build Mesh | a reasonably quick PC | | Record now, stitch afterwards | Only the camera's frames are saved to disk (about 10 a second), which even a slow PC keeps up with. | Stitching starts by itself and shows how long is left. Then Build Mesh. | slower PCs, such as a 7th-gen Core i3 | The first time it starts, the app times one tracking step on your PC (about a third of a second). With 4 processor threads or fewer, or a slow step, it picks *Record now, stitch afterwards*. You can change it at any time when not scanning. On a 7th-gen i3, be ready for slow. It won't freeze or crash, but it takes a while. - Stitching runs as a separate program with a memory limit. If it runs out of memory, only that program stops, and it starts again on every 2nd frame (twice at most). The recording stays safe on disk whatever happens. A recording cut short by a crash keeps all but its last few frames. - Expect minutes, not seconds. On a 2-core test machine, about as fast as a 7th-gen i3, a 40-second handheld recording (about 120 frames) took about half a minute to clean and track. Then lining up the 48 frames it kept took 2–4 minutes, and Build Mesh takes longer again. A turntable scan is much quicker to line up. These are measured on made-up scans, not timed on a real i3. - While stitching, the status bar shows the progress and the minutes left. You can leave it running. Whichever style you choose, captures are now worked out away from the camera's own thread. If the PC falls behind, a capture is skipped with a message rather than freezing the live picture. Speed profiles and the graphics card (new in 0.11.0) The Speed and graphics card box (right-hand panel) is taken from STL2STEP. It sets how hard Build Mesh and stitching work the computer. | Profile | Alignments at once | Priority | Graphics card | Auto picks it for | |---|---|---|---|---| | Potato | 1 | lowest: the PC stays usable | no | under 4 cores or 12 GB, such as a 7th-gen i3 | | Moderate | half the cores | below normal | no | most laptops | | Extreme | every core | normal | yes, where it passed its test | 8+ cores and 16 GB | !Speed and graphics card box Be realistic about what it gains. - Lining the frames up is over 90% of Build Mesh, and that is Open3D's ICP alignment. - On a 7th-gen i3, Potato makes nothing faster. It keeps the computer usable while it works. - Alignments side by side give the same results. On the 2-core test machine they were only about 10% faster; a PC with more cores should gain more, but that hasn't been measured. - The final polish is now about a quarter quicker, with the same results. Graphics cards: - Nvidia on Linux: the standard Open3D already contains Nvidia (CUDA) support, so nothing extra is installed. Press Test the card; the card is only used if a real alignment and depth fusion on it give the right answers. Otherwise the processor does the work, as before. - Nvidia on Windows: not used. Open3D's Windows graphics-card build is an experimental preview that isn't on the normal download site. - Apple M1–M5 Macs: not used. Open3D can't use Apple's graphics chip; Extreme uses all the processor cores instead. - AMD and Intel graphics: not used. Open3D supports Nvidia cards only. - No real graphics card has been tried. The card's code was run on the processor instead; see the write-up. python3 scantastic.py --speed-check prints the same information and tests the card. Scan target and compare (new in 0.9.0) Save printable target (STL) writes a 70 x 70 mm test block, shown below. Each corner has one feature: - steps 2, 4, 6 and 8 mm high; - a dome 30 mm across; - grooves 1, 2 and 3 mm wide; - a ramp. An L-shaped notch on one side means it only fits one way round. Print it in a matt colour, scan it on the turntable and build the mesh. Then Compare mesh with scan target reports: - the typical error and the error that 9 points in 10 stay within, in mm; - how much of the top was covered; - each step height as scanned. The same can be run outside the app: python scan_target.py target.stl # the STL python scan_target.py --ring ring.pdf # the marker ring python scan_target.py --compare scan.stl # compare a scan with the target !Scan target !Turntable mode The camera on and off, and turning the picture (new in 0.5.0) | Control | What it does | |---|---| | Turn camera off / Turn camera on (Camera panel) | Off stops the camera and keeps it off, also the next time the app starts, until you turn it on. The line under the button says what the camera is doing: live, waiting for one to be plugged in, or off. | | Rotate (above the picture) | Turns the live picture a quarter turn clockwise each press, for a camera mounted on its side or upside down. The 3D model's default view and the sensor check's pictures turn with it. The scan data itself is not changed. Remembered. | Unplug the camera and the app notices (at once on Linux, within about 8 seconds elsewhere), says so, and starts the picture again when the camera is back. A camera that is plugged in but will not start is reported once in the status line, with no dialog; press Capture Frame to see the full reason. START SCAN and Capture Frame still start the camera themselves, and turn it on if it was off. A Kinect is looked for in the same way on Linux. On Windows and macOS there is no quick way to look for one, so a Kinect starts when you press START SCAN or Capture Frame. Settings for each camera, and which camera is running (new in 0.6.0) Each kind of camera has its own settings. When a camera starts, the app puts that camera's settings in the window, and anything you change is remembered for that camera only. So a D415 and an SR305 can be swapped without retuning. Reset ... settings in the Camera panel puts the starting values back for the camera in use. The line under it lists what you have changed. The coloured badge at the top of the Camera panel says which camera is running: blue for an SR305 / SR300, orange for a D400, purple for a Kinect, grey for none. The model name is also shown in that colour on the live picture and in the window title. Starting values (best guesses; the reasons are in DESIGN_NOTES section 3): | Setting | SR305 / SR300 | D400 (D415) | Kinect | |---|---|---|---| | Near / Far | 0.20 / 1.00 m | 0.25 / 1.00 m | 0.5 / 3.0 m | | Depth confidence | Standard | (no such setting) | (no such setting) | | Laser power | Maximum | Maximum | (no such setting) | | Quality | 60 | 60 | 60 | | Surface detail | Standard | Fine (1.0 mm grid) | Standard | | Narrow band / 3+ frames | off / off | off / off | off / off | | Final smoothing passes | 5 | 2 | 5 | | Fill holes smaller than | off | 8 mm | off | | Sensor-check mask: only no-depth patches | off | on | off | | Only keep the subject / Average when still | on / on | on / on | on / on | Black spots in the same place on the screen (0.6.1) A black spot that stays put whatever you scan is one of two things, and the live depth picture now tells them apart: - Magenta: the sensor-check mask. You ran the sensor check and the app ignores those pixels on purpose. Untick Ignore damaged sensor areas to see what the camera gives there, or tick ...only patches with no depth to keep the merely noisy parts (run the sensor check again once, to save that smaller mask). - Black: the camera gives no depth there (a scratch, mark or smear on the window, or a dark or shiny patch). Clean the window with a blower and a dry, soft cloth (no liquids). Either way, move the object (or yourself) between frames. A spot at a fixed place on the screen falls on a different part of a turning object in the next frame, so the other frames fill it in. And Fill holes smaller than ... mm (Quality panel) closes what is left in the finished mesh with flat patches. It starts at 8 mm for a D400. D400 advanced mode and firmware (0.7.1) Advanced mode. A D400 has a setting stored in the camera called "advanced mode". Intel's driver only offers the High Accuracy preset and 0.1 mm depth steps while it is on, and the ripple correction needs it too. The first time a D400 with it off starts, the app asks whether it may switch it on. The camera restarts once, a few seconds, and it stays on. The tick box "Let the app switch on a D400's advanced mode" in the Camera panel changes your answer. Intel RealSense Viewer can switch it off again. D400 firmware. The app uses Intel's driver 2.54.2. It has to: 2.55 and later dropped the SR305. That driver is fine for a D415, because the depth is worked out inside the camera, but Intel recommends D400 firmware 5.15.0.2 or later with it. The status line says when a camera's firmware is older. The D415 tested here reports 5.11.10, from 2019. It works. Updating is optional, done with Intel's tools rather than this app: - Intel RealSense Viewer, under More, Update Firmware; - or rs-fw-update. Read the D400 firmware release notes first. Keep the camera plugged in and don't interrupt the update. D400 cameras such as the D415 (0.5.1) Before 0.5.1 a D400 shared the SR305's settings, and scans looked coated in a thick soft skin. Now a D400 gets its own: - depth at 848x480 instead of 640x480 (sharper; still works from about 30 cm); - 0.1 mm depth steps instead of 1 mm; - Intel's ripple correction (A-factor 0.08), if the camera's advanced mode is on. If it is off, the log says so. Intel RealSense Viewer can switch it on once and it stays on; - a wider trim along object outlines, where stereo depth spills past the real edge; - (0.5.2) the colour laid onto the depth, so the depth is never resampled; - (0.5.2) 2 smoothing passes to start with instead of 5; (0.6.0) its own remembered settings. The status line and the sensor check report say whether the ripple correction is on. Scan at the close end of the guide, about 35 to 45 cm. If a white or shiny object still looks blobby, try Laser Reduced. A sensor-check mask made before 0.5.1 is ignored on a D400 (wrong resolution), so run the check again. Cutting: point at where the cut goes (new in 0.4.0) !A cut set on the model The cut is set on the model itself, in the 3D view. The part that will be cut off turns red before anything is changed. 1. Press Draw a cut (in the 3D view, or Draw the cut on the model in the Edit panel) and drag a line across the model. The cut follows the line and goes straight into the screen. Hold Shift for a level, upright or 15-degree line. Esc cancels. 2. Adjust it if needed: drag the yellow dot to move the cut, drag the red arrow to turn it. The arrow points at the part that goes. Or press Redraw and draw the line again. 3. Flip side if the wrong part is red. Apply cut when it looks right. Undo last edit brings back both the mesh and the cut, so you can nudge it and apply again. Three shortcuts, in the Edit panel: | Button | What it does | |---|---| | Find the table / flat base | Finds the biggest flat area of the model and puts the cut just above it, so the table goes and the subject stays. It is a suggestion: check the red part first. | | Top, Bottom, Left, Right, Near, Far | Cuts off that side of the model as you see it now. Turn the view first (the view cube snaps to a face) and these give exactly level or upright cuts. | | How much | Slides the cut through the model, from nothing cut off to everything. | "Cap the cut" (on by default) closes the cut with a flat face, which makes a solid you can print; untick it to simply trim the surface. A scan seen from one side only is filled in straight back to a flat back, just behind the deepest point of the part you keep. This replaces the earlier orientation list, position slider and tilt joystick. A line drawn on the model removes whichever part is the thinner slice; if you meant the other, Flip side. Looking at the result: colours and background (0.2.2) !Height colours in the 3D view Above the 3D view, Colours chooses how the mesh is painted: | Colours | Shows | |---|---| | Scan colours | The colours the camera saw. | | Plain | Grey, shaded only. Best for judging the shape without the texture distracting. | | Height (low - high) | Blue at the bottom to red at the top, with the range in millimetres and the highest and lowest points marked. | | Relief (back - front) | The same map, front to back. Small bumps and dents stand out. | | Coverage (rescan hints) | How many frames saw each part, so you know where to scan again. | Background switches the 3D view between dark, grey, light, white, navy or a colour you pick. Both choices are remembered in settings.json next to the script. Sensor check: what kind of fault is it? (new in 0.2.1) !Sensor check result Sensor check (point at a wall)… looks at a plain, matt wall for about two seconds and finds the parts of the view that misbehave, so scans can ignore them. Since 0.2.1 it also says what kind of fault it found, because the cures differ: - Flicker (noise): the reading jumps about from frame to frame. Left picture. It cannot be subtracted; those pixels can only be trusted less. - Steady offset: the reading is wrong by the same amount every frame. Right picture (red = reads too far, blue = too near). An offset can in principle be subtracted. - Missing depth: purple in both pictures. It also reports how curved the camera sees the flat wall (calibration error, or a wall that is not flat) and whether a suspicious ring is only smooth calibration error. Every run saves two pictures, the two maps (.npz) and a text report in sensor_check/, named by wall distance and laser setting, so runs can be compared. Useful comparisons, each one a fresh run of the check: | Change | If the pattern changes | If it stays the same | |---|---|---| | Laser power Maximum → Reduced | Glare or saturation | Calibration or the window | | Wall at about 30, 40 and 60 cm | Glare or saturation | Calibration or optics | | Camera turned 10–20° off square | Glare off the wall | The camera | | Camera upside down or slid sideways | Stays with the wall: the wall is not flat | Stays with the image: the camera | Which pixels are ignored is decided exactly as in 0.2.0. One thing the breakdown shows that the ignore-mask misses: a large area with a steady offset (a third of the view reading 4 mm off, in the tests) is not ignored, because the old rule compares each pixel with the spread across the whole view. The report says so when it happens. Surface detail options (new in 0.2.1) Under Quality, for the Smooth surface method. The defaults give exactly the surface earlier versions gave. | Option | What it does | |---|---| | Surface detail | Grid size for fusing. Standard follows the Quality slider (2.5 mm at Low, about 1.5 mm in the middle, 1 mm at High). Fine / Finer / Finest fix it at 1.0 / 0.75 / 0.5 mm. | | Narrow fusion band | Sharper, but may leave holes where depth is noisy. | | Only surface seen in 3+ frames | Less noise, more holes. Needs 6 or more frames. | | Final smoothing passes | 0 = sharpest, 5 = as before. | Measured on a synthetic test object (a ball with 1 mm ripples, 40 frames, 1.5 mm depth noise, subject isolated), with the camera positions known exactly: | Setting | 6 mm ripples kept | 3 mm ripples kept | Fusing time | |---|---|---|---| | Standard, Quality in the middle (as before) | 64% | 48% | 0.7 s | | Standard, smoothing 0 | 70% | 66% | 0.7 s | | Fine 1.0 mm, smoothing 0 | 73% | 71% | 1.1 s | | Fine 1.0 mm, narrow band, smoothing 0 | 77% | 73% | 1.1 s | | Finest 0.5 mm, smoothing 0 | 76% | 75% | 5.0 s | So these options help, modestly. How accurately the frames are lined up matters far more. The same test with small errors added to every camera position: | Error per frame | 6 mm ripples kept (Fine, smoothing 0) | 3 mm ripples kept | |---|---|---| | none | 73% | 71% | | 0.1° and 0.3 mm | 71% | 63% | | 0.25° and 0.5 mm | 65% | 46% | | 0.5° and 1 mm | 48% | 7% | Fine grids need more memory. If a scan would need too much, the app uses the finest grid that fits and says so. Scanning only the subject ("Only keep the subject in the middle") keeps the volume small. Raw stream and clean-up !Clean-up dialog Tick Record every camera frame before scanning to keep the raw colour and depth (and optionally infrared) on disk. Afterwards, Open recording and clean up… replays a recording folder (or a RealSense .bag) through these passes, each optional: - Depth gate: drop anything outside the near/far range. - Remove the table: finds the flat supporting surface (RANSAC) and removes it and everything below. - Edge-aware smoothing: smooths depth noise but stops at edges the colour picture shows. - Track camera movement from the picture: matches features in infrared first, then colour, and lifts them to 3D using the depth. The resulting poses guide the mesh alignment: they seed the ICP, rescue frames ICP can't verify, and veto an ICP result that contradicts confident tracking. - Compare neighbouring frames: re-projects neighbours into each frame, drops depth that disagrees (noise) and fills small holes. - Small AI background mask (optional, off by default): needs pip install onnxruntime into rs_env and models/u2netp.onnx. Then it loads the result as normal scan frames, ready for BUILD MESH. How each pass works, and where it can go wrong, is in HOW_IT_WORKS.md. !Quality and detail options <!-- Hardware photos: add docs/images/unit.jpg, unit-2.jpg and real-feed.jpg and they will appear on the project web page automatically. --> Notes, research and tools | Where | What | |---|---| | DESIGN_NOTES.md | What was looked into, what was measured, what was decided and why, what is untested, what to build next. Start here. | | docs/research | The full research report on soft scans and damaged sensors (68 sources), the working notes behind it, a printable PDF in plain English, and the Kinect driver bug report. | | HOW_IT_WORKS.md | What the app does, step by step, written from the code. | | PROJECT_NOTES.md | Short hand-over notes: where things stand and what is open. | | tools | detail_test.py repeats the surface-detail measurements; make_screenshots.py retakes every picture here from made-up data; make_research_pdf.py rebuilds the PDF; bench/ is the stitching benchmark (python tools/bench/bench.py --mode rotary --seeds 0-1). | | scan_target.py | The printable scan target, its compare report, and the turntable marker ring. | --- Source code: The-Dorkknight/scantastic on GitHub
Blip WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN — proof of concept, v0.2.2-wip Turn a tiny radar chip and an old phone into a people-spotting radar 📡 Ever wanted to know who is walking about, and how far away they are, without a camera? Blip does it with a tiny radar chip and a spare phone. The chip sends out invisible radio waves and listens for the echoes. When someone moves, the echo changes, and Blip works out where they are. The phone is the screen. Blip makes its own Wi-Fi network; you join it, open a web page, and a glowing green radar scope appears, like something from a submarine film. Up to three people show up as dots with their distance, direction and speed. No app to install, no internet needed, no cloud, no camera. How it works, in three steps 1. Plug a little ESP32 board into a radar chip (the Ai-Thinker RD-03D) and power it from USB. 2. Join the Wi-Fi network called Blip-Radar on any old phone, tablet or laptop. 3. Open the page and watch the dots move. Walk about and see yourself on the scope! Good things to know - It only sees things that move. Someone sitting very still fades from the scope. - It also bounces off big metal things such as fridges, so a small room can look busy. - A tiny optional screen (an OLED) can sit on the board and show the same picture. Blip finds it by itself when it starts. - You can switch between tracking the one nearest person or up to three. It is a slimmed-down take on Stevee87's Arduino-ESP32-Radarproject, which pairs the same radar with a XIAO ESP32-S3 and an Arduino GIGA R1 + display shield. The drawing is the easy part; a phone already does it. > Required Notice: Copyright Matthew Armstrong (github.com/The-Dorkknight). > Licensed under the PolyForm Noncommercial License 1.0.0 — source-available, free for non-commercial use. Provided as-is with no warranty and no liability. Not a medical device. Radar can see motion through thin walls: respect other people's privacy and the 24 GHz rules where you live. Project started 2026-11-05 10:24. 📘 The whole manual and research notes as one PDF: docs/Blip-manual.pdf (also attached to every release). <p align="center"> <img src="raw.githubusercontent.com" alt="Blip radar scope on a phone" width="260" style="height:auto"> </p> <p align="center"><i>Phone screenshot from the simulator (tools/sim_radar.py).</i></p> Bonus experiment: the Stetho add-on (parked) The idea: use a second, very cheap radar-style module (a £3 CDM324 or HB100 Doppler sensor) as a stethoscope that listens to a heartbeat from a distance. A modded MAX4466 microphone board boosts the signal, and the ESP32 cleans up the sound (ducks knocks, lifts heart, lung and throat sounds, cuts hiss) and plays it live to the phone, to 3.5 mm earphones, or to a small speaker. > Status: abandoned, but kept as an optional install. The radar and phone scope are the project; the stethoscope is parked. The firmware, page and tests are still in the repo and still build, and you can switch it on in Settings, but nobody is working on it. Why, in the author's words: "Needing to build an ultra-low-noise, ultra-high-gain, fast-slew-rate instrumentation amplifier is just too much work for a 'fun' 30-minute project, but I encourage anyone gifted enough with analogue, or mad enough, to carry on my research 😉" Findings and test recordings are in docs/STETHO_SIGNAL_NOTES.md. <p align="center"> <img src="raw.githubusercontent.com" alt="Stetho screen" width="260" style="height:auto"> </p> <p align="center"><i>Simulator screenshot. The real thing never got past the noise floor.</i></p> What exists vs what doesn't | Part | State | |---|---| | RD-03D frame parser (sign bits, resync, ACK tolerance) | Done; unit-tested natively in C++ and Python (tests/) | | Single/multi-target mode command | Fixed in v0.2.1: now wrapped in enable/end-config like the original project (earlier versions probably did nothing) | | "Smart" target filter (own track ids, smoothing, hides flickers, wall reflections, fans) | Experimental, opt-in. Native tests on synthetic scenes pass; not tried in a real room | | Auto-sleep + optional power switches for the RD-03D and the CDM324 | Written, compiles; not tried on hardware | | Phone web UI: scope, targets table, tracker ping, settings, about | Done; tested in Chromium against the simulator | | Flasher page the launcher opens (Quick flash of bundled firmware, or build from source; serial output; error tips) | Done; tested end to end with stand-ins for esptool and PlatformIO (tests/test_flasher.py); the bundled images and the esptool command were checked with the real esptool (image_info: valid); not yet used on a real board | | Wi-Fi hotspot + captive portal + WebSocket/HTTP API | Running on the author's bench (Nov 2026): the page loads and shows live targets | | ESP32-C3 Super Mini and Waveshare ESP32-S3-Pico builds | Compile cleanly (pioarduino, Arduino-ESP32 3.3.12); not yet flashed | | OLED mirror (0.91" 128×32 / 0.96" 128×64 SSD1306) | Works on the author's bench; found automatically at boot. The previews below are rendered by the firmware's own drawing code on a PC | | Stetho audio clean-up on the ESP32 (bump gate, heart/lungs/voice presets, noise suppression, AGC) | Done in fixed point; native test on a synthetic scene passes (knocks −38 dB vs heart sounds, hiss −11 dB) | | Live low-latency audio to the phone, chest-motion trace, heart/breath estimates | Done; tested in Chromium against the simulator (54–83 ms delay there) | | Earphone (delta-sigma) and I2S amp outputs on the node | Written, compiles; not heard yet | | CDM324 + modded MAX4466 front end | Built and tried on a bench (Nov 2026): static fixed by supply caps, but the heartbeat sits at the noise floor even at 2 cm. Abandoned: it needs a custom ultra-low-noise, high-gain instrumentation amplifier (and ideally an I/Q module) | | Making the RD-03D itself into a Doppler stethoscope | Not possible through its UART — see DESIGN_NOTES.md | | RD-03D tracking in a real room | Tracks up to 3 targets, and also big metal objects as you walk towards them; noisy in a small house, outdoor test still to do | | Enclosure | None yet | Bill of materials | Qty | Part | Notes | |---|---|---| | 1 | ESP32-C3 Super Mini or Waveshare ESP32-S3-Pico | Either; both envs in firmware/platformio.ini | | 1 | Ai-Thinker RD-03D — or an HLK-LD2450 (see Radar options) | 5 V, ≥200 mA, UART 256000 baud, 3.3 V logic | | 1 | Old phone / tablet / laptop with a browser | The display | | 0–1 | SSD1306 I2C OLED, 0.91" 128×32 or 0.96" 128×64 | Optional second display | | 0–1 | CDM324 (24 GHz) or HB100 (10.5 GHz) CW Doppler module | Optional "Stetho"; HB100 if you want to run it alongside the RD-03D (see below) | | 0–2 | MAX4466 electret-mic amp board (Adafruit 1063 / GY-MAX4466) | The Stetho amplifier, modded: hardware/max4466-mod.md | | 0–1 | 470 Ω, 100 nF, 220 µF, 3.5 mm socket | Earphone output, hardware/audio-out.md | | 0–1 | MAX98357A I2S amp board + 4–8 Ω speaker | Speaker output | | — | USB-C cable / 5 V supply, wire | The C3's 5V pin can feed the radar for bench tests | Wiring !Wiring, ESP32-C3 Super Mini !Wiring, Waveshare ESP32-S3-Pico | Signal | C3 Super Mini | S3-Pico | Note | |---|---|---|---| | Radar TX → ESP RX | GPIO20 | GPIO12 | UART1, 256000 8N1 | | Radar RX ← ESP TX | GPIO21 | GPIO11 | only used to send the single/multi-target command | | OLED SDA / SCL | GPIO6 / GPIO7 | GPIO17 / GPIO18 | I2C 0x3C | | Stetho: MAX4466 OUT | GPIO1 (ADC1) | GPIO7 (ADC1) | MAX4466 powered from 3V3 | | Earphones (delta-sigma) | GPIO10 | GPIO16 | via 470 Ω / 100 nF / 220 µF | | I2S amp BCLK / LRC / DIN | GPIO3 / 4 / 5 | GPIO13 / 14 / 15 | MAX98357A | | Radar 5V / GND | 5V / GND | VBUS / GND | never 3V3 | Pin numbers live in one place, firmware/platformio.ini; the diagrams are drawn from it. Stetho front end: CDM324 → modded MAX4466 !CDM324 into a modded MAX4466 board > ⚠ DC warning. When you desolder the mic capsule and wire the radar's IF pin onto its pads, also remove the mic bias resistor, or put a 10–47 µF DC-blocking cap in series with the IF lead. Otherwise ~1.5 mA of DC from VCC is pushed into the CDM324's mixer diode. Power the MAX4466 from 3V3, never 5 V. Full steps: hardware/max4466-mod.md. > RD-03D + CDM324 at the same time? They share the 24 GHz band. The RD-03D's sweep passes right over the CDM324's frequency, so expect a buzz in the Stetho audio and possibly a noisier RD-03D. Use an HB100 (10.5 GHz) for the Stetho, or fit a 5 V switch on the radar and choose Radar off while listening (PIN_RADAR_PWR). Details in DESIGN_NOTES.md §11.5. One launcher: flash it, or try it first (double-click) 1. Unzip, then double-click Blip-Linux.sh (choose Run), Blip-Windows.bat or Blip-Mac.command (first time on a Mac: right-click → Open). 2. Your browser opens the Blip Flasher at http://127.0.0.1:8080/ (the red page). Only Python 3 is needed to open it. - Want to look around before you have hardware? The small Radar simulator › button (top right) opens the normal Blip page at /sim, with three pretend people wandering about and a synthetic Stetho signal; its ⚡ Flasher button brings you back. Start the launcher with --lan to open the simulator from your phone too (the terminal prints the address). 3. To flash a real board: plug the board in with a USB data cable, pick the board (C3 Super Mini / S3-Pico), the radar (RD-03D / LD2450) and how to flash, pick the port (or leave Auto-detect), press ⚡ Flash firmware. - Quick flash (default, recommended): writes the firmware that ships in firmware/prebuilt/. Nothing is hidden: the page shows the file, version, build date, size and full SHA-256, checks the file against manifest.json before writing, says whether it was built from exactly the source in your folder, and shows the exact esptool command. The first run installs only esptool into .venv (about 40 MB). No Git, no compiler. - Build from source: compiles your folder with PlatformIO so your own changes go in. The first build downloads the ESP32 toolchain (a few GB; needs the internet and Git; 5–15 minutes), later builds are quick. - The steps light up as it goes (Quick: Firmware → Flash tool → Upload → Boot; Source: Prepare → PlatformIO → Build → Upload → Boot) with a progress bar for the upload and the full log underneath (Copy puts it on the clipboard for a bug report). - If something fails, a tip explains the usual cause: serial-port permission on Linux, the board not in flashing mode (hold BOOT, tap RESET), no board or several boards found, no internet on the first run, Git missing, a port held by another program, your source newer than the bundled firmware. - Afterwards it shows the board's serial output (no terminal needed). Cancel stops any step. - Rather use another tool? Any ESP32 flasher can write firmware/prebuilt/blip-<env>-full.bin at address 0x0 (they are also attached to each GitHub release). 4. Wire the radar as above and power up. The LED on the C3 blinks slowly until frames arrive, then fast. 5. On the phone: join Wi-Fi Blip-Radar, password blipblip. The captive portal should open the scope; if not, browse to http://192.168.4.1/. It is the same green page as the simulator. !Blip Flasher The flasher only answers this computer (127.0.0.1 / localhost): starting a flash needs a per-run token only the page has, and the board, radar and port are checked against fixed lists before anything runs. --no-flash hides it entirely. Prefer the terminal? cd firmware && pio run -e c3-supermini -t upload (envs: c3-supermini, s3-pico, c3-supermini-ld2450, s3-pico-ld2450). After editing web/index.html run python3 tools/embed_web.py (the Flash tab does this for you). Using it | Screen | What it does | |---|---| | !Scope | Scope — ±60° sector, rings every 2 m to 8 m, one coloured blip per tracked person with distance and radial speed. Trails fade over 4 s. Tracker ping is the original project's buzzer, done in the phone's speaker: faster and higher as the nearest person approaches. Mirror L/R flips the picture if you mount the radar the other way round. With the Smart filter on, Show filtered draws what it is hiding as dashed rings (ghost / clutter). | | !Targets | Targets — the numbers behind the blips plus the raw JSON, handy when checking orientation. | | !Stetho | Stetho — the optional CW Doppler channel. Presets: Heart (S1/S2 heart sounds, 20–150 Hz), Lungs (breath hiss), Voice (throat/larynx buzz), Wide, Raw (plain Doppler warble). Listen on phone plays it live; Delay shows how far behind real time you are. Knocks are ducked and limited (red in the trace). Beat lock quietens the gaps between beats once a rhythm is found; Record 10 s → WAV saves a recording for tools/analyze_wav.py; Experiments has ADC averaging and the burst blanker (see docs/STETHO_SIGNAL_NOTES.md). Not a medical device. | | !Chest motion | Chest motion view — the 100 Hz motion trace with heart-rate and breathing rates from the pattern trackers (a ? means only roughly steady); Beat thumps adds a synthetic thump on each detected beat. | | !Clean-up | Clean-up on the node — noise suppression, bump rejection, AGC or manual gain; Sound out of the node — earphones or I2S amp, with its own volume. | | !Settings | Settings — single/multi target mode (also on the Radar page as Track 1 / Track 3), Target filter (Raw / Smart, experimental) with Forget learned clutter, Auto-sleep, OLED (Auto-detect, or a fixed size), Stetho on/off, radar-off-while-listening, hotspot name and password (reboots). | | !About | About — version, build date, board, pin map and counters. | | !Flash | Flash (simulator on a PC only) — pick board, radar, Quick flash or Build from source, and port; see exactly what will be written; watch the board boot. | OLED mirror. Each person is a circle with their distance inside: big digit = metres, small raised digit = tenths, so "1⁹" = 1.9 m. The nearest person is solid. There's no status row, so the scope fills the panel. ◆ top-left = Smart filter on; Wi-Fi icon + number top-right = phones connected; the IP shows bottom-left only until a phone joins. These are exact renders of the firmware's drawing code, not photos: !OLED 128x64 !OLED 128x64, no phone yet !OLED 128x32 How it works Short version: the ESP32 parses 30-byte frames from the radar, keeps the latest three targets, and pushes them as JSON over a WebSocket 20 times a second to whoever is on the hotspot; the browser draws the scope on a canvas. The long version, including the frame format, is in HOW_IT_WORKS.md. The research — radar physics, why the RD-03D can't be a stethoscope and what can, pin choices — is in DESIGN_NOTES.md. Radar options Blip was written for the Ai-Thinker RD-03D (1.25 mm 4-pin socket, 8 m, up to 3 targets). The HLK-LD2450 (Hi-Link, 24 GHz, about 6 m, up to 3 targets with X/Y position) is supported too: - It sends the same 30-byte frame (AA FF 03 00, three 8-byte slots, 55 CC), so the same parser reads it. - It has no RD-03D configuration commands, so Blip skips the mode command. Single (nearest) is picked in firmware instead. - Use the c3-supermini-ld2450 or s3-pico-ld2450 build environment (or add -DRADAR_LD2450=1). /api/status reports "model":"ld2450" while it is running. - Its pins are on a 2.54 mm header, so jumper wires work. Check the labels on the module: its TX goes to the board's RX pin, and its RX to the board's TX. - Weaker than the RD-03D on people who sit very still (the vendor notes this beyond about 2 m), and range is about 6 m. - Still 24 GHz, so it clashes with a CDM324 in the same way. Use an HB100 for Stetho, or the radar power switch. - Not tested on hardware yet. Check the angle direction on the Scope first (Mirror L/R in Settings if left and right are swapped). Repository map firmware/ PlatformIO project (src/main.cpp, include/rd03d.h, tracker.h, audio_dsp.h, stetho.h, oled.h, oled_draw.h, web_ui.h) firmware/prebuilt/ bundled whole-chip images for the four builds + manifest.json (checksums, version, source hash) web/index.html the phone UI (single file; embedded gzipped into the firmware) web/flasher.html the flasher (served by the PC tool only; never in the firmware) web/flash_home.html the red home page the launcher opens, with the flasher inlined tools/ sim_radar.py, flasher.py, serial_tail.py, make_prebuilt.py, make_pdf.py, embed_web.py, draw_illustrations.py, rd03d_py.py, tracker_py.py tests/ native C++ tests (parser, audio DSP, tracker, OLED render), Python parser + tracker cross-check, flasher (with fake_pio.py), launcher test hardware/ wiring, MAX4466 mod (with the DC warning), earphone / I2S amp outputs examples/ synthetic RD-03D frames for replay; dsp_before.wav / dsp_after.wav docs/ GitHub Pages site + images + Blip-manual.pdf (built by tools/make_pdf.py) --- Source code: The-Dorkknight/blip-radar on GitHub
Bat Tree-Bar Proe !The Bat Tree-Bar Saloon WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN · version 0.2.0-wip · source-available · non-commercial Battery percentage and time left at a glance, with a click for the details: charge/discharge current, power, voltage and battery health. In the spirit of BatteryBar, built to run on Windows 11 and Linux (and, experimentally, macOS). > Licence and no warranty. Source-available under the PolyForm Noncommercial License 1.0.0: free to use, change and share for non-commercial purposes; commercial use needs separate permission. Provided as is, with no warranty and no liability. This is not legal advice. Bat Tree-Bar Proe only reads your battery; it never changes a setting. 📘 The whole manual and research notes as one PDF: docs/BatTreeBarProe-manual.pdf · Changelog · Build history · How it works · Design notes A tribute to BatteryBar The name is a pun on BatteryBar Pro, the Windows taskbar battery meter made by Osiris Development (osirisdevelopment.com). It showed the battery level and the time left or time to full right on the taskbar, with a Pro version adding graphs, warnings and more. That is the idea this project follows, rebuilt from scratch for Windows 11 and Linux (the author reports the original does not run there). This project is not affiliated with Osiris Development, shares no code with BatteryBar and is not a substitute for it; if BatteryBar still works for you, please go and use the original. Project started 2026-11-11 11:01. Renamed from "ChargeGlance" the same day, before any public release. !The bar while charging What it looks like A tiny always-on-top bar shows the battery icon, the percentage and the time left (or time until full). Click it and the details open. Drag it anywhere; it remembers where you left it. Right-click for the menu. | On battery | Charging | |---|---| | !popup on battery | !popup charging | These screenshots use the built-in simulated battery (--demo), because they were taken in a sandbox with no battery. The layout is the real one. Using it | You do | You get | |---|---| | Look at the bar | 73% 4h 24m on battery; 64% 34m (blue icon with a bolt) while charging; 100% full when full; 80% on AC when plugged in but not charging | | Click the bar | Popup: charge or discharge current, power, voltage, energy now/full, health (full-charge capacity vs new), cycle count, temperature, mains status, a 30-minute power graph. Click again or press Esc to close | | Drag the bar | Moves it; position is saved | | Right-click the bar | Details, Start at login, Always on top, Allow over the taskbar (experimental), Move to bottom right, Quit | The popup says in brackets where the time estimate came from: rate (energy left divided by smoothed power), trend (percent slope over the last few minutes) or os (the number your operating system reports). Command line python3 src/main.py --version python3 src/main.py --once # one reading as JSON: paste this in bug reports python3 src/main.py --text # no window, one line every 5 s python3 src/main.py --demo # simulated battery (also: --demo charging, --demo full) python3 src/main.py --autostart on|off|status # start at login python3 src/main.py --force # start even if it thinks a copy is running Settings and a small log live in ~/.config/bat-tree-bar-proe/ (Linux), %APPDATA%\Bat Tree-Bar Proe\ (Windows) or ~/Library/Application Support/Bat Tree-Bar Proe/ (Mac). What works, what does not | | Linux | Windows 11 | macOS | |---|---|---|---| | Code written | yes | yes | yes | | Reading logic unit-tested | yes, with fake battery folders | parser only, on a hand-written sample | parser only, on a hand-written sample | | Run on a real battery | not yet (built in a sandbox with no battery) | not yet | not yet | | Window runs | yes (Xvfb, simulated battery) | not run | not run | | Graphical installer / uninstaller | yes (Xvfb, into a temp folder) | code written, not run (Start Menu shortcuts, Run key, Apps list entry) | code written, not run (LaunchAgent, app folder) | | Fuzz and edge-case tests (garbage readings, suspend, clock jumps, corrupt settings, HiDPI) | yes | parser only | parser only | Project layout src/main.py window and command line · src/battery_source.py Linux, Windows, macOS readers · src/estimator.py time estimates · tests/ unit tests · tools/ screenshot rig, PDF and history scripts. Run the tests: python3 -m unittest discover -s tests -v Created by Matthew Armstrong (The-Dorkknight). --- Source code: The-Dorkknight/bat-tree-bar-proe on GitHub