chafa Documentation

File: README.md Copy Chapter

About Copy Chapter

Chafa is a command-line utility that converts image data, including
animated GIFs, into graphics formats or ANSI/Unicode character art suitable
for display in a terminal. It has broad feature support, allowing it to be
used on devices ranging from historical teleprinters to modern terminal
emulators and everything in between.

The core functionality is provided by a C library with a public,
well-documented API.

Both library and frontend tools are covered by the Lesser GPL license,
version 3 or later (LGPLv3+).

The official web pages and C API
documentation can be found online. Check
out the gallery for screenshots.

Installing Copy Chapter

Chafa is most likely packaged for your distribution, so if you're not
going to hack on it, you're better off using
official packages. If you want to
build the latest and greatest yourself, read on.

You will need GCC, make, Autoconf, Automake, Libtool and the GLib
development package installed to compile Chafa from its git repository. If
you want to build the command-line tool chafa and not just the library,
you will additionally need development packages for:

• FreeType2. Often packaged as libfreetype6-dev or freetype2-devel.
• libjpeg (optional). Look for libjpeg-dev, libjpeg62-devel or libjpeg8-devel.
• librsvg (optional). Look for librsvg2-dev or librsvg-devel.
• libtiff (optional). Look for libtiff5-dev or libtiff-devel.
• libwebp (optional). Look for libwebp-dev or libwebp-devel.

If you want to build documentation, you will also need gtk-doc.

Start by cloning the repository:

$ git clone https://github.com/hpjansson/chafa.git

Then cd to the toplevel directory and issue the following shell commands:

$ ./autogen.sh
$ make
$ sudo make install

That should do it!

Python bindings Copy Chapter

Erica Ferrua Edwardsdóttir maintains
excellent Python bindings for Chafa. If
Python's your thing, check them out. They are easy to use and come with a
detailed tutorial.

JavaScript bindings Copy Chapter

Héctor Molinero Fernández maintains
wonderful JavaScript bindings
built around his WebAssembly port. These are available from NPM and can
be used in Node.js, web browsers, and more.

File: lodepng/README.md Copy Chapter

LodePNG Copy Chapter

PNG encoder and decoder in C and C++, without dependencies

Home page: http://lodev.org/lodepng/

Documentation Copy Section

Detailed documentation is included in a large comment in the second half of the
header file lodepng.h.

Source code examples using LodePNG can be found in the examples directory.

An FAQ can be found on http://lodev.org/lodepng/

Building Copy Section

Only two files are needed to encode and decode PNGs:

• lodepng.cpp (or renamed to lodepng.c)
• lodepng.h

All other files are just source code examples, tests, misc utilities, etc...,
which are normally not needed in projects using this.

You can include the files directly in your project's source tree and its
makefile, IDE project file, or other build system. No library is necessary.

In addition to C++, LodePNG also supports ANSI C (C89), with all the same
functionality: C++ only adds extra convenience API.

For C, rename lodepng.cpp to lodepng.c.

Consider using git submodules to include LodePNG in your project.

Compiling in C++ Copy Section

If you have a hypothetical your_program.cpp that #includes and uses lodepng.h,
you can build as follows:

g++ your_program.cpp lodepng.cpp -Wall -Wextra -pedantic -ansi -O3

or:

clang++ your_program.cpp lodepng.cpp -Wall -Wextra -pedantic -ansi -O3

This shows compiler flags it was designed for, but normally one would use the
compiler or build system of their project instead of those commands, and other
C++ compilers are supported.

Compiling in C Copy Section

Rename lodepng.cpp to lodepng.c for this.

If you have a hypothetical your_program.c that #includes and uses lodepng.h,
you can build as follows:

gcc your_program.c lodepng.c -ansi -pedantic -Wall -Wextra -O3

or

clang your_program.c lodepng.c -ansi -pedantic -Wall -Wextra -O3

This shows compiler flags it was designed for, but normally one would use the
compiler or build system of their project instead of those commands, and other
C compilers are supported.

Makefile Copy Section

There is a Makefile, but this is not intended for using LodePNG itself since the
way to use that one is to include its source files in your program. The Makefile
only builds development and testing utilities. It can be used as follows:

make -j

File: tools/fontgen/README.md Copy Chapter

Chafa8x8 Custom Block Font

Advantages of this custom font Copy Chapter

1. One can read large fonts from images more easily.

2. Very good at dealing with some natural image textures.

3. Higher definition compared to block glyphs in standard Unicode.

How to build this font Copy Chapter

1. Prepare many images, and put them to a folder, e.g. ~/coco/*.jpg.

2. Create dataset from those images. ./chafa8x8.py CreateDataset --glob "$HOME/coco/*.jpg". Note, don't miss the quotes because the wildcard should be expanded by python's glob instead of the shell. Although the default parameters should be fine, the optional arguments are: (1) -Mc specifies the number of vectors to sample from each image file. The default is 16. Namely, in total 16 random crops (converted to vectors) are sampled from each image; (2) -N specifies the vector length. The default is 64 for 8x8 blocks. After this, a fine named chafa8x8.npz will be created for the following clustering step.

3. Run K-Means algorithm to find cluster center vectors. ./chafa8x8.py Clustering. This will create the optimal vectors. The optional parameter -C specifies how many vectors you want (i.e., how many optimal 8x8 blocks you want). The actual usable vectors (glyphs) will be less than this number after post processing (such as deduplication). The results will be stored in chafa8x8.raw.json by default. Note, this step is slow. For GPU accelerated computing, see the misc notes in the next section.

4. Post-process. Generate C code, SVG images and TTF font. ./chafa8x8.py GenA. This is actually a composed command. It executes the following four steps: (1) It invokes ./chafa8x8.py Postproc to deduplicate the optimal glyphs. The results will be written in chafa8x8.json; (2) Then it invokes ./chafa8x8.py GenC to generate C header from json as chafa8x8.h; (3) Next, it invokes ./chafa8x8.py GenSVG to convert the optimal glyphs from json into SVG files under the chafa8x8_svg directory; (4) Lastly, it invokes ./chafa8x8.py GenFont to create the font file chafa8x8.ttf from the json result.

Misc Notes Copy Chapter

1. Python dependencies: pip3 install numpy scipy scikit-learn tqdm.

2. Note, in order to generate a usable font, the python3-fontforge (for Debian bullseye and newer) package has to be installed as well. It will be used in the ./chafa8x8.py GenA step. It will automatically invoke chafa8x8.py GenFont subcommand for creating the font.

3. Note, the clustering step is the most time-consuming procedure. If the created dataset is very large (e.g., more than 1 million vectors inside), it won't be surprising to run for several hours or even longer. Although the result can be better with a large dataset, the resulting fonts should be good to use as long as, say, the dataset size is more than 10 times larger than the number of optimal glyphs we want.

4. You may take a quick glance at the glyphs from the json files, e.g., for the finalized glyphs: ./chafa8x8.py Dump --json chafa8x8.json | less, and for the preliminary glyphs before deduplication: ./chafa8x8.py Dump --json chafa8x8.raw.json | less.

5. The clustering step can be accelerated using Nvidia GPU (through CUDA). You need to install faiss first: pip3 install faiss-gpu. To use it, just specify the backend in the command line: ./chafa8x8.py Clustering --backend faiss.

Todos Copy Chapter

• update compare.py with the latest usage.

Acknowledgement Copy Chapter

The core algorithm used to generate the glyphs is
K-Means, one of the
clustering algorithms in the machine learning literature.

You can generate a font by using some image dataset e.g.
MSCOCO dataset (research-oriented).

License Copy Chapter

Copyright (C) 2018 Mo Zhou, LGPLv3+