Metadata-Version: 1.0
Name: mplh5canvas
Version: 0.6
Summary: A matplotlib backend based on HTML5 Canvas.
Home-page: http://code.google.com/p/mplh5canvas/
Author: Simon Ratcliffe, Ludwig Schwardt
Author-email: sratcliffe@ska.ac.za, ludwig@ska.ac.za
License: BSD
Description: Matplotlib HTML5 Canvas Backend
        ===============================
        
        This provides a web-delivered interactive matplotlib backend using HTML5
        technologies including `WebSocket`_ and the `Canvas`_ element.
        
        Our main goal is to have a backend that is consistent across multiple platforms,
        has few installation dependencies, is easy and fast to animate, and retains
        compatibility with current matplotlib usage scenarios.
        
        Installation instructions can be found below or on the project's `Wiki`_ page.
        The short answer::
        
          easy_install mplh5canvas
        
        Features
        --------
        
        - Pure Python
        - Uses mod_pywebsocket to provide multi browser support through multiple websocket standards
        - Requires web browser with Canvas and WebSocket support (Chrome 4+, Safari 5+ (OSX and IOS)
          work out of the box. Opera 11+ works after enabling WebSockets in preferences. Firefox
          is not supported and Internet Explorer will never be supported.)
        - Designed with animation and interactivity in mind (resizable, zoomable,
          clickable regions, etc)
        - Simple plots (e.g. a 2048-point line plot) can be animated at around 60 frames
          per second
        - Allows proper remote access to plots
        - Allows multiple concurrent access to plots
        - Thumbnail window allows quick cycling between plots on a single page
        
        Screenshot
        ----------
        
        .. image:: http://mplh5canvas.googlecode.com/files/screenshot.png
           :height: 600px
        
        .. _WebSocket: http://en.wikipedia.org/wiki/WebSockets
        .. _Canvas: http://en.wikipedia.org/wiki/Canvas_element
        .. _Wiki: http://code.google.com/p/mplh5canvas/wiki/Installation
        
        
        Requirements
        ------------
        
        We have tried to keep this module as free of dependencies as possible in order
        to open up the widest possible installation base. We do however depend
        on the excellent `pywebsocket`_ code for handling our browser
        communications. This allows us to better track the WebSocket standard
        as it continues to evolve.
        
        The current base system requirements prior to installation are:
        
        * Python 2.5 or newer (2.4 should also be OK, but has not been tested)
        * `Matplotlib`_ 0.99.1.1 or newer
        
        The web browser you use to display the plots must support Canvas and WebSockets
        (see http://caniuse.com/#feat=websockets for a summary of current WebSocket
        support). The status quo for the main browsers in May 2011 is:
        
        * **Chrome 9.0+** works out of the box and is the target browser
        
        * **Safari 5.0+** works out of the box (both OSX and IOS versions)
        
        * **Firefox 4.0** works after unblocking WebSocket support:
        
            - Browse to the ``about:config`` preferences page and promise to be careful
            - Type ``websocket`` in the filter to find the right option
            - Double-click on ``network.websocket.override-security-block`` to set it to ``true``
        
        * **Firefox 5.0+** is not supported due to a custom websocket class.
        
        * **Opera 11.0+** works after unblocking WebSocket support:
        
            - Browse to the Preference Editor at the ``opera:config`` page
            - Type ``websocket`` in the "Quick find" search field to zoom in on the
              right option ("Enable WebSockets" under User Prefs)
            - Check the tickbox and click on the Save button
        
        * **Internet Explorer** is not supported
        
        Netifaces
        ^^^^^^^^^
        
        It is surprisingly difficult to make a good guess of the IP address of a user's
        primary network interface across a range of operating systems. The code uses
        ``socket.gethostbyname`` by default, which does a reasonable job but is
        completely borked if you have VMware installed.
        
        If available it will use the `netifaces`_ module which generally does a better
        job. It is recommended that you install this by running::
        
          easy_install netifaces
        
        mod_pywebsocket
        ^^^^^^^^^^^^^^^
        
        This will be installed along with mplh5canvas if you follow the instructions below.
        However you can install it yourself::
        
            easy_install mod_pywebsocket
        
        The `PyPI`_ page may be out of data as we maintain this ourselves. The master
        repository for mod_pywebsocket is `pywebsocket`_.
        
        Installation
        ------------
        
        Since this package is available on `PyPI`_ the simplest way to install it is to do::
        
          easy_install mplh5canvas
        
        Alternatively, download the latest tarball or check out the source code from
        Google Code and do::
        
          python setup.py install
        
        It is assumed that you have the proper permissions to install Python packages on
        your system (if not, you can make use of `virtualenv`_ instead).
        
        Testing
        -------
        
        We provide a number of example scripts for initial testing. Surprisingly these
        are found in the ``examples`` directory of the source code.
        
        The script names are self-explanatory. The URL of the management server should be
        printed out by the script, and if a web browser is installed and available a new
        tab should be opened in your browser. If not, then just copy and paste the
        management URL into a browser window.
        
        Conformance Testing
        ^^^^^^^^^^^^^^^^^^^
        
        To try and reach a level of reasonable conformance we have a crude test suite
        that will run against a directory of matplotlib examples and produce a web page
        for side-by-side comparison::
        
          cd tests
          python test.py -d <matplotlib source tree>/lib/mpl_examples/pylab_examples
        
        This produces output files in the ``tests/output`` directory. The file ``test.html``
        when viewed in a web browser will show the mplh5canvas implementation alongside a
        PNG and SVG for each file in the target directory. 
        
        Be aware that these test results can be pretty massive and may well lead to
        browser instability. You can run on a restricted set of tests by using a wildcard
        parameter (see ``test.py --help``).
        
        There is also the option of rendering each canvas on the page to a PNG for easier
        side-by-side comparison. To do this, run::
        
          python rec.py
        
        once you have a completed test run. At the bottom of the test.html page click
        the "Connect" button. Then click the "Put Images to Server" button.
        The ``rec.py`` instance should indicate a variety of files being written to disk.
        Then open the ``test_rendered.html`` page which will have a side-by-side column
        of PNGs.
        
        .. _pywebsocket: http://code.google.com/p/pywebsocket/
        .. _Matplotlib: http://matplotlib.sourceforge.net/
        .. _block it by default: http://hacks.mozilla.org/2010/12/websockets-disabled-in-firefox-4/
        .. _netifaces: http://alastairs-place.net/netifaces/
        .. _PyPI: http://pypi.python.org/pypi/mplh5canvas
        .. _virtualenv: http://pypi.python.org/pypi/virtualenv
        
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Topic :: Software Development :: Libraries :: Python Modules
