retropixels
v0.9.11
Published
A cross platform command line tool to convert images to Commodore 64 format.
Downloads
24
Readme
retropixels
A cross platform command line tool to convert images to Commodore 64 format.
Summary
retropixels --format png paintface.jpg
Disclaimer
This is a command line tool, meaning you have to be comfortable typing commands into a terminal, or not afraid to find out. Windows, macOS and Linux come with terminals pre-installed. How to use a terminal is beyond the scope of this document.
The output of the tool consists of Commodore 64 format binaries, with the
exception of .png
files, which are normal cross-platform images. It is not
explained what you can do with these output files, you are expected to know or
to find out yourself.
This tool contains bugs and is missing features; if you find any, you can report them in the Github issue tracker for this project. There is no guarantee these will be addressed, because this is a hobby project for me. You are welcome to fork and submit merge requests.
The tool has been tested on macOS but should work on all operating systems supporting NodeJS.
Installation
Note: you do not need to download retropixels to install it. The npm
command
below will do that for you.
- Install NodeJS (v14 or higher. just use the defaults when asked)
- Run
npm install -g retropixels
You now have a new shell command called retropixels
Usage
retropixels [options] <infile>
With
<infile>
: the image to convert[options]
:--outfile, -o
: output filename--mode, -m <mode>
with<mode>
:bitmap
(default)sprites
fli
--format, -f <format>
with<format>
:png
: preview imageprg
: c64 executable
--ditherMode, -d <ditherMode>
with<ditherMode>
:none
bayer2x2
bayer4x4
(default)bayer8x8
--ditherRadius, r <ditherRadius>
with<ditherRadius>
:- A number between 0 (no dithering) and 64 (heavy dithering). Default is 32.
--palette, -p <palette>
with<palette>
:PALette
(default)colodore
pepto
deekay
--colorspace, -c <colorspace>
with<colorspace>
:xyz
(default)yuv
rainbow
rgb
(no conversion)
--cols <columns>
with<columns>
:- The number of sprites in horizontal direction.
sprites
mode only.
- The number of sprites in horizontal direction.
--rows <rows>
with<rows>
:- The number of sprites in vertical direction.
sprites
mode only.
- The number of sprites in vertical direction.
--hires, -h
: use hires mode instead of multicolor--scale, -s <mode>
with<mode>
:fill
(default): scale and crop to fill output dimensionsfit
(default): scale and crop to fit output dimensions, potentially padding with to fit aspect rationone
: do not scale, only crop
--nomaps
: restrict to a single color per attribute type or sprite--overwrite
: overwrite if output file already exists
Notes:
- The FLI/AFLI display code was found on codebase64.org
- FLI/AFLI modes result in an issue with the leftmost 3 characters on each row being unusable. You will see a blank space in the image. This is a limitation of the Commodore 64 VIC chip hacking involved in creating this artificial mode, and is not a bug in retropixels
- Spritepad files can be viewed and edited online at spritemate.com
Options
--mode, -m < bitmap | sprites | fli >
A c64 graphic mode:
| value | description |
| ------------------ | --------------------------- |
| bitmap
(default) | A fullscreen bitmap |
| sprites
| A grid of sprites |
| fli
| A fullscreen (A)FLI picture |
The output is multicolor by default. To get high resolution output, use
--hires
together with this option.
The format of the output file is determined automatically, see the section Output formats for details.
--format, -f < png | prg >
Two special formats can be supplied for the output:
png
: A PNG image of how the image will look on a Commodore 64prg
: An executable that can be run on a Commodore 64
When omitted, the format of the output file will be determined automatically as
described for the --mode
option.
Note: prg
is not supported for -m sprites
mode.
--ditherMode, -m < none | bayer2x2 | bayer4x4 | bayer8x8 >
The mode to use for dithering. Default is bayer4x4
--ditherRadius, -r < 0-64 >
The dithering strength. Default is 32
.
--palette, -p < colodore | pepto | deekay >
The predefined palette to use. Default is colodore
.
--colorspace -s < rgb | yuv | xyz >
Convert colors to this colorspace before quantizing. Default is xyz
.
rgb
means no colorspace conversion takes place.
--rows < number >, --columns < number >
Number of rows and columns in the grid when using -m sprites
.
Note: Ignored in other modes.
--scale < none | fill >
Sets the way the input image is scaled before converting:
fill
(default): scale to fill output dimensions, and crop if necessaryfit
(default): scale to fit output dimensions, and pad if necessarynone
: only crop to output dimensions
Note: Mode none
in multicolor mode does rescale double-width pixels to
one pixel, to preserve the original aspect ratio. This is useful for
pixel-perfect input images. Keep in mind these should have double width pixels
though. Also keep in mind to use -d none
to avoid dithering.
--nomaps
Instead of different colors per attribute type, or sprite, use only one color per attribute type or sprite. Results in less colors but can look more uniform, and can be used to boost performance on a Commodore 64.
Note: This option is ignored in -m fli
mode.
--outfile
The name of the output file. Will not be overwritten unless --overwrite
is specified.
--overwrite
Exisiting files are not overwritten by default. This option overrides that behaviour and will overwrite the output file if it exists.
Output formats
The following output formats describe the bytes in the output file in the order they appear.
| format | size in bytes | data |
| ------------------------------ | --------------------- | ------------------------------------------ |
| Koala painter (.kla
) | 2 | load address ($6000) |
| -m bitmap
| 8000 | bitmap |
| | 1000 | screen ram |
| | 1000 | color ram |
| | 1 | background color |
| Art studio (.art
) | 2 | load address ($2000) |
| -m bitmap -h
| 8000 | bitmap |
| | 1000 | screen ram |
| | 7 | $00 padding |
| Spritepad (.spd
) | 1 | background color |
| -m sprites
| 1 | multicolor 1 |
| -m sprites --h
| 1 | multicolor 2 |
| | nr of sprites * 64 | 63 bytes sprite data |
| | | 1 packed info byte: %m000cccc |
| | | m: hires (0) / multicolor (1) |
| | | cccc: sprite color |
| Retropixels raw FLI (.fli
) | 2 | load addres ($3c00) |
| -m fli
| 1024 | color ram (1000) + zero padding (24) |
| | 8 * 1024 | 8 * screen ram (1000) + zero padding (24) |
| | 8000 | bitmap |
| | 1 | background color |
| Retropixels raw AFLI (.afli
) | 2 | load addres ($4000) |
| -m fli -h
| 8 * 1024 | 8 * screen ram (1000) + zero padding (24) |
| | 8000 | bitmap |
Pixel perfect input
If you want to convert pixels one-on-one (for sheets of sprites for example), make sure to:
- use the
--palette
option and make sure the input colors map correctly on the palette - use
--scale none
- use
--ditherMode none
Examples
Convert an image to a (multicolor bitmap) Koala picture:
retropixels paintface.jpg
Convert an image to a (hires bitmap) Art studio picture:
retropixels --hires paintface.jpg
Convert an image to a (2 color hires bitmap) Art studio picture:
retropixels --hires --nomaps paintface.jpg
Convert an already pixel-perfect image to (8x4 multicolor) Spritepad sprites:
retropixels -m sprites --cols 8 --rows 4 -s none -d none sprites.png
Convert an image to a Commodore 64 executable, and use heavy dithering
retropixels -b bayer8x8 -r 64 --format prg eye.jpg
View the result by running it in the VICE emulator:
x64 eye.prg
Uninstall
npm uninstall -g retropixels
Development
The build process has been tested on macOS. It should work on other platforms but you're on your own there.
Prerequisites
Build
git clone https://github.com/micheldebree/retropixels.git
cd retropixels
make
Run with node cli.js [options] <infile>
Changelog
0.9.10
- Added #103 Option
fit
for the--scale
setting, which scales to fit entirely in the screen. Thanks to magwed for requesting.
0.8.10
- Added #89 A palette called "PALette". Thanks to Tobias Albert for developing and supplying the palette.
0.8.6
- Fixed #71 Error: Cannot find module 'node:path' (Thanks to Gregory Nacu for reporting)
0.8.5
- Changed: Significantly improved conversion speed
- Changed: (Internal) Split package into the command line tool (
retropixels
) and core functionality (retropixels-core
).
0.8.1
- Fixed [#53] multicolor PNG output is not pixel-perfect (Thanks to Rob for reporting)
0.8.0
This is a backwards incompatible release.
- Added #26
sprites
mode.--mode: sprites
--cols
: number of sprites in horizontal direction.--rows
: number of sprites in vertical direction.
- Added #44 save hires bitmaps to Art Studio format
- Changed all the options for
--mode
.c64Multicolor
,c64Hires
andc64HiresMono
are nowbitmap
mode.c64FLI
andc64AFLI
are nowfli
. - Added option
--hires
for hires images. Default when not supplied is multicolor images. - Added #43 option
--format
for outputting the specialpng
andprg
formats. - Added option
--nomaps
for limiting attribute maps to one single color. - Added option
--scale none
to disable rescaling of the input image. Default behaviour is--scale fill
- Added option
--outfile
for setting output filename. - Changed automatically overwriting of output file
Added option
--overwrite
to force overwriting output file.
0.7.2
- Fixed #37: Unfriendly error message when file not found
- Changed #38: Improve performance of quantizing
0.7.1
- Changed #15: Default color
palette changed from Pepto to Colodore. You can still chose
pepto
with the new--palette
argument. - Changed default color space conversion changed from YUV to XYZ. You can still choose
yuv
with the new--colorspace
argument. - Added #35:
--palette
argument to choose a color palette. New default iscolodore
. - Added #36:
--colorspace
argument to choose the color space to convert to before quantizing. New default isxyz
. - Removed
--unicorn
argument. It is replaced by therainbow
option in the new-colorspace
argument. It is a secret option so don't tell anyone!
0.6.4
- Changed #31: More developer friendly importing of library.
0.6.3
- Changed #28: Replaced ACME compiler with c64jasm to support JS only build.
0.6.2
- Added Unicorn mode
0.6.1
Fixes:
- #25: Koala export is broken. (Thanks to Alex Goldblat for reporting this)
0.6.0
Features:
- #19: Undocumented fake modes.
0.5.2
Bugfix:
- #22 Fixed small dithering bug.
0.5.1
Internal refactoring.
0.5.0
All modes now support saving as Commodore 64 executable (.prg)
0.4.1
0.4.0
- Export FLI executable.
- Internal refactoring.
0.3.0
Dithering options added:
- ditherMode
- ditherRadius
0.2.2
Optimized dithering, with better default setting.
0.2.1
- Fixes in
README.md
0.2.0
- Library: ported to Typescript
- Conversion tool: support for graphicMode c64Hires
0.1.0
Initial version.