Metadata-Version: 2.1
Name: colossus-ltsm
Version: 1.0.3
Summary: Font conversion and visualization tool for embedded systems
Author-email: Gavin Lyons <glyons66@hotmail.com>
Project-URL: Homepage, https://github.com/gavinlyonsrepo/Colossus_LTSM
Project-URL: Issues, https://github.com/gavinlyonsrepo/Colossus_LTSM/issues
Keywords: ttf,fonts,converter,embedded,lcd,gui,font,microcontroller
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow

# Colossus_LTSM

[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/paypalme/whitelight976) [![CI](https://github.com/gavinlyonsrepo/Colossus_LTSM/actions/workflows/ci.yml/badge.svg)](https://github.com/gavinlyonsrepo/Colossus_LTSM/actions/workflows/ci.yml) [![PyPI version](https://img.shields.io/pypi/v/colossus-ltsm.svg)](https://pypi.org/project/colossus-ltsm/)

## Table of Contents

* [Overview](#overview)
* [Installation](#installation)
* [Libraries](#libraries)
* [Usage](#usage)
* [Input](#input)
* [Output](#output)
* [Configuration file](#configuration-file)
* [Desktop Entry](#desktop-entry)
* [Glyph rendering](#glyph-rendering)
* [Screenshots](#screenshots)
* [Projects](#projects)
* [See also](#see-also)

## Overview

**Colossus_LTSM** is a Python tool for converting TrueType fonts (`.ttf`) into C/C++ bitmap arrays and for visualizing font data stored in C/C++ header files.  
It is aimed at users working with embedded systems, LCDs, and GUIs where compact fonts are needed.

* Convert `.ttf` fonts to C/C++ arrays
* Adjustable font size, ASCII range, and addressing mode
* Visualize fonts from existing C/C++ headers
* GUI built with Tkinter
* Lightweight: only depends on `Pillow`

## Installation

1. [github repository](https://www.github.com/gavinlyonsrepo/Colossus_LTSM)
2. [Arch Linux AUR package](https://aur.archlinux.org/packages/colossus)
3. [Pypi package](https://pypi.org/project/colossus-ltsm/)

The program is present in python package index, Pypi.
Install (you can use *pip* or *pipx*) to the location or environment of your choice.

```python
# For example with pipx 
pipx install colossus-ltsm
```

## Libraries

[Pillow](https://python-pillow.org/) for image processing

## Usage

0. Github repository: Colossus_LTSM
1. PyPI package name: colossus-ltsm
2. Import path: import colossus_ltsm
3. Executable command: colossus

Run the GUI:

Select from application menu(if desktop entry installed) or run from terminal with:

```python
colossus
# or directly with Python
 python3 -m colossus_ltsm.colossus_main
```

## Input

* Select a `.ttf` font file
* Set font size, Width and Height(e.g., 12, 16, 24)
* Define ASCII range (e.g., 32-126)
* Choose data addressing mode (horizontal or vertical)
* Choose C or C++ arrays
* Choose file extension (.h or .hpp)
* Choose font name and file name
* Some ttf files are available in the `extras/ttf` directory for testing.

## Output

* Generates a C or C++ header file with bitmap arrays.
* Visualizes the font in the GUI, a PNG image can also be exported.

Example output :

```c
// Example Font
// An 8 by 8 character size font starting at 
// ASCII offset 0x30 in ASCII table with 0x02 characters in font. 
// 0 and 1 , size 20 bytes, 4 Control bytes at start.
static const std::array<uint8_t, 20> FontBinaryExample =
{
0x08, 0x08, 0x30, 0x01,   // x-size, y-size, offset, (last character-offset : 0x31-0x30)
0x7C,0xC6,0xCE,0xD6,0xE6,0xC6,0x7C,0x00, // ASCII font data '0' : 0x30
0x18,0x38,0x18,0x18,0x18,0x18,0x7E,0x00 // ASCII font data  '1' : 0x31
};
```

Exported PNG image of font data visualization:

![ img font ](https://github.com/gavinlyonsrepo/Colossus_LTSM/blob/main/extras/images/HomeSpun3232.png)

## Configuration file

The configuration file is created on startup and populated by default values.
The file is located at '~/.config/colossus_ltsm/colossus_ltsm.cfg' on Linux systems.

| Setting | Value | Default | Note |
| ------ | ------ | ----- | ----- |
| scale | int | 4 | Scale of font displayed |
| Columns | int | 16 | Number of columns of font characters to display |
| glyph color | hex color | #0078FF | Color of font glyphs in visualization |
| background color | hex color | #000000 | Background color for visualization |
| screen_resolution | str | 1000x800 | Window size for GUI on start up |
| debug | bool | False | Enable debug output to terminal |
| input_path | str | $HOME | input file path when a file dialog opens |
| output_path | str | $HOME | output file path when a file dialog opens |

## Desktop Entry

A button on the main GUI allows Linux users to install a desktop entry and icon for Colossus.This creates a `.desktop` file in `~/.local/share/applications/` and an icon in `~/.local/share/icons/`, allowing Colossus to be launched from the application menu. The button is automatically disabled if the desktop entry is already installed. Uses *Curl* to download the icon from GitHub and creates the desktop entry file with the correct paths.

## Glyph rendering

Glyph rendering help [readme.](extras/docs/README_glyph_help.md)
Explains how the converter measures and positions glyphs within the bitmap cell, and how to interpret messages in the conversion log related to width scaling and clipping.

## Screenshots

![ image ](https://github.com/gavinlyonsrepo/Colossus_LTSM/blob/main/extras/images/screenshot.png)

## Projects

Some of my libraries that use these fonts are:

| MCU type | Library link | Data adddressing mode |
| ------ | ------ | ----- |
| Arduino | [GFX](https://github.com/gavinlyonsrepo/display16_LTSM) | Horizontal |
| Raspberry Pi Pico | [GFX 16 bit](https://github.com/gavinlyonsrepo/displaylib_16bit_PICO) | Horizontal |
| Raspberry Pi Pico | [GFX 1 bit](https://github.com/gavinlyonsrepo/displaylib_1bit_PICO) | Vertical |
| Raspberry Pi | [GFX](https://github.com/gavinlyonsrepo/Display_Lib_RPI) | Horizontal |
| PIC | [OLED](https://github.com/gavinlyonsrepo/pic_18F47K42_projects ) | Vertical |

## See also

Guardian_LTSM is a Python tool for converting image files into C/C++ data arrays and for visualizing image data stored in C/C++ header files. It is aimed at users working with embedded systems, LCDs, and GUIs where compact images are needed.

[Guardian_LTSM](https://github.com/gavinlyonsrepo/Guardian_LTSM)
