pybrl is an Open-Source Grade-2 Braille Translation system written entirely in Python. It is flexible and any new language can be imported in 10-minutes.
How to use?
The usage of pybrl is super simple:
In : import pybrl as brl In : brl.translate("Hello World") # Test for English Out: [[u'000001', u'110010', u'100010', u'111000', u'111000', u'101010'], [u'000001', u'010111', u'101010', u'111010', u'111000', u'100110']] In : example = _ In : brl.translate("English with Ελληνικά") # Test with multiple languages Out: [[u'000001', u'100010', u'101110', u'110110', u'111000', u'010100', u'100101'], [u'011111'], [u'000010', u'100010', u'111000', u'111000', u'001110', u'101110', u'010100', u'101000', u'000010', u'000101']] In : brl.toUnicodeSymbols(example, flatten=True) Out: u'\u2820 \u2813 \u2811 \u2807 \u2807 \u2815 \u2820 \u283a \u2815 \u2817 \u2807 \u2819' In : print _ ⠠⠓⠑⠇⠇⠕ ⠠⠺⠕⠗⠇⠙
It has automatic language detection, and recognizes different languages as you translate.
Open the directory of the project in the Terminal and run:
pip install -r requirements.txt
(You will probably need to add
sudo in the beginning of that command. Do so if you get Permission errors.)
How to import a new Language?
Each Language file is located under the
languages directory. It has 3 dictionaries:
alphabetcontains all the alphabet characters and combinations which have separate shorthand braille symbols (such as
contractionscontains complete words which can be abbreviated into simpler combinations of braille cells. For instance,
childcan be represented by the same symbol as
specialCharacterscontains braille indicators and special symbols such as
[. Indicators are built-in with special variable representations like
$emph. There is a difference between the
%are automatically handled by the translation system (i.e. if a letter is capital), but the
$cannot because they are usually font-related (i.e.: italic letters).
Check out the
languages/english.py file for example.
For more details please refer to the
docs/Language File Structure.txt file.
If the language supports Grade-2 translation, the program supports it.
Moreover, the output of the translation is a list which has the following format:
[[u'110000', u'111010', u'111000']] # This means "braille" in Grade-2 Translation
Each list represents one word, and each string in that sublist is a Braille cell. The following image shows the corresponding position in the cell:
If a cell character is a 1, then the corresponding dot in the cell is filled:
Note that in the language files, the following cell representation is valid:
which can be used if a character or symbol uses more than one cell to be represented in Braille (in this example it uses 2 cells).
The translator will automatically split the cells into segments of 6 characters, so the output of the system is consistent.
Jupyter Notebooks for example usage:
docs/Samples directory, I have some Jupyter Notebooks with example usage of
pybrl. Going through them is a great way to learn the tool and how it works.
- Translate PDF files and create new ones using
- Learn how data is formated within
docs/TODO.txt file for an updated list.
What is missing?
The Nemeth code is not integrated yet. Specifically it needs:
- Convert the keys in
nemeth.dictfile to be used within pybrl.
- Complete the Logic that handles the Nemeth code translation
- Convert the keys in
A solid way to convert files such as PDFs or Word Documents into a plain format that can be used in the program. Thoughts on how to do this so far:
Convert the Document pages into Images.
Use/Integrate tools such as PDFMiner to extract text and images (it is useful that it provides information about the position of the text)
Use an OCR-based method to analyze Equations. There will be exclusive preprocessing of the Equations to first convert it into MathML (which can already be parsed by pybrl).
How to contribute if you are a Developer?
If you want to contribute in this project, please do so by opening a Pull request.
If you are motivated and want to help developing this project, please send me an email at antonis.katzourakis (I use gmail).
How can you help if you are not a Developer?
Add a new Language File: Check out the existing language files (under the
languagesdirectory) and read the instructions in the How to import a new Language part of this README. You will find a sample language file to start in the
Add more Contractions in the Language Files: You can edit the language files, and add more contractions in the corresponding dictionary. Right now, only a few are listed, but there are many more that will be added. Check it out and see how easy it is in the
How this project started?
A mathematician friend of mine works at a school which is located in a remote village in Crete, Greece. A student of hers is blind. Since the facilities of the school are limited, I was trying to find an affordable Braille printer for him. The programs that the specific school has are really limited. If Greek and Math are combined into one piece of text, the Braille that is printed is unreadable. On top of that, the printer that is available is quite old and thus has a lot of problems. I soon figured out that most machines cost 2000$ or more. I decided to build a printer for him. Having almost no experience with Braille, I researched on how it works and how these printers work. However, I first needed to find a complete translation program, which supports at least English, Greek and Mathematics. Most programs (either commercial or non-commercial) that are available right now are either not complete, or expensive (usually they are both).
The first days of this project were a reality-check: We take things for granted and these people are not taken into account for many things in this world. I don't want to go into detail about the handling of blind students in Greece, but I will only mention that they are completely unable to do the National exams on the last grade of Highschool, because the Ministry of Education in Greece forbids the translation of the exams into Braille. Moreover, the Math books that these students get, have all the exercises omitted, on the justification that "they need to be done under a teacher's supervision". This is just not the way to go.
This is just an example why the world needs a complete Braille translation program and affordable Braille printers.
Where does this project go?
This program will be integrated on an open-source Braille printer. I haven't started designing it yet, since the correct translation of documents is most important. The main idea is that any document will be translated on the printer, giving the ability of the blind to translate any digital document themselves.
- The Language detection works great, but it can fail on similar languages (i.e. German and Dutch). However, such languages usually share the same Braille alphabet, so there is really low chance of failure. Remember to check if the translated text is correct though - I hadn't any occurrencies of bad translations, but I cannot guarantee that.
- Math is not ready yet. There is a lot of work to do there...
tests directory, I include unit tests for different functionalities of pybrl. You can run them individually or all of them by:
pybrl is licensed under GNU-GPL. You can find a copy of the license in this repository. What does that mean?