img2splat is inspired by this tool that plunks images into Splatoon posts with a programmable microcontroller. It generates macros for NXBT, which allows you to directly control a Nintendo Switch from a Linux computer/VM over Bluetooth. It is intended to work with Splatoon 3, but might work with earlier titles.

Completed img2splat macro run in Splatoon 3

Getting your image into Splatoon

  1. Install NXBT and verify connectivity with your Switch by running the demo
    1. Some have reported issues with running very long macros with NXBT where it skips inputs. I made a fork that tries to address some of the timing issues. If you want to try using this fork, clone the linked branch and…

      1. On Linux systems, instead of doing sudo pip3 install nxbt, do pip3 install -e . from the root of the repo
      2. On Windows/macOS, follow the instructions in the readme, but make sure you choose to install NXBT from local files.
  2. Make a 320 x 120 image
    1. The image does not necessarily need to be black and white, img2splat will look at the luminance of each pixel to decide if it should be black or white
    2. If you want dithering in your image to approximate shades of grey, img2splat will not do that for you. Graphics software like the GIMP can dither your image for you
    3. A lossless format like PNG is probably ideal
  3. Run img2splat with your image as the input, which will spit out two files:
    1. splat_macro.txt is the actual list of commands for NXBT to run
    2. macro_preview.png shows what the resulting image might look like
    3. More on specific options below
  4. Open Splatoon 3 and start editing a new post
    1. Ensure the canvas is in the wider “horizontal” mode
    2. Clear the canvas to all white pixels. Don’t do this if you’re repairing.
    3. Select the smallest, single-pixel brush size
    4. Move the cursor to the upper-left corner of the canvas
  5. Run NXBT with the macro: sudo nxbt macro -c "splat_macro.txt" -r
    1. The macro should start running after a few moments without any need to pair controllers if you’ve previously paired and run the demo
    2. When the macro finishes, it will press - to save in case the Switch is left unattended.

Running img2splat

img2splat needs Java to run. At a minimum, you have to provide an image as the first argument:

java -jar img2splat.jar myimage.png

Preview Image

In addition to the NXBT macro, an image named macro_preview.png will also be generated to visually show what the output of the macro might look like. Pixels that the macro will “visit” with the drawing cursor will be black or white. Any “unvisited” pixels will be blue; this can happen as the result of an optimization or if you specify repair rows.

Macro Button Press Duration

You can also specify the length of button presses/releases in the generated macro. By default, buttons are pressed for 0.1 seconds and released for the same. You can override this via the pressDuration/d flag:

java -jar img2splat.jar myimage.png -d 0.05

A macro with a press duration of 0.05 would run approximately twice as fast as default. The tradeoff, however, is you may be more likely to run into missed button presses and a compromised image. This ultimately boils down to the performance of NXBT, your machine, and your Bluetooth adapter.

Repair Mode

With the repairRows/r flag, you can generate a macro that only draws the rows of pixels you specify. This might be useful if NXBT hitched while drawing a few rows or if your Bluetooth connection broke partway through. Then you can re-run a “repair” macro and not have to wait for the whole thing to re-draw!

Repair rows can be specified as a comma-separated list of individual pixel rows (e.g. 28) or a range (e.g. 77-82). Values should be between 0 and 119. Example:

java -jar img2splat.jar myimage.png -r 28,77-82,100

Repair macros still start from the upper-left corner of the canvas like regular macros, so most preparation steps are the same.


View Github