Mosaicus
Contents›Reference›Command line

Command line

The mosaicus command converts pictures without opening the app: handy for trying a format on a folder of pictures, or for scripts. It has three commands: convert, formats and serve-dev.

mosaicus <COMMAND>

Commands:
  convert    Convert a picture (or a .mosaicus project) and write a PNG of the result
  formats    List the formats
  serve-dev  Serve the app's commands over HTTP for the UI in a browser (development and UI testing)
  help       Print this message or the help of the given subcommand(s)

mosaicus --help (or -h) prints that list, mosaicus help convert or mosaicus convert --help a command's options, and mosaicus --version (-V) the version.

convert

mosaicus convert [OPTIONS] <INPUT>

Converts a picture and writes a PNG of the C64 picture, as Mosaicus shows it. It writes a PNG only: for files a C64 can load, open the picture in the app and use Exporting.

INPUT is a picture (PNG, JPEG, GIF, BMP, WebP, TIFF or TGA) or a .mosaicus project.

Option What it does
-f, --format <FORMAT> The format, by the id mosaicus formats lists (koala, hires, afli…). Default: the preset's format if you give a preset, else koala. The format's usual size is used.
--preset <PRESET> A preset saved in the app, by name (capitals don't matter; quote a name with spaces). Its settings apply first; the other options here go over them.
-d, --dither <DITHER> The dither: none, pair2 (Two-color mix, fine), pair4 (Two-color mix, more tones), bayer2, bayer4, bayer8 (Ordered 2×2, 4×4, 8×8), blue (Blue noise), floyd (Floyd–Steinberg), atkinson, sierra3 (Sierra), sierra2 (Sierra two-row), sierra (Sierra Lite), jjn (Jarvis–Judice–Ninke), stucki, burkes. Default: pair2.
--wide <WIDE> The ordered and pair dithers' pattern on multicolor's wide pixels: diagonal (the default), classic or rows.
-p, --palette <PALETTE> The palette: colodore (the default) or pepto. Another name is an error.
-o, --out <OUT> The PNG to write. Default: beside the input, with .c64.png in place of its extension (wave.jpg becomes wave.c64.png).
-s, --scale <SCALE> Screen pixels per C64 pixel in the PNG, default 2. Multicolor pixels come out twice as wide as tall, as on the screen.

When it is done it prints the file it wrote and how long it took, plus how many cells are over their limit if any are:

> mosaicus convert wave.jpg -f hires -d floyd
wrote wave.c64.png (31 ms)

How it converts

  • The settings are Mosaicus' defaults (or the preset's) with your options over them: Crop to fill framing, no adjustments, every color allowed, and Fast quality unless the preset says Best.
  • It doesn't make the choices the app makes when it opens a picture: it doesn't fit pictures of another shape, treat pixel art differently, or open a picture already in a C64 format exactly. For those, use the app, or a preset with the framing you want.
  • A project is converted with its own settings, source picture and hand edits, as the app shows it; the --format, --preset, --dither, --wide and --palette options are ignored (the command says so). If its source picture isn't found, the command says so and converts the hand edits over a blank picture.

Presets

--preset reads the presets the app keeps in its own folder (on Windows %LOCALAPPDATA%\Mosaicus\presets.json). Save one in the app (Presets panel ▸ Save…), then:

mosaicus convert picture.jpg --preset "Box scans"
mosaicus convert picture.jpg --preset "Box scans" -d floyd

If there's no preset of that name, the command lists the names it has. See Presets.

Errors

A problem (a file that can't be read, a format or dither it doesn't know, a preset that isn't there) prints a line starting with mosaicus: and the command exits with code 1. It exits with 0 when the PNG is written.

formats

mosaicus formats

Lists every format: its id (for --format), its name, its usual size and its summary.

Id Format
hires Hires bitmap
koala Multicolor bitmap (Koala)
afli Hires FLI (AFLI)
fli Multicolor FLI
hiresspr Hires + sprites
koalaspr Multicolor + sprites
hiresfli Hires FLI + sprites
koalafli Multicolor FLI + sprites
hireschars Hires characters
mcchars Multicolor characters
ecmchars ECM characters
ecm Charset logo (ECM)
sprites Sprite sheet (multicolor)
hires16 Hires, 16 colors per pixel
hires240 Hires 240, 16 colors per pixel
mixed Hires band + chunky
chunky160 Chunky 160 × 200
chunky80 Chunky 80 × 50
koalascpu Multicolor, background per 4 × 1

See Formats for what each allows.

serve-dev

mosaicus serve-dev [--port <PORT>]

For developing Mosaicus itself: serves the app's commands over HTTP on 127.0.0.1 (port 1430 unless you give --port), so the app's interface can run in a web browser. It keeps its own recovery copies and presets (presets-dev.json), apart from the app's. You don't need it to use Mosaicus.