{"id":19218900,"url":"https://github.com/openprinting/braille-printer-app","last_synced_at":"2025-06-26T15:32:54.928Z","repository":{"id":63348330,"uuid":"567179101","full_name":"OpenPrinting/braille-printer-app","owner":"OpenPrinting","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-09T00:09:31.000Z","size":210239,"stargazers_count":2,"open_issues_count":3,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-13T00:32:48.355Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenPrinting.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES-cups-filters.md","contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-17T08:38:26.000Z","updated_at":"2024-12-19T12:21:35.000Z","dependencies_parsed_at":"2025-04-20T20:42:23.106Z","dependency_job_id":null,"html_url":"https://github.com/OpenPrinting/braille-printer-app","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/OpenPrinting/braille-printer-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fbraille-printer-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fbraille-printer-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fbraille-printer-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fbraille-printer-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenPrinting","download_url":"https://codeload.github.com/OpenPrinting/braille-printer-app/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fbraille-printer-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262094735,"owners_count":23258025,"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-11-09T14:28:40.095Z","updated_at":"2025-06-26T15:32:54.904Z","avatar_url":"https://github.com/OpenPrinting.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenPrinting Braille Printer Application v2.0b1 - 2020-11-18\n\nLooking for compile instructions? Read the file \"INSTALL\"\ninstead...\n\n## INTRODUCTION\n\nCUPS is a standards-based, open-source printing system used by\nApple's Mac OS® and other UNIX®-like operating systems,\nespecially also Linux. CUPS uses the Internet Printing Protocol\n(\"IPP\") and provides System V and Berkeley command-line\ninterfaces, a web interface, and a C API to manage printers and\nprint jobs.\n\n`brf-printer-app` implements printing for a variety of common Braille printers\nconnected via network or USB.  Features include:\n\n- A single executable handles spooling, status, and server functionality.\n- Multiple printer support.\n- Each printer implements an IPP Everywhere™ print service and is compatible\n  with the driverless printing support in Linux®.\n- Each printer can directly print \"raw\", pdf,ubrl files.\n\nMore generally, this package includes backends, filters, and auxiliary files\nfor Braille embosser support, currently only as a classic CUPS printer driver\npackage.\n\nFor compiling and using this package see INSTALL file.\n\nReport bugs to\n\n    https://github.com/OpenPrinting/braille-printer-app/issues\n\nSee the \"COPYING\", \"LICENCE\", and \"NOTICE\" files for legal\ninformation. The license is the same as for CUPS, for a maximum of\ncompatibility.\n\n## BASIC USAGE\n\n`brf-printer-app` uses a single executable to perform all functions.  The normal\nsyntax is:\n\n    brf-printer-app SUB-COMMAND [OPTIONS] [FILES]\n\nwhere \"SUB-COMMAND\" is one of the following:\n\n- \"add\": Add a printer\n- \"cancel\": Cancel one or more jobs\n- \"default\": Get or set the default printer\n- \"delete\": Delete a printer\n- \"devices\": List available printers\n- \"drivers\": List available drivers\n- \"jobs\": List queued jobs\n- \"modify\": Modify a printer\n- \"options\": Lists the supported options and values\n- \"printers\": List added printer queues\n- \"server\": Run in server mode\n- \"shutdown\": Shutdown a running server\n- \"status\": Show server or printer status\n- \"submit\": Submit one or more files for printing\n\nYou can omit the sub-command if you just want to print something, for example:\n\n    brf-printer-app somefile.brf\n\nThe options vary based on the sub-command, but most commands support \"-d\" to\nspecify a printer and \"-o\" to specify a named option with a value, for example:\n\n- `brf-printer-app -d myprinter somefile.brf`: Print a file to the printer named\n  \"myprinter\".\n- `brf-printer-app -o media=na_letter_8.5x11in picture.brf`: Print a media to a US\n  letter sheet.\n- `brf-printer-app default -d myprinter`: Set \"myprinter\" as the default printer.\n\nSee the `brf-printer-app` man page for more examples.\n\n\nRunning the Server\n------------------\n\nNormally you'll run `brf-printer-app` in the background as a service for your\nprinter(s), using the systemd service file:\n\n    sudo systemctl enable brf-printer-app.service\n    sudo systemctl start brf-printer-app.service\n\nYou can start it in the foreground with the following command:\n\n    sudo brf-printer-app server -o log-file=- -o log-level=debug\n\nRoot access is needed on Linux when talking to USB printers, otherwise you can\nrun `brf-printer-app` without the \"sudo\" on the front.\n\n\nSupported Printers\n------------------\n\nThe following printers are currently supported:\n\n- Generic Braille embosser.\n\n\n## LINKS\n\n### The New Architecture of Printing and Scanning\n\n* [The New Architecture - What is it?](https://openprinting.github.io/current/#the-new-architecture-for-printing-and-scanning)\n* [Ubuntu Desktop Team Indaba on YouTube](https://www.youtube.com/watch?v=P22DOu_ahBo)\n\n### Printer Applications\n\n* [All free drivers in a PPD-less world - OR - All free drivers in Snaps](https://openprinting.github.io/achievements/#all-free-drivers-in-a-ppd-less-world---or---all-free-drivers-in-snaps)\n* [Current activity on Printer Applications](https://openprinting.github.io/current/#printer-applications)\n\n## DOCUMENTATION FROM CUPS-FILTERS 1.x\n\nMost of this is still valid for the current cups-filters.\n\n### BRAILLE EMBOSSING\n\ncups-filters also provides filters and drivers for braille\nembossers. It supports:\n\n- Text on all kinds of embossers with generic support\n- Text and graphics on the Index V3 embossers and above.\n\nThis is configured in CUPS just like any printer. Options can then be configured\nin the standard printer panel, or passed as -o options to the lp command.\n\n\n#### Text support\n\nText can be embossed either with no translation on the computer side (the\nembosser will translate), or with translation on the computer side (thanks to\nliblouis). It is a matter of running\n\n    lp file.txt\n\nor even\n\n    lp file.html\n    lp file.odt\n    lp file.doc\n    lp file.rtf\n    lp file.docx\n    lp file.pdf\n\nImportant: it is really preferrable to directly print the document files\nthemselves, and not a pdf output, or printing from the application (which\nwould first convert to pdf). That way, the braille conversion will have the\nproper document structure (paragraphs, titles, footnotes, etc.) to produce good\nquality.\n\n\n#### Vector Image support\n\nVector images can be embossed by converting them to braille dots.\n\nThis needs the inkscape package installed. Various input formats are then\nsupported: .svg, .fig, .wmf, .emf, .cgm, .cmx\n\nThe conversion assumes that the input is black-on-white. If it is\nwhite-on-black, the -o Negate option can be used.\n\nThis image support is preferred over the generic image support described below,\nwhich has to reconstruct lines to be embossed.\n\n\n#### Image support\n\nImages can be embossed by converting them to braille dots.\n\nThe orientation of the image can be controlled. By default it will be rotate to\nfit the image orientation, i.e. it will be rotate by 90 degree if it is wider\nthan high and the paper is higher than wide, or if vice-versa. Other rotation\nmodes are provided.\n\nBy default, the image will be resized to fit the size of the paper. Disabling\nthe resize (fitplot set to No) will crop the image to the paper size. This is\nuseful for instance when a carefully-drawn image was designed especially for\nembossing, and thus its pixels should exactly match with braille dots. In such\ncase, edge detection should very probably be disabled too.\n\nThe image can be processed for edge detection. When no processing is done (edge\ndetection is configured to \"None\"), the dark pixels are embossed if the Negate\noption is off, or the light pixels are embossed if the Negate option is on. When\nedge processing is done, only the edges of the images will be embossed. The\nBasic and the Canny algorithms bring differing results. The Basic algorithm\ncan be tuned thanks to the edge factor only. The Canny algorithm can also be\ntuned: increasing the Upper value will reduce the amount of detected edges (and\nvice-versa), increasing the Lower value will reduce the lengths of the detected\nedges (and vice-versa). The Radius and Sigma parameter control the blurring\nperformed before edge detection, to improve the result; the Radius parameter\ncontrols how large blurring should be performed, setting it to zero requests\nautodetection; the Sigma parameter determines how strongly blurring should be\nperformed.\n\nA lot of images formats are support, so one can just run\n\n    lp file.png\n    lp file.gif\n    lp file.jpg\n    ...\n\nHere are complete examples for controlling the processing (all options can be\nomitted, the default values are shown here):\n\nEmboss the image without edge detection, as black on white or white on black:\n\n    lp -o \"Edge=None\" file.png\n    lp -o \"Edge=None Negate\" file.png\n\nEmboss the image with edge detection, the default tuning parameters are set\nhere:\n\n    lp -o \"Edge=Edge EdgeFactor=1\" file.png\n    lp -o \"Edge=Canny CannyRadius=0 CannySigma=1 CannyLower=10 CannyUpper=30\" file.png\n\nEmboss the image as it is, without any resize or edge detection, as black on\nwhite or white on black:\n\n    lp -o \"nofitplot Edge=None\" file.png\n    lp -o \"nofitplot Edge=None Negate\" file.png\n\n\n#### Generic embosser support\n\nIt should be possible to make all embossers use the generic driver. For this to\nwork, one has to:\n\n- configure the embosser itself so that it uses an MIT/NABCC/BRF braille table\n- add in CUPS a printer with the \"Generic\" manufacturer and \"Braille embosser\"\n  model\n- configure CUPS options according to the embosser settings, so that CUPS knows\n  the page size, braille spacing, etc.\n\nThe generic driver can emboss text, as well as images, but images will probably\nbe distorted by the Braille interline spacing.\n\n\n#### Index embossers support\n\nSupported models:\n\n- Basic-S V3/4\n- Basic-D V3/4\n- Everest-D V3/4\n- 4-Waves PRO V3\n- 4X4 PRO V3\n- Braille Box V4\n\nIndex V3 embosser support has been well tested. It supports both text and\ngraphics mode.  Embossers with firmware 10.30 and above can be easily configured\nfrom CUPS (paper dimension, braille spacing, etc.).\n\nIndex V4 embosser support has not been tested, but is very close to V3 support,\nso it is probably working fine already.  Feedback would be very welcome.\n\nTo connect an Index embosser through Ethernet, gather its IP adress, select the\n\"AppSocket/HP JetDirect\" network printer protocol, and set\nsocket://the.embosser.IP.address:9100 as Connection URL.\n\nThe density of dots for images can easily be chosen from the command line, for\ninstance:\n\n    lp -o \"GraphicDotDistance=160\" file.png\n\nto select 1.6mm dots spacing\n\nTroubleshooting: if your embosser starts every document with spurious\n\"TM0,BM0,IM0,OM0\" or \"TM0,BI0\", your embosser is most probably still using an\nold 10.20 firmware.  Please either reflash the embosser with a firmware version\n10.30 or above, or select the 10.20 firmware version in the \"index\" panel of the\ncups printer options.\n\n\n#### Braille output options\n\nThe output can be finely tuned from the standard printing panel, or from the\ncommand-line, the following example selects translation tables for French and\nGreek, with 2.5mm dot spacing and 5mm line spacing. All options can be omitted,\nthe default values are shown here.\n\n    lp -o \"LibLouis=fr-fr-g1 LibLouis2=gr-gr-g1 TextDotDistance=250 LineSpacing=500\" file.txt\n\n\n#### Reworking output before embossing\n\nOne may want to check and modify the .brf or .ubrl output before sending it to\nthe embosser.  This can be achieved by first generating the .brf file:\n\n    /usr/sbin/cupsfilter -m application/vnd.cups-brf -p /etc/cups/ppd/yourprinter.ppd yourdocument.txt \u003e ~/test.brf\n\nOne can choose a ppd file and additionally pass -o options to control the\ngenerated output. One can then modify the .brf file with a text editor. One can\nthen emboss it:\n\n    lp -o document-format=application/vnd.cups-brf ~/test.brf\n\n\nThe same can be achieved for images:\n\n    /usr/sbin/cupsfilter -m image/vnd.cups-ubrl -p /etc/cups/ppd/yourprinter.ppd yourimage.png \u003e ~/test.ubrl\n\n    lp -o document-format=image/vnd.cups-ubrl ~/test.ubrl\n\n\n#### BRF file output\n\nOne can generate BRF files by adding a virtual BRF printer.\n\nWhen creating it in the cups interface, choose the CUPS-BRF local printer,\nselect the Generic maker, and choose the Generic Braille embosser model.\n\nPrinting to the resulting printer will generate a .brf file in a BRF\nsubdirectory of the home directory.\n\n\n#### UBRL file output\n\nOne can generate Unicode braille files, not useful for embossing, but which can\nbe easily looked at by sighted people to check for the output.\n\nIn the cups interface, create a printer with the CUPS-BRF local printer,\nthe Generic maker, and choose the Generic UBRL generator model.\n\nPrinting to the resulting printer will generate a .brf file in a BRF\nsubdirectory of the home directory.\n\n\n#### Remark about the source code\n\nThe file driver/index/ubrlto4dot.c is used to generate\nthe translation table in\ndriver/index/imageubrltoindexv[34]. It is included as\n\"source code\" for these two files, even if actually running the\ngeneration in the Makefile is more tedious than really useful.\n\n\n#### TODO\n\n- Test whether one wants to negate, e.g. to emboss as few dots as possible\n- textubrltoindex when liblouis tools will be able to emit 8dot braille\n\n## LEGAL STUFF\n\nFilter used to convert various file format are in cups-filter is Copyright © 2022, 2024 by Samuel Thibault (samuel.thibault@ens-lyon.org).\n\nThe Braille Printer Application is Copyright © 2024 by Arun Patwa .\nSome of the reference has been taken from (https://github.com/chandresh-soni/Braille-printer-app) which is copyright © 2022 by Chandresh Soni.\nand also from pappl-retrofit.(https://github.com/OpenPrinting/pappl-retrofit) which is Copyright © 2022 by openprinting.\n\nIt is derived from the HP PCL Printer Application, a first working model of\na raster Printer Application using PAPPL. It is available here:\n\nhttps://github.com/michaelrsweet/hp-printer-apps\n\nThe HP PCL Printer Application is Copyright © 2019-2020 by Michael R Sweet.\n\nThis software is licensed under the Apache License Version 2.0.  See the files\n\"LICENSE\" and \"NOTICE\" for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenprinting%2Fbraille-printer-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenprinting%2Fbraille-printer-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenprinting%2Fbraille-printer-app/lists"}