5
This section is meant to help users on well-supported platforms and common
6
Python environments get started using Chaco as quickly as possible. If your
7
platform is not listed here, or your Python installation has some quirks, then
8
some of the following instructions might not work for you. If you encounter
9
any problems in the steps below, please refer to the :ref:`installation`
10
section for more detailed instructions.
15
There are several different ways to get Chaco:
17
* Install the Enthought Python Distribution.
18
Chaco and the rest of the Enthought Tool Suite are bundled with it. Go to
19
the main `Enthought Python Distribution (EPD)
20
<http://www.enthought.com/epd>`_ web site and download the appropriate
21
version for your platform. After running the installer, you will have a
22
working version of Chaco.
24
*Available platforms:*
27
* Mac OS X 10.4 and 10.5
28
* RedHat Enterprise Linux 3 (32-bit and 64-bit)
31
Enthought Python Distribution is free for academic and personal
32
use, and fee-based for commercial and government use.
34
* *(Windows, Mac)* Install from PyPI using easy_install (part of setuptools)
35
from the command line:
37
:command:`easy_install Chaco`
39
* *(Linux)* Install distribution-specific eggs from Enthought's repository.
40
See the `ETS wiki <https://svn.enthought.com/enthought/wiki/Install#UsingEnthoughtsEggRepo>`_
41
for instructions for installing pre-built binary eggs for your specific
42
distribution of Linux.
44
* *(Linux)* Install via the distribution's packaging mechanism. We provide
45
.debs for Debian and Ubuntu and .rpms for Redhat. (TODO)
47
* Download source as tarballs or from Subversion and build. See
48
the :ref:`installation` section.
50
Chaco requires Python version 2.5.
57
Depending on how you installed Chaco, you may or may not have the examples already.
59
If you installed Chaco as part of EPD, the location of the examples depends on
62
* On Windows, they are in the :file:`Examples\\` subdirectory of your installation
63
location. This is typically :file:`C:\\Python25\\Examples`.
65
* On Linux, they are in the :file:`Examples/` subdirectory of your installation
68
* On Mac OS X, they are in the :file:`/Applications/<EPD Version>/Examples/`
71
If you downloaded and installed Chaco from source (via the PyPI tar.gz file, or
72
from an SVN checkout), the examples are located in the :file:`examples/` subdirectory
73
inside the root of the Chaco source tree, next to :file:`docs/` and the :file:`enthought/`
76
If you installed Chaco as a binary egg from PyPI for your platform, or if you
77
happen to be on a machine with Chaco installed, but you don't know the exact
78
installation mechanism, then you will need to download the examples separately
81
* ETS 3.0 or Chaco 3.0:
83
:command:`svn co https://svn.enthought.com/svn/enthought/Chaco/tags/3.0.0/examples`
85
* ETS 2.8 or Chaco 2.0.x:
87
:command:`svn co https://svn.enthought.com/svn/enthought/Chaco/tags/enthought.chaco2_2.0.5/examples`
90
(TODO): Add links to examples tarball.
92
Almost all of the Chaco examples are stand-alone files that can be run
93
individually, from any location.
95
All of the following instructions that involve the command line assume that
96
you are in the same directory as the examples.
101
Run the ``simple_line`` example:
103
:command:`python simple_line.py`
105
This opens a plot of several Bessel functions and a legend.
107
.. image:: images/simple_line.png
109
You can interact with the plot in several ways:
111
* To pan the plot, hold down the left mouse button inside the plot area
112
(but not on the legend) and drag the mouse.
116
* Mouse wheel: scroll up to zoom in, and scroll down to zoom out.
118
* Zoom box: Press "z", and then draw a box region to zoom in on. (There
119
is no box-based zoom out.) Press Ctrl-Left and Ctrl-Right to go
120
back and forward in your zoom box history.
122
* Drag: hold down the right mouse button and drag the mouse up
123
or down. Up zooms in, and down zooms out.
125
* For any of the above, press Escape to resets the zoom to the
128
* To move the legend, hold down the right mouse button inside the
129
legend and drag it around. Note that you can move the legend
130
outside of the plot area.
132
* To exit the plot, click the "close window" button on the window frame
133
(Windows, Linux) or choose the Quit option on the Python menu (on
134
Mac). Alternatively, can you press Ctrl-C in the terminal.
136
You can run most of the examples in the top-level :file:`examples`
137
directory, the :file:`examples/basic/` directory, and the :file:`examples/shell/`
138
directory. The :file:`examples/advanced/` directory has some examples that
139
may or may not work on your system:
141
* :file:`spectrum.py` requires that you have PyAudio installed and a working
144
* :file:`data_cube.py` needs to download about 7.3mb of data from the Internet
145
the first time it is executed, so you must have a working
146
Internet connection. Once the data is downloaded, you can save it so you
147
can run the example offline in the future.
149
For detailed information about each built-in example, see the :ref:`examples`
155
While all of the Chaco examples can be launched from the command line using the
156
standard Python interpreter, if you have IPython installed, you can poke around
157
them in a more interactive fashion.
159
Chaco provides a subpackage, currently named the "Chaco Shell", for doing
160
command-line plotting like Matlab or Matplotlib. The examples in the
161
:file:`examples/shell/` directory use this subpackage, and they are particularly
162
amenable to exploration with IPython.
164
The first example we'll look at is the :file:`lines.py` example. First, we'll
165
run it using the standard Python interpreter:
167
:command:`python lines.py`
169
This shows two overlapping line plots.
171
.. image:: images/lines.png
173
You can interact with the plot in the following ways:
175
* To pan the plot, hold down the left mouse button inside the plot area
176
and dragging the mouse.
180
* Mouse wheel: scroll up zooms in, and scroll down zooms out.
182
* Zoom box: hold down the right mouse button, and then draw a box region
183
to zoom in on. (There is no box-based zoom out.) Press Ctrl-Left and
184
Ctrl-Right to go back and forward in your zoom box history.
186
* For either of the above, press Escape to reset the zoom to the
189
Now exit the plot, and start IPython with the -wthread option:
191
:command:`ipython -wthread`
193
This tells IPython to start a wxPython mainloop in a background thread. Now
194
run the previous example again::
198
This displays the plot window, but gives you another
199
IPython prompt. You can now use various commands from the :mod:`chaco.shell`
200
package to interact with the plot.
202
* Import the shell commands::
204
In [2]: from enthought.chaco.shell import *
206
* Set the X-axis title::
208
In [3]: xtitle("X data")
210
* Toggle the legend::
214
After running these commands, your plot looks like this:
216
.. image:: images/lines_final.png
218
The :func:`chaco_commands` function display a list of commands with brief
221
You can explore the Chaco object hierarchy, as well. The :mod:`chaco.shell`
222
commands are just convenience functions that wrap a rich object hierarchy
223
that comprise the actual plot. See the :ref:`tutorial_ipython` section
224
for information on more complex and interesting things you can do with Chaco
228
Start Menu (MS Windows)
229
-----------------------
231
If you installed the Enthought Python Distribution (EPD), you have
232
shortcuts installed in your Start Menu for many of the Chaco examples. You can
233
run them by just clicking the shortcut. (This just invokes python.exe on the
234
example file itself.)
246
Once you have Chaco installed, you can either visit the :ref:`tutorials`
247
to learn how to use the package, or you can run the examples (see the
248
:ref:`examples` section).
254
There have been several presentations on Chaco at previous PyCon and
255
SciPy conferences. Slides and demos from these are described below.
257
Currently, the examples and the scipy 2006 tutorial are the best ways
258
to get going quickly. (See http://code.enthought.com/projects/files/chaco_scipy06/chaco_talk.html)
260
Some tutorial examples were recently added into the examples/tutorials/scipy2008/
261
directory on the trunk. These examples are numbered and introduce
262
concepts one at a time, going from a simple line plot to building a
263
custom overlay with its own trait editor and reusing an existing tool
264
from the built-in set of tools. You can browse them on our SVN server
266
https://svn.enthought.com/enthought/browser/Chaco/trunk/examples/tutorials/scipy2008
273
The API docs for Chaco 3.0 (in ETS 3.0) are at:
274
http://code.enthought.com/projects/files/ETS3_API/enthought.chaco.html
276
The API docs for Chaco2 (in ETS 2.7.1) are at:
277
http://code.enthought.com/projects/files/ets_api/enthought.chaco2.html
added
removed
docs/source/quickstart.rst
