graphics-braille 0.2.2

Create Braille maps for simple Turtle program output

Graphics Braille

We attempt to enable blind individuals to "visualize" simple graphics produced by simple programs which use Python's turtle module.

Graphics For The Blind - History / Overview

How it started:

For years, I have been introducing computer programming to the novice. I am always searching for better examples to catch and maintain their interest and attention. I landed on the idea of using simple programs to create simple figures such as squares or circles. We start with a short computer program, of 8 to 12 lines in length. This displays a multicolored square. Then we make a small program change and see what happens. This works nicely – for the sighted. But what about the blind? I developed a programming tool which enables the blind programmer to feel this simple figure.

Samples

For the sighted - screen shot containing the following two “windows”:

A: Program              B:Square Display

For the blind - screen shot containing the following four “windows”:

A: Program           B: Square display
C: Braille Depiction  D: Text created
                        for printer

The screen shot above shows four windows:

• (A) The program adjusted for the blind
• (B) The displayed square as seen by the sighted
• (C): The depiction of the figure’s Braille rendering.
• (D) The text “map” which, when sent to a Braille printer, creates a touchable rendition of the figure.

The basic logic

In our approach we divide the turtle graphics screen into 32 to 40 columns wide by 25 rows deep. We create a "text map" with a character representing the contents of each one column by one row region. For colored regions, we use the first letter of the region's color - r=red, o=orange, y=yellow, g==green, b==blue, i==indigo, v==violet. For other colors we use b (black). In general we use space for an empty region. To avoid possible compression of multiple spaces by Braille printer software, we convert non-trailing spaces into comma(,). In addition to turtle's standard graphics window, the following additions are created:

• A "text map" suitable for a low resolution physical display. The text map is placed in the Windows clip-board, from which it can be "pasted" into compatible applications such as a Braille printing application or a Zoom chat box for remote operation.
• A audio-draw-window which displays the expected braille - lower resolution(e.g. 40 x 25 braille cell) rendition of the turtle display
• The audio-draw-window supports many keyboard based window commands which provide positioning and reporting. These commands provide audio feedback of the current cursor position and contents. The audio feedback is user controlled with several levels of spoken text or audio tones.
• The audio-draw-window supports the selection of a portion of the displayed area with the creation of a new audio-draw-window, displaying of the selected region in greater detail.

Program Distribution (via pypi.org)

Setup (MS Windows)

• pip install from PyPI

  • TestPyPI

    py -m pip install --extra-index-url https://test.pypi.org/simple/ graphics-braille==0.1.29.dev1
    

  • Standard

  py -m pip install graphics-braille
  

Simple Testing / Viewing

Terminal Commands:

        gb, gbhelp - List graphics-braille commands
        gbfiles - copy user test files to Desktop/gb_exercises
        gbreadme - Display README.md (as seen on PyPI entry)
        gbtest - Do simple program test
        gbtest2 - simple program test 2 - spokes

Simple Startup tests

gbtest

or

gbtest2

In a handfull of seconds the following view should present on the screen. If audio is working, one should hear something like "green at row 14 column 20".

graphics_braille test Screenshot

Mac / Linux

The following tests should work but have not been fully tested.

python3 -m graphics_braille.z_show_square_loop_colors_braille 
python3 -m graphics_braille.wx_braille_display

Virtual Environment (venv)

It's optional, but we us it. It's no so hard. As of python3 venv is a standard module and need not be installed. Create the environment, activate the environment, do your stuff, and when done, deactivate the environmet.

Creating virtual environment

python -m venv venv
venv\Scripts\activate

Leaving environment

deactivate

Simple test (single process, only wxPython exercised)

Useful for debugging

py -m graphics_braille.wx_braille_display

Notable text map modifications

These changes were the results of experiences with and comments from some 8th grade students at the Perkins School for the Blind.

• Non-trailing blanks are replaced with "," characters so as not to be compressed by the braille producing software. The "," characters, while not being "blank" are single dot braille constructs, provide an "empty-like" view.
• Blank area above and to the left is reduced to facilitate viewers finding graphics objects.

A set of screen shots for a simple program

Example User program

turtle display window

Text map display (in clipboard)

braille display window - with audio feedback

Note that the color of the braille dots is for the implementer's view to empasize the color. Also the rectangles surrounding the dots are to further help the visual image.

Braille Window - audio feedback - An implementation aid, providing the likely braille view

Terminal output (wordy, mostly diagnostic in nature)

Keyboard / Menu commands

Keyboard display/positioning commands

        h - say this help message
        Up - Move up through run of same color/space
        Down - Move down through run of same color/space
        Left - Move left through run of same color/space
        Right - Move right through run of same color/space
        DIGIT - Move one square in direction (from current square):
           7-up left    8-up       9-up right
           4-left       5-mark     6-right
           1-down left  2-down     3-down right
              0-erase
        a - move to first(Left if Horizontal, Top if Vertical)
        b - move to second(Right if Horizontal, Bottom if Vertical)
        c<roygbiv> - set color red, orange, ...
        d - pendown - mark when we move
                
        g - Go to closest figure
        j - jump up to reduced magnification
        k - jump down to magnified region
        m - mark location
        p - Report/Say current position
        r - Horizontal position stuff to left, to Right
        t - Vertical position stuff to Top, to bottom
        u - penup - move with out marking 
        w - write out braille
        x - move to original cell (after a/b Horizontal/Vertical)
        z - clear board
        Escape - flush pending report output

File - Program control - Only Exit is functioning

        x - Exit program

Magnify - Magnification Control

        Help - list magnify commands (Alt-m) commands
        h - say this help message
        r - remove position history
        t - expand magnify selected region left/right
        s - select/mark magnify region
        t - expand magnify selected region up/down top/bottom
        v - view region (make new window)

Magnify supports the creation of a new audio-display-window, enlarging the currently selected region of the current audio-display-window. The selected region is the rectangular region encompasing the currently traversed squares.

###Currently options t is not implemented.

Navigate - Navigation commands from Navigate pulldown menu

        Help - list navigate commands (Alt-n) commands
        h - say this help message
        a - Start reporting position
        b - remove 
        z - stop reporting position
        e - echo input on
        o - echo off
        v - visible cells
        i - invisible cells
        r - redraw figure
        s - silent speech
        t - talking speech
        l - log speech
        m - show marked(even if invisible)
        n - no log speech
        p - report position
        u - audio beep
        d - no audio beep
         Escape - flush pending report output

Draw - Free drawing control

        Help - list drawing setup commands (Alt-d) commands
        h - say this help message
        d - Start/enable drawing
        s - stop/disable drawing
        Escape - flush pending report output

Scanning - Audio Window Scanning

        Help - list scanning commands (Alt-s) commands
        h - say this help message
        c - combine wave - faster scan
        d - disable combine wave - viewing in window
        k - toggle skip space
        s - Start scanning mode
        t - Stop scanning mode
        n - no_item_wait
        w - wait for items

Auxiliary - internal tracking / debugging

        Trace - tracing control

Program text printout - targeted for the brailler machine

Supported turtle commands

Because of our post running, screen scanning technique, we support all turtle commands, not requiring animation. That is, we take a static snapshot at the end of the program.

Our implementation has some harsh compromises:

• Our graphics resolution is currently 40 wide by 25 down for a 800 by 800 screen. Note this is further constrained by the fact that our students' shared braille embosser is set to 30 characters wide.
• Colors are represented by braille for the color's first letter(English)
• No motion - yet

TurtleBraille Support Files

• turtle_braille.py - direct outer interface to global turtle commands, and turtle object level commands
• braille_display.py - implements turtle commands in the braille setting and the creation of display braille window and text printout
• turtle_braille_link.py - simple link to support user level replacement of "from turtle import *" with "from turtle_braille_link import *" lines

TurtleBraille Trace / logging support

• select_trace.py
• crs_funs.py
• select_error.py
• select_report.py
• java_properties.py

resource_lib

Common files / support for other projects

Contains files used to support other projects. Provides logging, tracing, properties support.

Brief listing of document files (Docs directory)

• Program_Logging_Tracing.pptx PowerPoint presentation about Logging/Tracing demonstrating the classes SlTrace and TraceControlWindow

Brief listing of source files (src directory) with purpose.

• arrange_control.py: window sizing/placement support
• java_properties.py: simple properties file support
• logging_absolute_minimum.py: smallest example of logging
• logging_tracing_menu.py: TraceControlWindow class example
• logging_tracing_simplest.py: Simple logging/tracing example
• resource_group.py: support to handle a program's resource groups
• select_control.py class SelectControl
  • Base for independent control
  • Provides a singleton which is universally accessible
  • Facilitates
    • setting and retrieving of game controls
    • persistent storage of values
• select_dd_choice.py Dropdown choice one of n text strings - not sure
• select_error.py General local, to our program/game, error class
• select_trace.py class SlTrace
  • trace/logging package
  • derived from smTrace.java (ours)
  • properties file support
• select_window.py Program Level Menu control
• tkMath.py Useful window math thanks to: tkMath from recipe-552745-1.py Ronald Longo
• trace_control_window.py class TraceControlWindow
  • Window support for SlTrace flag manipulation
• variable_control.py class VariableControlWindow
  • Simple Control and Display of program variables
  • Adapted from trace_control_window.py/TraceControl
  • Essentially presents a scrollable list of variable names and values
  • Uses select_control/SelectControl to store and manipulate variable contents