Writing a SAM Coupé SCREEN$ Converter in Python

MODE 3 Retailer

When switching between MODE 3 and MODE 4. The palettes of MODE 3 & 4 are separate, however palette operations on the identical CLUT. When altering mode 4 colours are apart to a short lived retailer, and changed when switching again. These values are additionally saved when saving SCREEN$ information (see “retailer” entries above), so you possibly can exchange the MODE 3 palette by loading a MODE 4 display screen. It is a bit odd.

We are able to ignore this for our conversions and simply write a default set of bytes.

Interrupts

Interrupts outline places on the display screen the place a given palette entry (0-15) adjustments to a unique coloration from the 128 coloration system palette. They’re encoded with 4 bytes per interrupt, with a number of interrupts appended one after one other.

Interrupt coordinates set from BASIC are calculated from -18 as much as 172 on the prime of the display screen. The plot vary in BASIC is definitely 0..173, however interrupts cannot have an effect on the primary pixel (which is sensible, since that is dealt with by way of the primary palette).

When saved within the file, line interrupts are saved as 172-y. For instance, a line interrupt at 150 is saved within the file as 22. The road interrupt nearest the highest of the display screen (1st row down, interrupt place 173) could be saved as 172-172=0.

This sounds difficult, however really signifies that to get our interrupt Y byte we are able to simply subtract 1 from the Y coordinate within the picture.

Changing Picture to SCREEN$

We now have all the data we have to convert a picture right into a SCREEN$ format. The difficult bit (and what takes a lot of the work) is optimising the position of the interrupts to maximise the variety of colours within the picture.

Pre-processing

Processing is completed utilizing Pillow package deal for Python. Enter photographs are resized and cropped to suit, utilizing utilizing the ImageOps.match() methodology, with centering.

SAM_COUPE_MODE4 = (256, 192, 16)
WIDTH, HEIGHT, MAX_COLORS = SAM_COUPE_MODE4

im = Picture.open(fn)

# Resize with crop to suit.
im = ImageOps.match(im, (WIDTH, HEIGHT), Picture.ANTIALIAS, 0, (0.5, 0.5))

If the above crop is dangerous, you possibly can alter it by pre-cropping/sizing the picture beforehand. There is not the choice to shrink with out cropping as any border space would waste a palette entry to fill the clean area.

Interrupts

That is the majority of the method for producing optimized photographs: the optimize methodology is proven beneath — this exhibits the excessive stage steps taken to succeed in optimum variety of colours utilizing interrupts to compress colours.

def optimize(im, max_colors, total_n_colors):
    """
    Makes an attempt to optimize the variety of colours within the display screen utilizing interrupts. The
    result's a dictionary of coloration areas, keyed by coloration quantity
    """
    optimal_n_colors = max_colors
    optimal_color_regions = {}
    optimal_total_interrupts = 0

    for n_colors in vary(max_colors, total_n_colors+1):
        # Determine coloration areas.
        color_regions = calculate_color_regions(im, n_colors)

        # Compress non-overlapping colours collectively.
        color_regions = compress_non_overlapping(color_regions)

        # Simplify our coloration areas.
        color_regions = simplify(color_regions)

        total_colors = len(color_regions)

        # Calculate dwelling many interrupts we're utilizing, size drop preliminary.
        _, interrupts = split_initial_colors(color_regions)
        total_interrupts = n_interrupts(interrupts)

        print("- making an attempt %d colours, with interrupts makes use of %d colours & %d interrupts" % (n_colors, total_colors, total_interrupts))

        if total_colors <= max_colors and total_interrupts <= MAX_INTERRUPTS:
            optimal_n_colors = n_colors
            optimal_color_regions = color_regions
            optimal_total_interrupts = total_interrupts
            proceed
        break

    print("Optimized to %d colours with %d interrupts (utilizing %d palette slots)" % (optimal_n_colors, optimal_total_interrupts, len(optimal_color_regions)))
    return optimal_n_colors, optimal_color_regions

The tactic accepts the picture to compress, a max_colors argument, which is the variety of colours supported by the display screen mode (16). This can be a decrease certain, the minimal variety of colours we should always be capable of get within the picture. The argument total_n_colors incorporates the whole variety of colours within the picture, capped at 128 — the variety of colours within the SAM palette. That is the higher certain, the utmost variety of colours we are able to use. If the total_n_colors < 16 we’ll skip optimization.

Every optimization spherical is as follows –

• calculate_color_regions generates a dictionary of coloration areas within the picture. Every area is a (begin, finish) tuple of y positions within the picture the place a specific coloration is discovered. Every coloration will often have many blocks.
• compress_non_overlapping takes colours with few blocks and tries to mix them with different colours with no overlapping areas: transitions between colours might be dealt with by interrupts
• simplify takes the ensuing coloration areas and tries to simplify them additional, grouping blocks again with their very own colours if they will after which combining adjoining blocks
• total_colors the size of the color_regions is now the variety of colours used
• split_initial_colors removes the primary block, to get complete variety of interrupts

The compress_non_overlapping algorithm makes no effort to seek out the finest compression of areas – I experimented with this a bit and it simply explodes the variety of interrupts for little actual achieve in picture high quality.

def convert_image_to_sam_palette(picture, colours=16):
    new_palette = []
    rgb = picture.getpalette()[:colors*3]
    for r, g, b in zip(rgb[::3], rgb[1::3], rgb[2::3]):

        def distance_to_color(o):
            return distance(o, (r, g, b))

        spalette = sorted(SAM_PALETTE, key=distance_to_color)
        new_palette.append(spalette[0])

    palette = [c for i in new_palette for c in i]
    picture.putpalette(palette)
    return picture

pixels = np.array(image16)

image_data = []
pixel_data = pixels.flatten()
# Generate bytestream and palette; pack to 2 pixels/byte.
for a, b in zip(pixel_data[::2], pixel_data[1::2]):
    byte = (a << 4) | b
    image_data.append(byte)

image_data = bytearray(image_data)

        # Extra 4 bytes 0, 17, 34, 127; mode 3 short-term retailer.
        bytes4 = b'x00x11x22x7F'

        with open(outfile, 'wb') as f:
            f.write(image_data)
            # Write palette.
            f.write(palette)

            # Write further bytes (4 bytes, 2nd palette, 4 bytes)
            f.write(bytes4)
            f.write(palette)
            f.write(bytes4)

            # Write line interrupts
            f.write(interrupts)

            # Write remaining byte.
            f.write(b'xff')