https://github.com/aexoden/snesimage

A tool to optimize images for use on the SNES.
https://github.com/aexoden/snesimage

image-processing

Last synced: 5 months ago
JSON representation

A tool to optimize images for use on the SNES.

• Host: GitHub
• URL: https://github.com/aexoden/snesimage
• Owner: aexoden
• License: apache-2.0
• Created: 2020-09-18T04:53:59.000Z (almost 6 years ago)
• Default Branch: main
• Last Pushed: 2025-10-22T20:53:50.000Z (8 months ago)
• Last Synced: 2025-10-22T22:23:33.877Z (8 months ago)
• Topics: image-processing
• Language: Rust
• Homepage:
• Size: 321 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-APACHE-2.0

Awesome Lists containing this project

README

          
snesimage

=========

snesimage is a utility for optimizing a given image for display on the SNES. It

currently uses a combination of a k-means clustering algorithm to determine the

initial palette, with a iterative optimization algorithm to improve the

generated palette.

Usage

-----

snesimage currently expects to be given a 256x256 source image. Other sizes will

likely do very strange things, if they work at all.

The following command-line options are available:

* `--subpalette-count` determines the number of subpalettes to use.

* `--subpalette-size` determines the size of each subpalette, not including the

  transparent color. As a result, values of 3, 7 and 15 are most likely to be

  useful.

* `--dither` enables dithering of the result.

* `--perceptual-palettes` does color comparisons in CIELAB space instead of RGB.

  This does cache computations and may use up to several gigabytes of RAM, so

  monitoring memory usage is recommended if this option is enabled. However, the

  final result will possibly be better. The error function, however, is based on

  SSIMULACRA2 and will do its own calculations regardless of this option. This option

  controls initial palette assignment and the choice of which palette entry to

  use for each pixel.

* `--nes` restricts the available colors to those available on the NES (assuming

  no color de-emphasis bits or mid-frame trickery). Note that the generated output

  is still intended for the SNES. The primary purpose is to generate SNES images

  that look like they could have been for the NES, for whatever reason. As an

  additional limtation, the system still assumes palettes can be set per 8x8 tile,

  which is only true on the NES when using certain less common mappers. (To maximize

  the effect, you would want to use 1-4 subpalettes with 3 colors each.)

The program takes two mandatory arguments: an image to optimize, and the

filename you wish any JSON output to be written to.

After starting the program, it will begin in tile assignment mode, assigning

each tile to a palette index. The default assignment is often fine, but if you

wish to tweak it, you may do so by clicking on the tile in question to switch it

to the next available palette. (The colors of the tiles reflect the average

color of the originally chosen tiles using that palette.)

Once the tiles are set to your satisfaction, click the green button to assign

the initial palettes. Depending on your image, this assignment may be completely

satisfactory. If so, you may press the blue button to immediately write the

current state to the output file. Otherwise, press the green button again to

begin the optimization phase.

The optimization phase will run indefinitely, though it will generally stop

improving the result within a few minutes. At any point, you can press the

blue button to output the current state.

Output Format

-------------

The output format is currently a rather simple JSON document, with three

separate arrays. The first, named `tiles`, is an array of arrays, each of which

contains the palette number (within each subpalette, therefore ranging from 0 to

15) used by that pixel of the tile. The `palette` section gives the full palette

entries, automatically expanding each subpalette to the full 16 colors

(including the transparent color at index zero). The entries are already

converted to the SNES palette format and are given as 16-bit unsigned integers.

The final section, `tile_palettes`, provides the palette index used by each

tile, numbered starting from zero.

Notes

------------

Any fully transparent pixel in the original image will remain transparent in the

final output. Partially transparent pixels will have their transparency silently

ignored.

No attempt is made to consolidate identical tiles, and each of the original

tiles is output in its entirety.