Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 197 lines (127 sloc) 8.891 kB
fb77487 @jdf Fix broken images.
authored
1 # Python Mode for Processing #
52ccb15 @google-feinberg markdown README
google-feinberg authored
2
013cfcb @jdf New build!
authored
3 Write real [Processing](http://processing.org/) sketches in Python.
91f4aa8 @jdf working on regression tests, and the beginnings of a fix for bug #1
authored
4
5838eaf @jdf Further work on examples and documentation.
authored
5 * Based on [Processing 2.0](http://processing.org/), and compatible with most [3rd party libraries](http://www.processing.org/reference/libraries/).
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
6 * Source compatible with [Python 2.7.3](http://python.org).
e593710 @google-feinberg Remove obsolete known issues reference.
google-feinberg authored
7
66fd78f @ralfbiedert Updated list of platforms Processing.py is known to run on.
ralfbiedert authored
8 Tested on Mac OS 10.8 & 10.9, Windows XP, 7 & 8, and Ubuntu 12.10.
91f4aa8 @jdf working on regression tests, and the beginnings of a fix for bug #1
authored
9
86f2aef @jdf Add cute Travis badge.
authored
10 [![Build Status](https://travis-ci.org/jdf/processing.py.svg?branch=master)](https://travis-ci.org/jdf/processing.py)
11
f26f5cb @jdf minor tweaks
authored
12 ## Quick Start ##
3a04d0e @google-feinberg apply benfry suggestions
google-feinberg authored
13
edd6a97 @federicobond Fix typo in README.markdown
federicobond authored
14 ### Processing Development Environment ###
bc8a4c0 @jdf Update project README.
authored
15
16 If you're looking to write Processing sketches in Python, your best bet is to use
17 Python Mode. The project is still in its early days, and documentation is lacking,
18 but there are many example sketches to get you started. In general, the Processing
19 reference works just fine for Python mode.
20
21 First, [download Processing](http://processing.org/download). Then, install
22 Python Mode:
23
fb77487 @jdf Fix broken images.
authored
24 <img src="http://py.processing.org/add_mode.png"/>
25 <img src="http://py.processing.org/install.png"/>
bc8a4c0 @jdf Update project README.
authored
26
d2faadc @jdf Nice first sketch copypaste for README.
authored
27 Then try your first sketch:
28
29 ```python
30 def setup():
31 size(600, 600)
e035bdb @jdf Fix first sketch copypaste for README.
authored
32 colorMode(HSB)
d2faadc @jdf Nice first sketch copypaste for README.
authored
33 noStroke()
34
35
36 def draw():
37 fill(0x11000000)
38 rect(0, 0, width, height)
39 fill(frameCount % 255, 255, 255)
40 ellipse(mouseX, mouseY, 20, 20)
41 ```
bc8a4c0 @jdf Update project README.
authored
42
77d8f49 @jdf More clarification of the README.
authored
43 ### Processing.py ###
44
45 For command-line hackers and people who need much greater flexibility in how
46 they construct and integrate their programs, there's processing.py.
351b493 @google-feinberg Update docs.
google-feinberg authored
47
013cfcb @jdf New build!
authored
48 - [Mac OS X (83M)](http://py.processing.org/processing.py-0202-macosx.tgz)
49 - [Windows x64 (74M)](http://py.processing.org/processing.py-0202-windows64.zip)
50 - [Windows x32 (72M)](http://py.processing.org/processing.py-0202-windows32.zip)
51 - [Linux x64 (68M)](http://py.processing.org/processing.py-0202-linux64.tgz)
52 - [Linux x32 (69M)](http://py.processing.org/processing.py-0202-linux32.tgz)
351b493 @google-feinberg Update docs.
google-feinberg authored
53
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
54 Then, paste this code into a file, e.g., `mysketch.py`.
6eb14d2 @ralfbiedert Updated the README.
ralfbiedert authored
55
56 def setup():
9fae696 @jdf Fix up many broken eamples.
authored
57 size(600, 400)
a7ab1a1 @jdf New upload URLs
authored
58
59 def draw():
6eb14d2 @ralfbiedert Updated the README.
ralfbiedert authored
60 ellipse(mouseX, mouseY, 10, 10)
61
013cfcb @jdf New build!
authored
62 Drag and drop your sketch onto one of these files, according to your platform:
96be640 @jdf removing folder
authored
63
a7ab1a1 @jdf New upload URLs
authored
64 <img src="http://py.processing.org/howtolaunch.jpg"/>
d5ea494 @jdf new demo stuff
authored
65
013cfcb @jdf New build!
authored
66 You can also run the sketch from the command line, either with the included launcher script:
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
67
5838eaf @jdf Further work on examples and documentation.
authored
68 $ ./processing-py.sh path/to/mysketch.py
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
69
5838eaf @jdf Further work on examples and documentation.
authored
70 or using your own Java runtime environment:
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
71
5838eaf @jdf Further work on examples and documentation.
authored
72 $ java -jar processing-py.jar path/to/mysketch.py
80a6857 @google-feinberg More explicit docs.
google-feinberg authored
73
6eb14d2 @ralfbiedert Updated the README.
ralfbiedert authored
74 ## Documentation ##
80a6857 @google-feinberg More explicit docs.
google-feinberg authored
75
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
76 To learn Processing.py check out these resources:
77
78 * Built-in [Processing 2.0 functions](http://processing.org/reference/) for rendering and interaction.
5838eaf @jdf Further work on examples and documentation.
authored
79 * The [Python 2.7 documentation](http://docs.python.org/2/index.html).
80 * And of course the [Java 7 API documentation](http://docs.oracle.com/javase/7/docs/api/).
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
81
9566792 @jdf Oh, Markdown. :(
authored
82 Processing.py comes with many [examples](https://github.com/jdf/processing.py/tree/master/examples.py), most of which are exactly like the
013cfcb @jdf New build!
authored
83 example sketches that come with Processing, but converted to Python.
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
84
9566792 @jdf Oh, Markdown. :(
authored
85 $ processing-py.sh examples.py/Basics/Math/noisefield.py
86 $ processing-py.sh examples.py/Library/OpenGL/SpaceJunk.py
87 $ processing-py.sh examples.py/3D/Typography/KineticType.py
3a48bf7 @jdf Typo.
authored
88 $ processing-py.sh examples.py/3D/Textures/TextureCube.py
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
89
5838eaf @jdf Further work on examples and documentation.
authored
90 ## Using Processing Libraries ##
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
91
013cfcb @jdf New build!
authored
92 Processing.py is implemented in Java, and is designed to be compatible with the existing ecosystem of [Processing libraries](http://processing.org/reference/libraries/).
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
93
013cfcb @jdf New build!
authored
94 * Put processing extension libraries in the `libraries` subdirectory of your processing.py installation. Processing.py will search every jar file and directory beneath that special directory, so you don't need to be too fussy about where things go. Just unzip Processing libraries right there.
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
95
013cfcb @jdf New build!
authored
96 * Import the library in one of the usual Python ways, as in these snippets:
80a6857 @google-feinberg More explicit docs.
google-feinberg authored
97
5838eaf @jdf Further work on examples and documentation.
authored
98 from peasy import PeasyCam
99 # or
100 import peasy.PeasyCam
101 # or
102 import peasy.PeasyCam as PeasyCam
80a6857 @google-feinberg More explicit docs.
google-feinberg authored
103
5838eaf @jdf Further work on examples and documentation.
authored
104 Unfortunately, `from foo import *` is not supported.
80a6857 @google-feinberg More explicit docs.
google-feinberg authored
105
013cfcb @jdf New build!
authored
106 * Then, in your `setup()` method:
80a6857 @google-feinberg More explicit docs.
google-feinberg authored
107
5838eaf @jdf Further work on examples and documentation.
authored
108 cam = PeasyCam(this, 200)
d5ea494 @jdf new demo stuff
authored
109
5838eaf @jdf Further work on examples and documentation.
authored
110 Many libraries need a reference to "the current PApplet", and that's what
013cfcb @jdf New build!
authored
111 `this` is for. Of course, there's no such thing as `this` in Python; it's just something that processing.py provides for you for compatibility with such libraries.
3a04d0e @google-feinberg apply benfry suggestions
google-feinberg authored
112
5838eaf @jdf Further work on examples and documentation.
authored
113 ## Included Libraries ##
3a04d0e @google-feinberg apply benfry suggestions
google-feinberg authored
114
5838eaf @jdf Further work on examples and documentation.
authored
115 Some Processing libraries may not work with processing.py right out of the box. In particular, any library that uses Java reflection to call specially-named functions in your sketch will not work. However, we're happy to modify processing.py to work with any of the official Processing libraries. Here are the libraries that have required special handling in processing.py, and are included in the processing.py download:
3a04d0e @google-feinberg apply benfry suggestions
google-feinberg authored
116
5838eaf @jdf Further work on examples and documentation.
authored
117 * [Fisica](http://www.ricardmarxer.com/fisica/), by [Ricard Marxer](http://www.ricardmarxer.com/). Included under the terms of the LGPLv3, and with the kind cooperation of Mr. Marxer. See [examples.py/Fisica](https://github.com/jdf/processing.py/tree/master/examples.py/Fisica) for examples.
a7ab1a1 @jdf New upload URLs
authored
118
5838eaf @jdf Further work on examples and documentation.
authored
119 If you find that some Processing library doesn't work as expected with processing.py, please let us know in the [bug tracker](http://github.com/jdf/processing.py/issues).
3a04d0e @google-feinberg apply benfry suggestions
google-feinberg authored
120
5838eaf @jdf Further work on examples and documentation.
authored
121 ## FAQ ##
96be640 @jdf removing folder
authored
122
013cfcb @jdf New build!
authored
123 * __How do I report bugs or request new features?__
124
125 Please report any issue in the [bug tracker](http://github.com/jdf/processing.py/issues).
126
127 * __How can I create a launcher for my sketch?__
a7ab1a1 @jdf New upload URLs
authored
128
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
129 Add these lines near the top of your script:
130
131 import launcher
132 launcher.create()
133
a7ab1a1 @jdf New upload URLs
authored
134 * __How should I load data?__
3a04d0e @google-feinberg apply benfry suggestions
google-feinberg authored
135
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
136 [Tentative] Along with the launcher, consider using `pwd()` for file paths. For a given argument it resolves the path for an object relative to the currently running script:
80a6857 @google-feinberg More explicit docs.
google-feinberg authored
137
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
138 data = load(pwd("data.txt"))
80a6857 @google-feinberg More explicit docs.
google-feinberg authored
139
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
140 In that case, processing.py will try to search `data.txt` always where your script resides.
3a04d0e @google-feinberg apply benfry suggestions
google-feinberg authored
141
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
142 * __How can I use Ani, or any other library that modifies fields?__
a7ab1a1 @jdf New upload URLs
authored
143
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
144 Some libraries such as [Ani](http://www.looksgood.de/libraries/Ani/) require you to specify a variable name for animation. Unfortunately they cannot access Python variables directly (and Java's built in classes are immutable).
a7ab1a1 @jdf New upload URLs
authored
145
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
146 To solve this problem we instead create a mutable `PrimitiveFloat` object. This object has a field `.value`, which you can use for these purposes.
52ccb15 @google-feinberg markdown README
google-feinberg authored
147
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
148 import jycessing.primitives.PrimitiveFloat as Float
149 x = Float(100.0)
150 Ani.to(x, 200, "value", 50); # "value" is the name of the Float's internal field
151
152 In case you need other primitive values, please [let us know](http://github.com/jdf/processing.py/issues)!
153
154 * __Why was this project created?__
155
013cfcb @jdf New build!
authored
156 I ([Jonathan](http://MrFeinberg.com/)) recently gave a talk about Processing to a group of rather bright 8th-graders,
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
157 as part of a computer-programming summer camp they were attending at my office.
158 Their curriculum up to that point had been in Python, which is an eminently
159 sensible choice, given the
160 [pedagogical roots](http://en.wikipedia.org/wiki/ABC_%28programming_language%29)
161 of the language.
162
163 The kids were really turned on by the demos--I showed them the
164 [white glove](http://whiteglovetracking.com/), and
165 [Golan Levin](http://flong.com/)'s
166 [New Year's cards](http://www.flong.com/storage/experience/newyear/newyear10/)--but
167 they were bogged down by Processing's C-like syntax, which really seems arcane
168 and unnecessarily complex when you're used to Python.
169
170 I shared my experience with Processing creators
171 [Ben Fry](http://benfry.com/) and [Casey Reas](http://reas.com/), and they
172 told me that, indeed, the original Processing was a fork of
173 ["Design By Numbers"](http://dbn.media.mit.edu/), with Python and Scheme
174 support hacked in. Support for a multi-lingual programming
175 environment was always part of the plan, so they were enthusiastic
176 about any new attempt at the problem.
177
178 I was able to hack up a proof of concept in a couple of hours, and have
179 managed to create something worth sharing in a couple of weeks. I was only
180 able to do it at all thanks to the brilliant and beautiful
181 [Jython](http://www.jython.org/) project.
182
183 At the time of Processing's first public release, August of 2001,
184 Jython was too young a project to be used in this way. But now, having done
185 absolutely no work to profile and optimize, I can get hundreds of frames
186 per second of 3D graphics on my linux box. So, kudos to the Processing
187 project, and kudos to Jython!
6eb14d2 @ralfbiedert Updated the README.
ralfbiedert authored
188
189
190 ## Credits ##
191
a7ab1a1 @jdf New upload URLs
authored
192 Written by [Jonathan Feinberg](http://mrfeinberg.com) &lt;[jdf@pobox.com](mailto:jdf@pobox.com)&gt;
193 Launcher & many improvements by [Ralf Biedert](http://xr.io) &lt;[rb@xr.io](mailto:rb@xr.io)&gt;
6eb14d2 @ralfbiedert Updated the README.
ralfbiedert authored
194
9fc890d @ralfbiedert Updated README.
ralfbiedert authored
195 Also, [YourKit, LLC](http://www.yourkit.com) was so kind to sponsor a license for their excellent [YourKit Java Profiler](http://www.yourkit.com/java/profiler/index.jsp). Thank you very much!
47be091 @google-feinberg new small example for home page
google-feinberg authored
196
Something went wrong with that request. Please try again.