{"id":23190595,"url":"https://github.com/mlang/img2brl","last_synced_at":"2025-08-18T19:31:55.978Z","repository":{"id":10510924,"uuid":"12698056","full_name":"mlang/img2brl","owner":"mlang","description":"Web service for translating images to braille","archived":false,"fork":false,"pushed_at":"2020-10-27T13:04:05.000Z","size":158,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-14T00:30:46.985Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://img2brl.delysid.org/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-09-09T09:45:08.000Z","updated_at":"2024-08-14T00:30:46.986Z","dependencies_parsed_at":"2022-09-15T21:52:51.358Z","dependency_job_id":null,"html_url":"https://github.com/mlang/img2brl","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlang%2Fimg2brl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlang%2Fimg2brl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlang%2Fimg2brl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlang%2Fimg2brl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlang","download_url":"https://codeload.github.com/mlang/img2brl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230268715,"owners_count":18199806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-18T12:15:02.669Z","updated_at":"2024-12-18T12:15:03.230Z","avatar_url":"https://github.com/mlang.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A web service for converting arbitrary image data to braille representation\n\nimg2brl is a web service to convert arbitrary image formats to a tactile\nrepresentation based on\n[Unicode braille](http://en.wikipedia.org/wiki/Unicode_braille).  It can be\nused by a braille user to gather information about an image file without needing\nsighted assistance.\n\nA refreshable braille display or braille embosser will be needed to make\nuse of the output of this program.\n\nThe idea is as simple as it can get: Provide an image file from your computer,\nor enter an URL to an image on the web.  If the image can be read by\n[ImageMagick](http://imagemagick.org/), it will be converted to Unicode Braille\nand can be touched in the browser.\n\nA live installation of this program can be found\n[here](http://img2brl.delysid.org/).\n\n# Installation\n\nSince all the functionality provided is contained in a single compiled\nexecutable, installation can be very simple.\n\n## Dependencies\n\nYou need\n\n* [Git](http://git-scm.com/)\n* [CMake](http://cmake.org/)\n* A C++ compiler like [GCC](http://gcc.gnu.org/) or\n  [Clang](http://clang.llvm.org/)\n* [GNU cgicc](http://www.gnu.org/software/cgicc/)\n* [Boost](http://boost.org/) (locale and Spirit)\n* [ImageMagick](http://imagemagick.org/)\n* [libcurl](http://curl.haxx.se/)\n\n## Clone\n\n    $ git clone http://img2brl.delysid.org/ img2brl\n\n## Compile\n\n    $ cd img2brl\n    $ cmake . \u0026\u0026 make\n\n## Run\n\nYou can now copy img2brl.cgi into your cgi-bin directory, and you should be\nready to go.\n\n## Running your own git-based fork\n\nTo allow for automatic building of the CGI program upon git push, you need\ntwo git repositories on your webserver.  A bare repository which will also\ncontain the CGI program later on, and a working tree which will be used\nto build the program.\nIf you configure the location of your working tree via\ngit config img2brl.src in the bare repository, the\n[post-update hook](https://github.com/mlang/img2brl/blob/master/git-post-update-hook)\nwill automatically build and install changes to your repository upon push.\n\n[img2brl@delysid](http://img2brl.delysid.org/) is approximately configured like\nthis:\n\n    remote$ git clone --bare https://github.com/mlang/img2brl img2brl\n    remote$ git clone img2brl img2brl.src\n    remote$ cd img2brl.src\n    remote$ cmake -DCMAKE_INSTALL_PREFIX=../img2brl -DCMAKE_BUILD_TYPE=RELEASE .\n    remote$ make install\n    remote$ git --git-dir=../img2brl config img2brl.src $(pwd)\n    remote$ exit\n    local$ git clone remote:/home/user/img2brl\n    local$ cd img2brl\n    local$ cmake .\n\nYou can now do changes locally, and test them by locally running make, to\nsee if the program still compiles.  If you decide to push your\nchanges, they will automatically get compiled on the remote webserver, and an\nup-to-date binary (img2brl.cgi) will be installed into /home/user/img2brl.\n\n    local$ git push\n    Counting objects: 16, done.\n    Delta compression using up to 4 threads.\n    Compressing objects: 100% (12/12), done.\n    Writing objects: 100% (12/12), 1.41 KiB | 0 bytes/s, done.\n    Total 12 (delta 7), reused 0 (delta 0)\n    remote: -- Configuring done\n    remote: -- Generating done\n    remote: -- Build files have been written to: /home/user/img2brl.src\n    remote: Scanning dependencies of target img2brl.cgi\n    remote: [100%] Building CXX object CMakeFiles/img2brl.cgi.dir/img2brl.cc.o\n    remote: Linking CXX executable img2brl.cgi\n    remote: [100%] Built target img2brl.cgi\n    remote: Install the project...\n    remote: -- Install configuration: \"RELEASE\"\n    remote: -- Installing: /home/user/img2brl/img2brl.cgi\n    remote: -- Up-to-date: /home/user/img2brl/favicon.png\n    remote: -- Up-to-date: /home/user/img2brl/hooks/post-update\n    To user@remote:/home/user/img2brl\n       1696b99..66316db  master -\u003e master\n\nWhat is missing now is to configure your remote webserver to serve\n/home/user/img2brl at the URL of your choice.\nYou will likely need to enable CGI execution in that directory, and perhaps have\nimg2brl.cgi served as the index page.\n\n### Local testing\n\nIf you want to minimize mistakes on your online site, it can be helpful to\nconfigure your local webserver to also serve an installation of img2brl.cgi.\nYou do not need to setup a bare repository, since your remote webserver\nwill already provide one.  You will likely want to provide CMAKE_INSTALL_PREFIX\nto cmake in your local work tree and have it point to a location\nwhich is served by your local webserver.  You can then very easily test\nchanges by executing \"make install\" in your local work tree, and visiting your\nlocal webserver to observe the effect.\n\n    local$ cmake -DCMAKE_INSTALL_PREFIX=~/public_html/img2brl .\n    ...\n    local$ make install\n    local$ lynx http://localhost/~user\n\nIf you are happy with a change (or maybe after \"git rebase -i\") you can run\n\"git push\" which will compile and install the current version on your remote\nwebserver.\n\n# API\n\n## Output formats\n\nimg2brl can produce output in various formats:\n\n* mode=html: XHTML 1.0, the default.\n* mode=json: JSON for easy parseability.\n* mode=text: text/plain utf-8 encoded unicode braille.  This format omits all\n  metadata and will only present the requested image in unicode braille text.\n\n## Parameters\n\nThe following GET and POST request parameters can be used:\n\n* img: An image file, uploaded via multipart/form-data.\n* url: The URL of the image data to process.\n* mode: One of html, json or text.\n* trim=on: Trim edges with the same color as the background automatically.\n* resize=on: Enable resizing to a maximum, see cols=.\n* cols=INTEGER: If resize=on was provided, ensure that the braille output is at\n  maximum INTEGER columns wide.\n\n## Examples\n\nUpload a file and present its unicode braille representation as text:\n\n    curl --silent --form mode=text --form img=@favicon.png http://img2brl.delysid.org/\n\nRequest the Unicode braille representation of img2brl's favicon for processing with JSON:\n\n    curl --silent --data mode=json --data url=http://img2brl.delysid.org/favicon.png http://img2brl.delysid.org/\n\nRequest plain Unicode braille representation of a design from [tactileview.com](http://tactileview.com/) trimmed and with at most 40 columns width (80 dots):\n\n    curl --silent --data mode=text --data url=http://tactileview.com/pbimages/koekkoeksklok_middle2366.png --data resize=on --data cols=40 http://img2brl.delysid.org/\n\nParse JSON output with Emacs Lisp:\n\n    (with-temp-buffer\n      (url-insert-file-contents\n       (concat \"http://img2brl.delysid.org/\"\n               \"?url=http://img2brl.delysid.org/favicon.png\"\n               \"\u0026mode=json\"))\n      (json-read))\n\nproduces the following output:\n\n    ((runtime\n      (seconds . 0.224454))\n     (braille . \"⡏⠉⠉⠉⠉⠉⠉⢹\\n⡇⢨⡅⠮⢩⡆⣤⢸\\n⡇⢸⡇⣔⢧⡀⣤⢸\\n⣇⣀⣀⣀⣀⣀⣀⣸\\n\")\n     (height . 16)\n     (width . 16)\n     (src\n      (height . 16)\n      (width . 16)\n      (comment . \"Created with GIMP\")\n      (format . \"Portable Network Graphics\")\n      (content-type . \"image/png\")\n      (url . \"http://img2brl.delysid.org/favicon.png\")))\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlang%2Fimg2brl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlang%2Fimg2brl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlang%2Fimg2brl/lists"}