myscan/RE_colour_stitch.md

RE notes: colour, exposure, geometry, lift-off, scan button (Dacuda Scanner Mouse for Mac 2.4)

Static analysis only (no device access). Tags: [V] verified in disassembly or strings, [I] inferred. Addresses are virtual addresses. The main app Contents/MacOS/Scanner Mouse and libSLAMScanSystech.dylib are i386 thin Mach-O. UVCControl.framework is fat, and its x86_64 slice was used (addresses with "uvc:"). The app is stripped except for template symbols. I located code through string xrefs and RTTI vtables.

0. Scoping facts

• libSLAMScanSystech.dylib is NOT our device. [V] It is the driver for a different, network-attached "Free"/Systech mouse. It contains ffmpeg and RTSP code plus HTTP/XML commands: cmd/gain, cmd/rgbgain (<Red><Green><Blue>), cmd/exposure (Delay_us, Duration_us) and cmd/laser. It is used only by Hal::HalFree. Our USB/UVC mouse is Hal::HalLuckyCat + Hal::OVMouseManager (mouse "LuckyCat", OV bridge), with all stitching and registration code inside the main app (libs/Core, libs/Hal/Driver/...).
• Per-device calibration lives in the mouse's EEPROM (see section 1.4). The values compiled into the app are only fallbacks, and they are for an LG LSM100 (productString = EProduct_LG_LSM100). Anything below tagged "compiled default" is not necessarily what the Hama unit contains.

1. Colour / white balance

1.1 Sensor and bridge writes (complete list) [V]

OVMouseManager::sccbWrite(id,reg,val) is at 0x138b020. It has 36 call sites, and all were enumerated. With id=0x42 (image sensor via the bridge proxy BD/BE/B8) the app writes only these registers:

Sensor reg	Written by	Value
0x00	setGain(double) 0x1389160; deferred writer 0x13892f0	OV gain byte, see below
0x01, 0x02, 0x03	setWhiteBalance(int a,int b,int c) 0x13893e0 (writes at 0x1389732/53/76)	reg1=a, reg2=b, reg3=c
0x16 and 0x19	setImageWindowOffset / setYBaseOffset 0x1389bf0, 0x1389e96, 0x138a7af	window start/stop rows (value derived from yBaseOffset)

The app never writes sensor reg 0x13 (AEC/AGC/AWB) or any other sensor register. It relies entirely on firmware defaults for AWB and AGC. Bridge-register writes (id=0x88) are D8, ED, EC, 2D, E7, E6, DC, A1..A5 and BD/BE/B8 (proxy).

Gain encoding (reg 0x00, 0x1389214-0x13892af). The input is imagerGain, a double, clamped to [0,16]. The OV format has bits 7..4 as doubling stages and bits 3..0 as the fraction:

v = clamp(g,0,16); r = 0
if v>=16: r|=0x80; g/=2
if v>=8 : r|=0x40; g/=2
if v>=4 : r|=0x20; g/=2
if v>=2 : r|=0x10; g/=2
r |= (g<2) ? int((g-1)*16) : 0x0F      # g=1.0 -> reg0 = 0x00

Colour gains. HalLuckyCat::open (0x1331ae0) calls setWhiteBalance(this+0x2fc, +0x300, +0x304) at 0x133312f. These three ints come from the config getters at 0x14452f0, 0x1445360 and 0x14453d0. Their property offsets (+0x108, +0x138, +0x168) correspond to gainR, gainG and gainB in the HardwareData config ctor (0x1441300), so:

• sensor reg 0x01 = gainR, reg 0x02 = gainG, reg 0x03 = gainB in the app's naming [V for the plumbing].
• Which physical channel each register controls is [I]. The standard OV7725/7740 map is 0x01=BLUE, 0x02=RED, 0x03=GREEN. If that applies here, the app's "gainR" really lands in the blue-gain register. Test empirically.

Compiled defaults (LSM100 config ctor 0x1441300) [V]:

Name	Default	Note
gainR / gainG / gainB	150 (0x96) / 89 (0x59) / 64 (0x40)	the app's reg1 / reg2 / reg3
imagerGain	1.0	reg 0 = 0x00
exposureTimeUs	270	min 100, max 1200
yBaseOffset	105
laserReadOutDelay	0.9
clipOffset	"8 28 8 12"	ROI margins in px, order not verified [I]

Starting point for a green cast (untested [I]): reg0=0x00, reg1=0x96, reg2=0x59, reg3=0x40. If the channels turn out swapped, swap R and B. The proper values are in the EEPROM (1.4).

1.2 Software colour correction on decoded frames [V]

The preprocessing pipeline (Core::PreprocessorFactory) is, in order: ImageClipper -> NurbsColorBalancerPolicy -> GammaEnhancerPolicy -> Undistorter (UndistorterBailey = lens undistortion) -> FAST corner detector -> ThresholdController.

• Colour balancer = ColorBalancerLinearNurbsScaler (libs/Core/Preprocessor/ColorBalance/...). It is a per-pixel linear flat-field correction out = slope*in + intercept. The maps come either from /slope.bin /intercept.bin /black.bin /white.bin or are computed from the per-device NURBS surfaces nurbsModelBlack and nurbsModelWhite (shading and white reference) in HardwareData ColorParams. This corrects vignetting and colour cast in one step. There are IR and UV variants (IRBalancer, UVBalancer). Target brightness: colorDestBrightImage = 250 [V, default]. colorDestDarkImage was not extracted. A simple per-channel white balance alternative: normalise each channel so a white reference maps to 250.
• Gamma enhancer (GammaEnhancer.cpp, enableGammaEnhancement) builds a LUT by piecewise-linear interpolation (function 0x14b4eb0). The 17-point LSM100 curve at 0x1dc8480/0x1dc84c4 is: x = 0,4,8,16,32,40,48,56,64,72,80,96,112,144,176,208,255 y = 6,17,27,44,74,86,96,106,115,123,131,145,157,181,202,224,255. A separate 256-entry "LITEARRAY" LUT exists at 0x1dc8508/0x1dc8908. Which LUT our product uses is unknown. The enabling setting is enableColorEnhancement / enableColors (UI sliders for brightness and saturation).
• Hardware-data fields the colour code consumes: lambda, lambdaNormFactor, nurbsModelSize, nurbsSmoothingFactors, nurbsNSmoothingIterations, gainR/G/B, exposureTimeUs, imagerGain.

1.3 Mouse sensor-module variants known to the app [V]

"Scarab", "LuckyCat (Largan)", "LuckyCat (Newmax)", "LuckyCat (Kinko)", "(Kinko, restricted)", "(Kinko, r2)", "(Kinko, r2 restricted)". These strings are stored in the HardwareData info block.

1.4 Per-device calibration in EEPROM (HardwareData) [V for layout, I for blob format details]

Read routine OVMouseManager::readBinaryData (0x138c4e0); write routine at 0x138cc90. Both use OVIF_DaEEPROMRead/Write (uvc: 0x383f/0x380e), which call -[CameraControlAppDelegate EEPROMRead:withStartAddr:withLength:] (uvc: 0x1bb9).

EEPROM map:

Address	Content
0x3000	u16 LE: length N of the blob, valid if 0 < N <= 20000 (0x4E20)
0x3002	4 bytes: checksum (DaReadBinaryDataChecksum)
0x3006	N bytes: blob
0x7EB5	64 bytes: mouse ID / serial (ffff... when erased)

Blob = boost::archive::binary_iarchive (HardwareDataSerializer::fromRawData, 0x14c3731) holding, in order, RoiParams, SensorParams, UndistortionParams, ColorParams, InfoParams. There is also an "archiveVersion" check, which produces "Unknown archive version" and "Device contains an old version of UserData" errors. Field names (from the serializer string table 0x1b19c02..):

• Sensor: exposureTimeUs, imagerGain, laserReadoutDelay, metersPerLeftMouseUnit, metersPerRightMouseUnit, camToLeftMouseAngle, camToLeftMouseVec, camToRightMouseAngle, camToRightMouseVec, gyroDegPerStep, gyroBias, yBaseOffset.
• Roi: roiX0, roiY0, roiX1, roiY1.
• Undistortion: clipOffset, focalLength, principalPointX/Y, distModel, distCoefficients, tiltH, pixelSize.
• Color: gainR/G/B, lambda, lambdaNormFactor, nurbsModelBlack/White, nurbsModelSize, nurbsSmoothingFactors, nurbsNSmoothingIterations.
• Info: fingerprint, calibrationTime, avgReprojErrorIntrinsic, avgReprojErrorHomography, archiveVersion, mouse-model enum, product/vendor/odm strings.

EEPROM read protocol (uvc: 0x1bb9) [V]. It uses XU selector 3, a 33-byte buffer. "ReadBuf" means SET_CUR sel 3 followed by GET_CUR sel 3 (uvc: 0x25bb). "WriteBuf" means SET_CUR only (uvc: 0x2680). Requests are 0x21/0xA1, wValue 0x0300, wIndex 0x0600, wLength 33:

ReadBuf [01, addr_lo, addr_hi, len_lo, len_hi, ...]   # set address+length
WriteBuf[02, ...]                                      # start
repeat ceil(len/32): ReadBuf[03, ...] -> response bytes 1..32 = next 32 data bytes
WriteBuf[05, ...]                                      # end

The write protocol (0x1a34) is cmd 1 (addr, len), 6, then 7 per 32-byte chunk, and 9 to finish. The len < 0x7fff check is in the write path. Do NOT use the write path casually. The EEPROM holds the calibration, and writes are signed (RSA, :/calib_rsa.pub.txt).

Strong recommendation: use the selector-3 read to dump 0x3000..0x3006+N from the user's own mouse. That yields this unit's real gainR/G/B, imagerGain, exposureTimeUs, laser scale and positions, pixelSize, lens model and NURBS white/black surfaces. I did not touch the device, so none of the blob format is confirmed on real data.

2. Exposure

• Formula [V] (OVMouseManager::setExposureTime 0x1389e90): E6 = floor(ms*49.23 + 0.5) (the 49.23 is a double constant at 0x1cfaf80), clamped 0..255 by the bridge byte.
• The app calls it only from HalLuckyCat::open (0x1332e04): ms = exposureTimeUs * 0.001 from HardwareData. Default 270 us -> E6 = 13; limits 100..1200 us -> E6 5..59. I found no runtime caller that varies exposure. I checked the only direct caller and every call [reg+0x3c] (the setExposureTimeMs vtable slot) in the binary; none is exposure-related. [V for the callers, I for the conclusion "no AEC loop for LuckyCat".]
• The PID settings exist but look calibration-only [I]. In the DacudaSettings ctor (0x1470ff0), next to OpticalModuleValidator, they are pidGainP=1.8, pidGainI=0.01, pidGainD=0.3, pidGoal=240 [V values], alongside ignoreOmvExposureTime. The goal 240 is presumably a brightness target, probably a bright-pixel statistic, for the optical-module calibration tool. A separate ThresholdController (gainP=0.01, gainI=0.001, minThreshold=20, maxThreshold=150) tunes the FAST detector threshold, not exposure.
• So for our own AE: the vendor target brightness is ~240 on the bright part, with exposure kept in 100..1200 us (E6 5..59). Our 0..255 range is wider than the vendor ever uses. LED strobe time is the exposure.
• Laser read position, bridge reg DC [V] (0x138a1d0): DC = floor(min(pos,0.9)*128 + 0.5), so the default 0.9 gives 0x73 (115). The app refuses it while streaming.

3. Stitching geometry

Pipeline: record -> SensorLL::update (0x12f5c40) -> LaserCheckerGeometric::check (0x12fe6b0) -> PoseEstimatorLL::estimatePose (0x12f14c0, vtable 0x1d9a208+).

• Record fields used [V]: OVMouseData int fields at +0x74/+0x78 = laser1 dx, dy and +0x80/+0x84 = laser2 dx, dy (cvtsi2sd at 0x12f5d91.. and 0x12f14df..). The Sq fields sit at +0x7c and +0x88 and are not read in SensorLL::update.
• Per-laser calibrated vector [V structure]: v_i = M_i*(dx,dy)^T + t_i. M_i is a 2x2 matrix at estimator-data +0x84/+0x8c/+0x94/+0x9c (laser 1) and +0xb4/+0xbc/+0xc4/+0xcc (laser 2); t_i is at +0xa4 and +0xd4. It is built in the driver factory (0x12ce020) from camTo{Left,Right}MouseAngle and metersPer{Left,Right}MouseUnit / laserScaling. The pose (x, y, phi) is then a 2-point rigid fit: translation from the displacements and rotation from the difference of the two displacement components perpendicular to the laser-laser baseline, divided by the squared baseline length (division by 2*L^2 visible at 0x12f17d9). Laser dy is negated in the checker adapter at 0x12fe620 ((dx,-dy) for both lasers).
• Scale [V]: laserScalingLuckyCat = float 0x379f6230 = 1.9e-5 m per laser count (Driver config ctor 0x1422b40, compiled default). The per-device metersPerLeftMouseUnit / metersPerRightMouseUnit in EEPROM override it [I]. That is ~1337 counts/inch.
• Laser positions [V, LSM100 compiled default; per-device in EEPROM]: left (0.025, 0.063) m, right (0.025, -0.014) m, both angles 0. So the lasers are 77 mm apart along y, 25 mm from the camera axis in x. Our empirical values give a baseline of 1.9e-5/4.4e-4 = 43 mm and ~0.057 mm/px, so the Hama unit differs from the LSM100 defaults, as expected. Use the EEPROM values.
• Camera pixel size: the validator expects 75..79.4 um per pixel (geomExpectedPixelSizeMin/Max 7.5e-5..7.94e-5 m), i.e. 320-339 dpi native, for LG modules. gridUnitInMeters = 1.058333e-3 (1/24 inch), subsamplingFactorOM = 1.2. The authoritative number is pixelSize in the EEPROM.
• Orientation: my empirical result (frames transposed + mirrored: laser dx ~ image y, laser dy ~ image x with sign flip) is consistent with the dy negation and axis-swapped matrices above. The exact image flip in the app is applied by mirrorConfiguration (profile int, default 1 / user 2 in WING profile) plus the clip and undistort stages. Not resolved.
• Output DPI: user setting scanResolution (enum index, default 3) -> Core::setResolution(int dpi) (0x112fbd0), and BakerQt falls back to "native camera resolution" if undefined. The index->dpi table was not found (labels probably in .qm resources). Not resolved.

4. Lift-off / frame rejection

• LaserCheckerGeometric::check(l1, l2) (0x12fe6b0) [V logic]:
  1. If 0 < |v1| <= 2 and 0 < |v2| <= 2 (tiny motion on both lasers) -> OK.
  2. Otherwise, with u = normalised (p_right - p_left) from camToLeft/RightMouseVec (setter 0x12fe570), compute d = dot(v1,u) - dot(v2,u) and ratio = |d| / max(|v1|,|v2|). If ratio <= sensitivity -> OK. Else the result is OK only if |d| < 4 counts, otherwise invalid (lifted or slipping). The sensitivity is the liftoffSensitivityLaser config (default 50; profile ASD_SLAMLITE uses 21), passed to the ctor 0x12fe4f0 and stored at +0x6c. A raw ratio can never exceed 2, so the value is probably pre-scaled or the property is another one. The units are unresolved. [I] Also laserDoubleCheckThreshold, laserExpectedRatioMax, laserExpectedNumStepsMin (8000) are calibration-validator settings.
• Second checker (0x12fd330, from SensorLL::update) [V structure, I meaning]: keeps circular buffers of the last laser integer deltas (4 channels), and tests max |delta| against fixed limits (3, 1, 8, 9, 12) with a state flag. It logs "LiftOff1" / "LiftOff2". It looks like a stuck/static-sensor test.
• Surface-quality bytes (record bytes 14/15, i.e. Sq fields) and byte 16 / flag bits: I found no thresholds applied to them in the app. They are copied into SensorDataLL (laser1Sq, laser2Sq) but unused by the pose estimator or checker I decoded. [V for "not in SensorLL::update", I for "not used elsewhere"]. Lift detection is geometric (laser disagreement) plus Core states: ScanningState -> LiftoffState ("Stop after lift-off"), image-based IntensityChecker (Utilities/Core/IntensityChecker.cpp), BookBorder match failure, "The mouse was lifted off when starting the scan". Stop reasons in the UI: Buffer Full, lift off, user stop, USB capacity exceeded.
• Other thresholds: minimumBlenderTranslation 0.0075 m (7.5 mm), minimumBlenderRotation 0.0785 rad (4.5 deg), maximalBlenderConsecutiveDiscard 15, minimumBouncerTranslation 0.0015 m, minimumBouncerRotation 0.01 rad, maximalConsecutiveDiscard 15, minimumCoreOverlap 0.2, nFeaturesMin/Max 10/1000, ratioThresholdFast 0.6, ratioThresholdQuality 0.7.

5. Scan button

• Register [V]: bridge reg 0xBC, bit 0 (active high). OVIF_GetScanBtnStatus (uvc: 0x389a) edge-detects against the previous sample: returns 0x11 on a press edge (0->1), 0x10 on a release edge (1->0), 0/1 for steady state, -1 for the first sample, 0x99 on read error.
• Polling [V]: OVMouseManager button thread (loop at 0x138b4d0, call at 0x138b79e). Default interval stored at this+0xbc is 0x64 = 100 ms (store at 0x1390681, so I assume the ctor), changeable with setScanButtonPollingInterval(int). Posts ScanButtonPressedEvent / ScanButtonReleasedEvent. The loop takes a mutex around the register read, which is shared with video control, so reads are serialised.
• Semantics [I, from strings and config]: ControlWindow::scanButtonPress -> "Start scan, initiated with scan button press (not known yet if single swipe or regular scan)". Press = start. Settings singleSwipeEnabled, singleSwipeTime = 400 ms: a press held longer than that is "single swipe" (scan runs while held and stops on the release event, "Got ScanButton Released event / Single swipe is active"). A short press is a regular scan that continues after release and stops on the next press ("user stop") or on lift-off, buffer full or USB error. Pressed events are ignored while a modal dialog is open. Also: "Press scan button to begin scanning".
• The HID report byte0 bit7 we already see carries the same button state.

6. What I could not determine

• This unit's real EEPROM contents (gains, scales, laser positions, pixel size, NURBS surfaces) and the boost-binary blob layout. Reading the EEPROM (section 1.4) is the way to get them.
• Which of reg 1/2/3 is physically R/G/B on this sensor. Test empirically.
• The meaning and scale of liftoffSensitivityLaser; how Sq bytes 14/15, byte 16 and the flag bits are used (nothing found).
• The scan-resolution index -> dpi table, and the exact final image flip.
• Whether the firmware turns on AWB/AEC itself (the app never writes sensor reg 0x13).

7. Sensor proxy protocol (SCCB 0x42 via bridge BD/BE/B8)

Source: OVMouseManager::sccbWrite 0x138b020, low-level proxy write 0x1390a30, proxy read 0x1390860, generic read dispatcher ~0x13904f0. "Bridge reg" = OVIF_SCCBRead/Write(0x88, reg, ..), i.e. XU sel 2 cmd 0x80/0x00 (UVCRead/WriteUSBReg).

State flags (V) in OVMouseManager: +1 = standby (set at 0x138afaf after D8=00 and D8 reads 0xFF; cleared 0x138b459 after D8=E0 enable-mouse), +2 = mouse mode, +3 = scan streaming (set 0x138aa5e after VideoRun, cleared 0x13864b3 in stopVideo). +1 is NOT cleared by startVideo, so it stays 1 during scan.

Gate (V):

• Proxy read 0x1390860 and proxy write 0x1390a30 both start with if (this[+1]==0) return (no bridge traffic at all). So in mouse mode the app silently does nothing for sensor accesses. Only standby or scan (+1==1) works.
• sccbWrite(0x42) additionally requires this[+3] || this[+1].

Proxy write sequence (V), 0x1390a30(reg,val):

1. Poll bridge B8 up to 100 times; break when B8 == 0. Between polls it sleeps via boost sleep_until(now + 10000 us) (10 ms, I for the unit being us). (First read happens before any sleep.)
2. If still nonzero after 100 tries: return 1 (error). Otherwise:
3. write BD = reg; write BE = val; write B8 = 1. Return 0. No poll after the B8=1 write.

Proxy read sequence (V), 0x1390860(reg):

1. Same pre-poll: B8 until 0 (100 tries, 10 ms sleeps). On timeout return without reading.
2. write BD = reg; write B8 = 2.
3. Poll B8 until it reads 0 (up to 100 reads, no sleep in this loop, tight loop).
4. Result = bridge reg BE (single read, the value returned as the sensor register value). No BE write for reads. No F1 write.

Verify and retry in sccbWrite(0x42) (V): write(reg,val) via 0x1390a30, then read-back via 0x1390860 and compare with val. On mismatch: loop up to 10 times: sleep 10 ms, rewrite, sleep, read back, compare. Returns 0 on verified match, 1 on failure. The app's sensor writes therefore always read back.

Which path for id 0x42 (V): the proxy only. OVMouseManager calls OVIF_SCCBRead/Write exclusively with id 0x88; it never passes 0x42. The UVCControl path (ReadSCCB/WriteSCCB uvc: 0x12ce/0x13a6: if id != cached g_sccbID, bridge write F1=id, then XU sel 2 cmd 0x81 / 0x01) exists in the framework but is unused by the app. The app never writes bridge F1 anywhere (no 0xF1 immediate in OVMouseManager or OVInitUVC).

Implication for your observation (I): your sequence (BD=reg, B8=2, poll B8, read BE) matches the app's read exactly, and the app too works only in standby/scan. Differences to try: (a) the app writes nothing else first, so the zero BE may be real, e.g. the sensor not yet powered/clocked, or reg values genuinely 0 in standby; (b) try the same read while in scan mode (D8=E1 acked 0x99), where the app also uses it (it writes gain/colour gains at open in standby and window regs 0x16/0x19, and verifies each); (c) do the pre-poll (B8==0) before writing BD; (d) as a control, do a write of a known register (e.g. 0x00 gain, B8=1) and read back with the above protocol; (e) an F1=0x42 plus XU cmd 0x81 read is an alternative the firmware supports (UVCControl) but the app never exercises it, so it is untested by the vendor app. I cannot say from static analysis why BE reads 0 in standby.