wonder

Flying Descent (1995) with a SpaceMouse on a Mac

2026-09-19T00:00:00Z

Flying Descent (1995) with a SpaceMouse on a Mac

A 3Dconnexion SpaceMouse is a CAD tool, a little puck you push and twist to move around a model, and on a Mac it doesn't do much else. Its driver also has a keyboard emulation mode, controlled by an XML file you write for each program. I wrote one for DOSBox, and now I fly Descent, the 1995 shooter, with one hand on the puck. Descent is a six-degrees-of-freedom (6DOF) game, and so is a SpaceMouse, so all six axes work at the same time: pitch, yaw, roll and all three slides.

Why Descent and a SpaceMouse

In Descent you fly a ship through mines, and the ship can move in any direction. That is six degrees of freedom, or 6DOF: three axes of translation (forward and back, left and right, up and down) and three of rotation (pitch, yaw and roll).

A SpaceMouse reports the same six. Pushing the puck moves it along x, y and z, and tilting or twisting it rotates it around those axes, which are the rx, ry and rz in the reports below. So the puck's translation axes line up with Descent's slides and its rotation axes line up with pitch, yaw and roll. Forward and back on the puck becomes accelerate and reverse in the game. Because the puck reads all six axes at once, I can pitch, slide and roll at the same time.

The problem is that the puck sends raw axis data, and a DOS game running inside an emulator only understands keystrokes.

What the puck sends

Before touching the driver I wanted to see what the device sends, so I wrote a small Swift tool using Apple's IOKit HID API. It finds 3Dconnexion devices by vendor ID 0x256F, prints the HID report descriptor when one connects, and decodes the reports as they arrive.

There are three kinds of report. Report 1 carries translation (x, y, z) as three little-endian signed 16-bit numbers. Report 2 carries rotation (rx, ry, rz) in the same format. Report 3 carries the buttons as bits in a single byte, and my SpaceMouse Compact has two. If the tool can't open the device, the terminal probably needs Input Monitoring permission.

The data is easy to read, but it doesn't help with the game. For that I needed the driver to translate it.

KMJ mode

3DxWare has a mode called KMJ, for Keyboard, Mouse, Joystick. Instead of handing an application 3D motion data, the driver generates ordinary input events from it. An XML file, one per process, controls what it generates.

Each axis is split into two entries, one for pushing and one for pulling, and each entry has its own key. When the puck moves past a threshold in that direction, the driver holds the key down. DOSBox sees a keyboard.

The mapping

I worked out the axes and deadbands with Claude's help, then tuned signs and thresholds in a Notepad test profile before carrying them over. The file targets a process named DOSBox.exe. This is the mapping I ended up with:

Motion	Descent action	Key	Deadband
Push forward (Y−)	Accelerate	A	120
Pull back (Y+)	Reverse	Z	120
Slide right (X+)	Slide right	Keypad 9	60
Slide left (X−)	Slide left	Keypad 7	60
Lift up (Z−)	Slide up	Keypad 8	80
Press down (Z+)	Slide down	Keypad 2	80
Pitch (Rx+)	Pitch up	Up arrow	100
Pitch (Rx−)	Pitch down	Down arrow	100
Yaw (Ry+)	Turn left	Left arrow	130
Yaw (Ry−)	Turn right	Right arrow	130
Roll (Rz+)	Bank right	E	80
Roll (Rz−)	Bank left	Q	80

The deadband is how far you have to move the puck before the key fires, in raw sensor units on a scale of plus or minus 512. I gave forward and yaw the largest values, because those are the axes your hand moves by accident while resting on the puck. In the file the keys are USB HID usage IDs (page 0x07), so Keypad 7 is 5F and Z is 1D.

Two settings in the file are worth knowing about. AxisFilter is None. The alternative, Dominant, lets only the strongest axis through at a time, which makes it impossible to turn and slide together, and flying in Descent means combining axes. The repeat style is PressAndHold, so holding the puck over holds the key down instead of firing it repeatedly.

My file is here if you have a SpaceMouse of your own: DOSBox-KMJ.xml. It's heavily commented, with one entry per half-axis.

Caveats

The profile matches a process called DOSBox.exe, so it fits how I run the game. Another emulator or build needs its own entry. It also ignores the two buttons, which my Swift tool can read and the XML doesn't map. And each axis is either on or off, since the driver is pressing keys, so there is no proportional control the way an analog joystick gives.

If you want to try this

Install 3DxWare, find its profile folder, put the XML in it, restart the driver and launch DOSBox.

Apple Image Capture "lossless" TIFF scans might secretly be JPEGs

2026-09-16T00:00:00Z

Apple Image Capture "lossless" TIFF scans might secretly be JPEGs

If you scan with a Canon CanoScan LiDE 400 using Apple's Image Capture on macOS 27, you get JPEG compression artifacts in every file, even when you save in lossless formats like TIFF or BMP. Even though Image Capture is saving in a lossless format, the data it receives from the scanner has already been JPEG-compressed for transport.

The fix is to skip AirScan and talk to the scanner over Canon's own USB protocol, which delivers uncompressed sensor data. That protocol is already implemented in open source by SANE.

What I saw

I bought a LiDE 400 for receipts, mail and old family photos. It has no macOS driver from Canon. It doesn't need one: macOS finds it over AirScan and Image Capture just works.

Then I zoomed in on a 300 dpi scan saved as TIFF and saw DCT compression artifacts, the signature of JPEG. Saving as BMP showed the same artifacts. Picking a lossless format in Image Capture's own menu made no difference, and the app gave me no hint that it wouldn't.

A 300 dpi scan saved as a TIFF by Image Capture, enlarged. The blocky speckle around the letters is JPEG compression, in a file format that has no JPEG in it.

Two other programs on the same machine didn't produce them: VueScan and SANE's scanimage. Both gave clean scans of the same page. So the scanner could do better, and Image Capture was getting something worse than the sensor produces. Nobody told me, and I only found out because I looked at pixels.

The same kind of scan from SANE's scanimage, enlarged. Cleaner edges and a smoother background. The two crops aren't at identical zoom.

What AirScan is

AirScan is Apple's name for driverless scanning. Under the name is eSCL, a protocol (from Mopria, based on HTTP and XML) that lets a client ask a scanner what it can do and then request a scan. Discovery uses Bonjour (_uscan._tcp), the scanner publishes a capabilities document at /eSCL/ScannerCapabilities, and you request a scan by posting a settings document. The pages come back as image data over HTTP.

For a scanner on the network this is great. Nothing to install, and any client that speaks eSCL works. For a USB scanner it works through the same protocol carried over USB (the LiDE 400 has USB interfaces for this), and macOS exposes it as a local eSCL service.

The catch is in that capabilities document. The scanner declares which document formats it can return, and the LiDE 400 lists exactly two: image/jpeg and application/pdf. There is no raw, no PNG, no TIFF. Whatever the client does with the data afterwards, the lossy step has already happened in the scanner's firmware. Image Capture, ImageCaptureCore and any custom eSCL client all get JPEG, so none of them can fix this. Canon chose to offer nothing else over AirScan, and Apple chose to present TIFF and BMP as save options anyway, without saying that the pixels are already degraded.

I checked this against the device when I started the project and recorded it in my notes. I haven't re-run the check for this post, because the scanner isn't plugged in right now.

How open source already solved it

The scanner also speaks a second, older language. Its three USB interfaces are all vendor-specific, and interface 0 carries Canon's "pixma" protocol (generation 5). That's the protocol Canon's own drivers use, and it returns uncompressed image data.

Canon doesn't publish a specification. The SANE project's pixma backend (backend/pixma/pixma_mp150.c) works it out and implements it. That's why scanimage gives clean scans: it never touches AirScan. Everything I did next stands on that work, and I'm grateful for it.

SANE also has a debug mode that logs every USB transfer:

SANE_DEBUG_PIXMA=20 scanimage -d pixma:04A91912_… --resolution 300 --mode Color …

That log turned out to be the most useful thing in the whole project.

What I did with it

I wanted a native macOS app: no Homebrew, no bundled C libraries, nothing to keep building. (I'd started with a Python prototype, scanscan, and retired it in favour of the native rewrite, swiftscan.) So I ported the LiDE 400 path from pixma_mp150.c to Swift on top of Apple's IOUSBHost framework. It's about one scanner's worth of code, and I'm not trying to support others.

Then I checked it against SANE. A full-bed 300 dpi colour scan from my Swift driver and one from scanimage with the same settings came out the same size, with a mean absolute difference of about one level, which is sensor noise. There's no JPEG block pattern. It was also a little faster: about 11 seconds against 14.6.

What I added

The driver is a translation, so what's mine is mostly around it.

The biggest piece is the protocol itself, written down from evidence. I turned SANE's debug logs into a document describing the generation 5 protocol as it appears on the wire: the framing, the checksums, the XML job messages, the command sequence and the layout of the image data. It's written from captures rather than from SANE's source, and every claim says which capture backs it. Where I don't know what a field does, the document has an "unknowns" table with ideas for how to find out, rather than a guess.

The packet layouts are also available in machine-readable form, as Kaitai Struct definitions. I wrote a small capture format (.pxtrace) and a script that converts SANE's logs into it, so traces from SANE and from my driver can be compared directly.

Those traces double as test fixtures. Twelve small scans at different resolutions and modes are stored as full USB traces next to the image SANE produced from them. The test suite replays each trace through the driver, requires the USB messages to be byte-identical, and compares the resulting image to SANE's. That means the driver is tested without a scanner attached.

I also explored a few things the logs didn't cover. I cancelled scans partway through to see how the scanner recovers (it refuses a new job briefly, then accepts one), and I captured the front-panel buttons on the interrupt endpoint so that a press can start a scan.

On the Swift side, the API is built around async scans with cancellation and progress, and rows are converted as they arrive instead of after the whole page. The image writer refuses to be lossy: it saves PNG or TIFF only, and rejects any other extension rather than quietly recompressing.

Caveats

SANE's backends are GPL, and my driver is a translation of one of them, so I don't plan to distribute the app. The code is also hardcoded to this one scanner, with its USB IDs, bed size and command sequence baked in. And getting the raw data removes the compression, but not the other limits of a cheap CIS scanner, such as a very shallow depth of field. That's a separate post.

If you have a LiDE 400 (or similar)

You don't need my app. Install SANE (brew install sane-backends) and use scanimage. If you're stuck with Image Capture, know that "save as TIFF" is a container change, not a quality change, whatever the menu implies. If you're curious whether a scanner you already own is affected, ask it what it can return: fetch /eSCL/ScannerCapabilities from its eSCL endpoint and look at the document formats it lists.