A web service for converting arbitrary image data to braille representation
img2brl is a web service to convert arbitrary image formats to a tactile representation based on Unicode braille. It can be used by a braille user to gather information about an image file without needing sighted assistance.
A refreshable braille display or braille embosser will be needed to make use of the output of this program.
The idea is as simple as it can get: Provide an image file from your computer, or enter an URL to an image on the web. If the image can be read by ImageMagick, it will be converted to Unicode Braille and can be touched in the browser.
A live installation of this program can be found here.
Since all the functionality provided is contained in a single compiled executable, installation can be very simple.
$ git clone http://img2brl.delysid.org/ img2brl
$ cd img2brl $ cmake . && make
You can now copy img2brl.cgi into your cgi-bin directory, and you should be ready to go.
Running your own git-based fork
To allow for automatic building of the CGI program upon git push, you need two git repositories on your webserver. A bare repository which will also contain the CGI program later on, and a working tree which will be used to build the program. If you configure the location of your working tree via git config img2brl.src in the bare repository, the post-update hook will automatically build and install changes to your repository upon push.
img2brl@delysid is approximately configured like this:
remote$ git clone --bare https://github.com/mlang/img2brl img2brl remote$ git clone img2brl img2brl.src remote$ cd img2brl.src remote$ cmake -DCMAKE_INSTALL_PREFIX=../img2brl -DCMAKE_BUILD_TYPE=RELEASE . remote$ make install remote$ git --git-dir=../img2brl config img2brl.src $(pwd) remote$ exit local$ git clone remote:/home/user/img2brl local$ cd img2brl local$ cmake .
You can now do changes locally, and test them by locally running make, to see if the program still compiles. If you decide to push your changes, they will automatically get compiled on the remote webserver, and an up-to-date binary (img2brl.cgi) will be installed into /home/user/img2brl.
local$ git push Counting objects: 16, done. Delta compression using up to 4 threads. Compressing objects: 100% (12/12), done. Writing objects: 100% (12/12), 1.41 KiB | 0 bytes/s, done. Total 12 (delta 7), reused 0 (delta 0) remote: -- Configuring done remote: -- Generating done remote: -- Build files have been written to: /home/user/img2brl.src remote: Scanning dependencies of target img2brl.cgi remote: [100%] Building CXX object CMakeFiles/img2brl.cgi.dir/img2brl.cc.o remote: Linking CXX executable img2brl.cgi remote: [100%] Built target img2brl.cgi remote: Install the project... remote: -- Install configuration: "RELEASE" remote: -- Installing: /home/user/img2brl/img2brl.cgi remote: -- Up-to-date: /home/user/img2brl/favicon.png remote: -- Up-to-date: /home/user/img2brl/hooks/post-update To user@remote:/home/user/img2brl 1696b99..66316db master -> master
What is missing now is to configure your remote webserver to serve /home/user/img2brl at the URL of your choice. You will likely need to enable CGI execution in that directory, and perhaps have img2brl.cgi served as the index page.
If you want to minimize mistakes on your online site, it can be helpful to configure your local webserver to also serve an installation of img2brl.cgi. You do not need to setup a bare repository, since your remote webserver will already provide one. You will likely want to provide CMAKE_INSTALL_PREFIX to cmake in your local work tree and have it point to a location which is served by your local webserver. You can then very easily test changes by executing "make install" in your local work tree, and visiting your local webserver to observe the effect.
local$ cmake -DCMAKE_INSTALL_PREFIX=~/public_html/img2brl . ... local$ make install local$ lynx http://localhost/~user
If you are happy with a change (or maybe after "git rebase -i") you can run "git push" which will compile and install the current version on your remote webserver.
img2brl can produce output in various formats:
- mode=html: XHTML 1.0, the default.
- mode=json: JSON for easy parseability.
- mode=text: text/plain utf-8 encoded unicode braille. This format omits all metadata and will only present the requested image in unicode braille text.
The following GET and POST request parameters can be used:
- img: An image file, uploaded via multipart/form-data.
- url: The URL of the image data to process.
- mode: One of html, json or text.
- trim=on: Trim edges with the same color as the background automatically.
- resize=on: Enable resizing to a maximum, see cols=.
- cols=INTEGER: If resize=on was provided, ensure that the braille output is at maximum INTEGER columns wide.
Upload a file and present its unicode braille representation as text:
curl --silent --form mode=text --form firstname.lastname@example.org http://img2brl.delysid.org/
Request the Unicode braille representation of img2brl's favicon for processing with JSON:
curl --silent --data mode=json --data url=http://img2brl.delysid.org/favicon.png http://img2brl.delysid.org/
Request plain Unicode braille representation of a design from tactileview.com trimmed and with at most 40 columns width (80 dots):
curl --silent --data mode=text --data url=http://tactileview.com/pbimages/koekkoeksklok_middle2366.png --data resize=on --data cols=40 http://img2brl.delysid.org/
Parse JSON output with Emacs Lisp:
(with-temp-buffer (url-insert-file-contents (concat "http://img2brl.delysid.org/" "?url=http://img2brl.delysid.org/favicon.png" "&mode=json")) (json-read))
produces the following output:
((runtime (seconds . 0.224454)) (braille . "⡏⠉⠉⠉⠉⠉⠉⢹\n⡇⢨⡅⠮⢩⡆⣤⢸\n⡇⢸⡇⣔⢧⡀⣤⢸\n⣇⣀⣀⣀⣀⣀⣀⣸\n") (height . 16) (width . 16) (src (height . 16) (width . 16) (comment . "Created with GIMP") (format . "Portable Network Graphics") (content-type . "image/png") (url . "http://img2brl.delysid.org/favicon.png")))