Skip to content

README.pod

Latest commit

 

History

History
135 lines (75 loc) · 3.75 KB

README.pod

File metadata and controls

135 lines (75 loc) · 3.75 KB
Raw

OVERVIEW

BrailleToBitmap.pl version 1.00

This script converts Braille text to a bitmap.

I had to write this script because I had some simple code which misuses Braille to draw pictures, and ImageMagick can write Braille but not read it.

You need a Perl interpreter installed on your system to run this script.

USAGE

perl BrailleToBitmap.pl [options] [--] <braille-input.txt> <bitmap-output.ppm>

OPTIONS

  • -h, --help

    Print this help text.

  • --help-pod

    Preprocess and print the POD section. Useful to generate the README.pod file.

  • --version

    Print this tool's name and version number (1.00).

  • --license

    Print the license.

  • --verbose

    Show progress information.

  • --

    Terminate options processing. Useful to avoid confusion between options and filenames that begin with a hyphen ('-'). Recommended when calling this script from another script, where the filename comes from a variable or from user input.

BRAILLE TEXT INPUT FILE FORMAT

The input file format consists of text lines with Unicode 8-dot Braille characters in the range U+2800..U+28FF.

An example file x-in-a-rectangle-box-as-braille.txt is distributed with this script.

A future version of this script may support other Braille characters, like the 6-dot variant.

No extraneous characters are tolerated.

The file encoding must be UTF-8, with or without the UTF-8 BOM.

The end-of-line marker can be either Unix (LF) or Windows (CR, LF).

A text line is not allowed to be empty.

Normally, the Braille "picture" is a rectangle, but the text lines do not have to be of the same length. The resulting bitmap rows are padded as needed.

This file format is similar to ImageMagick's UBRL format, but beware that ImageMagick prepends a header with resolution information, and that header is not supported by this script, so you would have to manually remove it.

This is how to convert a PNG to UBRL with ImageMagick for test purposes:

convert -negate monochrome-picture.png UBRL:picture-as-ubrl.txt

Option -negate inverts the black/white colours to match what this script generates.

After manually removing the header at the beginning of the file, you can then feed it to this tool.

BITMAP OUTPUT FILE FORMAT

The output bitmap file is generated in Portable Pixmap format (PPM), in text format (the type is then P3). This format can be read by GIMP, ImageMagick and other programs.

The background is black, and a Braille dot translates to a white pixel.

The following ImageMagick command converts such a PPM file into a PNG:

convert bitmap-output.ppm converted.png

You may need to specify option -negate in order to invert the black/white colours.

EXIT CODE

An exit code of 0 means success, any other value signals an error.

FEEDBACK

Please send feedback to rdiez-tools at rd10.de

LICENSE

Copyright (C) 2026 R. Diez

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License version 3 for more details.

You should have received a copy of the GNU Affero General Public License version 3 along with this program. If not, see http://www.gnu.org/licenses/.