coco-tools

This is a simple collection of tools to assist with developing software for the TRS-80 Color Computer.

Installation

# To install via pip
pip install coco-tools

# To install from source
git clone https://github.com/jamieleecho/coco-tools.git
cd coco-tools
make install-pre-commit
make install

Tools

decb-to-b09

usage: decb-to-b09 [-h] [--version] [-l] [-z] [-s DEFAULT_STRING_STORAGE] [-D]
                   [-w] [-c CONFIG_FILE] [--list-integer-candidates] [-O]
                   [--no-optimize A,B,C]
                   program.bas program.b09

Convert a Color BASIC program to a BASIC09 program
Copyright (c) 2023 by Jamie Cho
Version: 0.26

positional arguments:
  program.bas           input DECB text program file
  program.b09           output BASIC09 text program file

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -l, --filter-unused-linenum
                        Filter out line numbers not referenced by the program
  -z, --dont-initialize-vars
                        Don't pre-initialize all variables
  -s DEFAULT_STRING_STORAGE, --default-string-storage DEFAULT_STRING_STORAGE
                        Bytes to allocate for each string
  -D, --dont-output-dependencies
                        Don't output required dependencies
  -w, --dont-run-width-32
                        if set don't run the default width 32
  -c CONFIG_FILE, --config-file CONFIG_FILE
                        Optional compiler configuration file
  --list-integer-candidates
                        Instead of compiling, write a sorted list of
                        variables that could be stored as BASIC09 integers,
                        one per line. Array variables are written with a
                        trailing '()'.
  -O, --optimize        Enable real-to-integer optimization: variables and
                        arrays that are only ever assigned integer values
                        in the range [-32768, 32767] are declared as
                        BASIC09 INTEGER instead of the default REAL.
  --no-optimize A,B,C   Comma-separated list of variables to exclude from
                        the real-to-integer optimization. Use plain names
                        for scalars (e.g., A) and a trailing '()' for
                        arrays (e.g., Y()). Has no effect unless -O is also
                        set.

cm3toppm

usage: cm3toppm [-h] [--version] [image.cm3] [image.ppm]

Convert RS-DOS CM3 images to PPM
Copyright (c) 2017 by Mathieu Bouchard
Copyright (c) 2018-2020 by Jamie Cho
Version: 0.6

positional arguments:
  image.cm3   input CM3 image file
  image.ppm   output PPM image file

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

hrstoppm

usage: hrstoppm [-h] [-w width] [-r height] [-s bytes] [--version]
                [image.hrs] [image.ppm]

Convert RS-DOS HRS images to PPM
Copyright (c) 2018 by Mathieu Bouchard
Copyright (c) 2018-2020 by Jamie Cho
Version: 0.6

positional arguments:
  image.hrs   input HRS image file
  image.ppm   output PPM image file

options:
  -h, --help  show this help message and exit
  -w width    choose different width (this does not assume bigger pixels)
  -r height   choose height not computed from header divided by width
  -s bytes    skip some number of bytes
  --version   show program's version number and exit

maxtoppm

usage: maxtoppm [-h] [--version]
                [-br | -rb | -br2 | -rb2 | -br3 | -rb3 | -s10 | -s11] [-i]
                [-w width] [-r height] [-s bytes] [-newsroom]
                [image] [image.ppm]

Convert RS-DOS MAX and ART images to PPM
Copyright (c) 2018 by Mathieu Bouchard
Copyright (c) 2018-2020 by Mathieu Bouchard, Jamie Cho
Version: 0.6

positional arguments:
  image       input image file
  image.ppm   output PPM image file

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

pixel mode:
  Default pixel mode is no artifact (PMODE 4 on monitor). The 6 other modes:

  -br         PMODE 4 artifacts, cyan-blue first
  -rb         PMODE 4 artifacts, orange-red first
  -br2        PMODE 3 Coco 3 cyan-blue first
  -rb2        PMODE 3 Coco 3 orange-red first
  -br3        PMODE 3 Coco 3 primary, blue first
  -rb3        PMODE 3 Coco 3 primary, red first
  -s10        PMODE 3 SCREEN 1,0
  -s11        PMODE 3 SCREEN 1,1

Format and size options::
  Default file format is CocoMax 1/2's .MAX, which is also Graphicom's
  .PIC and SAVEM of 4 or 8 pages of PMODE 3/4.
  Also works with any other height of SAVEM (including fractional pages).

  -i          ignore header errors (but read header anyway)
  -w width    choose different width (this does not assume bigger pixels)
  -r height   choose height not computed from header divided by width
  -s bytes    skip header and assume it has the specified length
  -newsroom   read Coco Newsroom / The Newspaper .ART header instead

mgetoppm

usage: mgetoppm [-h] [--version] [image.mge] [image.ppm]

Convert RS-DOS MGE images to PPM
Copyright (c) 2017 by Mathieu Bouchard
Copyright (c) 2018-2020 by Jamie Cho
Version: 0.6

positional arguments:
  image.mge   input MGE image file
  image.ppm   output PPM image file

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

mge_viewer2

usage: mge_viewer2 [-h] [--version] [image.mge]

View ColorMax 3 MGE files
Copyright (c) 2022 by R. Allen Murphey
Version: 0.6

positional arguments:
  image.mge   input MGE image file

optional arguments:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

pixtopgm

usage: pixtopgm [-h] [--version] image.pix [image.pgm]

Convert RS-DOS PIX images to PGM
Copyright (c) 2018-2020 by Mathieu Bouchard, Jamie Cho
Version: 0.6

positional arguments:
  image.pix   input PIX image file
  image.pgm   output PGM image file

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

png-to-cocopng

usage: png-to-coco-png [-h] [--bits-per-pixel BITS_PER_PIXEL] input_png input_palette output_png

Convert a PNG image to a CoCo 3 palette PNG.

positional arguments:
  input_png             Path to the input PNG image file.
  input_palette         Path to the input palette file is in the Multi Vue env.file format.
  output_png            Path to the output PNG file.

optional arguments:
  -h, --help            show this help message and exit
  --bits-per-pixel BITS_PER_PIXEL
                        Number of bits per pixel.

png-to-mvicon

usage: png-to-mvicon [-h] input_png input_palette output_icon

Convert a 24x24 PNG image to a Multi Vue icon file.

positional arguments:
  input_png      Path to the input PNG image file.
  input_palette  Path to the input palette file is in the Multi Vue env.file format.
  output_icon    Path to the output icon file.

optional arguments:
  -h, --help     show this help message and exit

png-to-os9-image

usage: png-to-os9-image [-h] [--mask-index MASK_INDEX] [--bits-per-pixel BITS_PER_PIXEL]
                        input_png input_palette output_os9_image

Convert an PNG image to an OS-9 image.

positional arguments:
  input_png             Path to the input PNG image file.
  input_palette         Path to the input palette file is in the Multi Vue env.file format.
  output_os9_image      Path to the output OS-9 image file.

optional arguments:
  -h, --help            show this help message and exit
  --mask-index MASK_INDEX
  --bits-per-pixel BITS_PER_PIXEL
                        Number of bits per pixel.

rattoppm

usage: rattoppm [-h] [--version] [image.rat] [image.ppm]

Convert RS-DOS RAT images to PPM
Copyright (c) 2018-2020 by Mathieu Bouchard, Jamie Cho
Version: 0.6

positional arguments:
  image.rat   input RAT image file
  image.ppm   output PPM image file

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

veftopng

usage: veftopng [-h] [--version] image.vef image.png

Convert OS-9 VEF images to PNG
Copyright (c) 2018-2020  Travis Poppe <tlp@lickwid.net>
Copyright (c) 2020  Jamie Cho
Version: 0.6

positional arguments:
  image.vef   input VEF image file
  image.png   output PNG image file

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

Developing and Testing

You will need a fairly modern python environment with uv installed.

You can begin by entering:

make install-pre-commit
make sync
make run-tests

The Makefile makes it easy to perform the most common operations:

make all transpiles several example ECB programs to Basic09
make basic.dsk os9boot.dsk builds ECB and OS-9 disks with examples
make check-all runs linting and uv.lock checks
make check-lint checks for linting issues
make check-lock verifies the uv.lock is aligned to pyproject.toml
make clean cleans the virtual environment and caches
make default runs a default set of checks on the code
make fix-all formats the code, fixes lint errors and runs locks uv.lock to pyproject.toml
make fix-format formats the code
make fix-lint fixes linting issues
make fix-lint-unsafe fixes linting issues potentially adding inadvertant bugs
make help outputs the different make options
make install build install the distribution
make install-pre-commit installs pre-commit hooks
make lock locks uv.lock to pyproject.toml
make install-pre-commit installs pre-commit hooks
make run-tests runs the unit tests
make sync syncs the python environment with uv.lock

.vscode/settings.json is set so that unit tests can be run without further configuration.

You can use Docker to run tests in a Linux environment:

# Build the docker image
docker compose build test

# Run tests using the source on the docker image
docker compose run test

# Run tests using the source on the host computer
docker compose run testv

Credits

The programs in the examples/decb and examples/other-decb-examples-to-try directories are from the following sources:

Development Status
- 3 - Alpha
Intended Audience
- Developers
Programming Language
- Python :: 3
Topic
- Software Development :: Build Tools

Release files for coco-tools 0.28

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for coco-tools 0.28
File	Size	Uploaded
coco_tools-0.28.tar.gz	114.9 kB	Sep 19, 2026	Details

Release files / coco_tools-0.28.tar.gz

Download URL	coco_tools-0.28.tar.gz
Size	114.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`aa1186113111df0e0defc60c2982db04f0b94abf84d148ba6c1e106307f09f67`
BLAKE2b-256 checksum How to use checksums	`6034336542353eadd1fdddd74e4554aac0ff59b48ace6ecf278bbe6292822b47`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.