farbfeld - bakkeby/dusk GitHub Wiki

farbfeld is a dead simple image format that basically just defines the width and height of the image followed by 16-bit RGBA pixel information.

The benefit of this is that it is easy to parse and process without the need for heavy libraries.

That brings us to the farbfeld tools and utilities, which provides file type conversions, image processing and filters.

Typical behaviour for these tools is that they take farbfeld data via stdin, and they write the output to stdout.

This means that you can chain farbfeld tools together piping the output of one command into another, just like you do with all other command.

Pseudo logic just to illustrate the point.

convert jpg to farbfeld | apply filter | crop | convert to png

As a practical example I had stored several screenshots as PNG files and needed to convert them to JPG to reduce the file sizes.

This is trivial to do using two farbfeld tools:

png2ff < image.png | ff2jpg > image.jpg

Since I may do this for a range of files I could dump this in a shell script that I named png2jpg.

#!/bin/bash
for FILE in "$@"; do
	png2ff < "$FILE" | ff2jpg > "${FILE%.*}.jpg"
done

There are so many tools and combinations that you can make if you need to automate certain things via scripting. For example applying colour corrections via LUTs.

The main page for farbfeld can be found here:

• https://tools.suckless.org/farbfeld/

The tools that are there are primarily just for converting between common formats such as JPG, PNG and PAM.

Then we have the farbfeld utils which is a rich collection of converters, processors and filters.

These can be found (or used to be found) at:

• http://zzo38computer.org/fossil/farbfeld.ui/wiki?name=Documentation

The problem with the farbfeld utils is that the programs themselves do not have any help output, and neither are there any man pages.

This, needless to say, makes it very hard to use especially if you come back after some time and are trying to figure out what a command or program does, or how it works. Reading the source code is not always the best approach either. There is online documentation available, but that is also cumbersome to work with when you have to spend time looking up the page for something just to tell what it does, let alone what all the cryptic command line arguments do.

The tools under the main suckless project, however, do come with man pages and basic help output.

With more than 160 converters, processors and filters I think the farbfeld utils is very cool and the vast majority of people are going to miss out on it due to the limitation when it comes to documentation.

Personally I think this is important which is why I spent six months writing up help output and man pages for all of them.

That can be found here:

• https://github.com/bakkeby/farbfeld-utils

The documentation describes what the format is, what the tool does and what command line arguments it takes (if any). It also generally provides some usage examples.

Example help output:

$ vec2ff
Usage: vec2ff <width> <height> <colour>

Convert DRAWX Vector Graphics image to farbfeld. vec2ff reads a VEC image from
stdin, converts it to farbfeld and writes the result to stdout.

This is a vector graphics format for use with a program called drawx, which is
a graphics tool for examining ASCII data generated elsewhere. It is based on
and uses basic xlib commands that make drawx fast, portable and well suited
for examining large volumes of data.

This decoder takes exactly three arguments:
   width             the width of the output
   height            the height of the output
   colour            the drawing colour(s) to use for the output

The colour argument can have these patterns:
   rrggbb            three pairs of 8-bit hex values
   rrggbbaa          four pairs of 8-bit hex values
   rrrrggggbbbb      three pairs of 16-bit hex values
   rrrrggggbbbbaaaa  four pairs of 16-bit hex values

The background will be transparent.

Example usage:
   $ vec2ff 640 480 F06060 < image.vec > image.ff
   $ vec2ff 320 240 A32260 < image.vec | bzip2 > image.ff.bz2

Example man page:

$ man ff-errdif
FF-ERRDIF(1)                General Commands Manual              FF-ERRDIF(1)

NAME
       ff-errdif  — farbfeld filter that applies a two-level error diffusion,
       individually per channel

SYNOPSIS
       ff-errdif <diffusion 1> ... <diffusion 12> <?divisor?>

DESCRIPTION
       ff-errdif reads a farbfeld(5) image from  stdin,  applies  the  errdif
       filter and writes the result to stdout.

       This farbfeld filter is used to apply a two-level error diffusion, in‐
       dividually per channel.

       In case of an error ff-errdif writes a diagnostic message to stderr.

EXIT STATUS
       0       Image processed successfully.

       1       An error occurred.

OPTIONS
       The filter takes twelve arguments and optionally a custom divisor.

          . . * A B
          C D E F G
          H I J K L

       The  twelve  arguments  are numbers named A to L in the above grid and
       these indicate the amount of diffusion in that position. The  asterisk
       indicates the current position.

       The divisor is normally equal to the sum of these numbers, but option‐
       ally a thirteenth argument can be added to specify the divisor.

EXAMPLES
       $ ff-errdif 1.0 1.0 5.0 1.0 1.0 1.0 1.0 5.0 1.0 1.0 1.0 1.0 < image.ff
       > image-errdif.ff

SEE ALSO
       farbfeld(5), farbfeld-utils(7)

farbfeld-utils                    2024-04-30                     FF-ERRDIF(1)

Back to Other scripts and life hacks.