From 84d914b0a015ef6c588253ac7f70382bfa9030e5 Mon Sep 17 00:00:00 2001 From: rcoh Date: Tue, 15 Feb 2011 15:15:43 -0500 Subject: Added documentation to repo in docs folder. --- docs/Behaviors/Behaviors.tex | 143 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/Behaviors/Behaviors.tex (limited to 'docs/Behaviors/Behaviors.tex') diff --git a/docs/Behaviors/Behaviors.tex b/docs/Behaviors/Behaviors.tex new file mode 100644 index 0000000..9021581 --- /dev/null +++ b/docs/Behaviors/Behaviors.tex @@ -0,0 +1,143 @@ +\documentclass{article} +\usepackage{fullpage} +\begin{document} + \title{Behaviors: An Introduction and Exercises} + \author{Russell Cohen} + \date{\today} + \maketitle + \section{What is a behavior?} + At its most basic, a behavior is machine with two input terminals and two + output terminals. One of these input terminals is external input. The + other is feedback from the behavior. Similarly, the behavior has two output + terminals. One gets released externally as output, and the other gets fed + back to the behavior. At their core, behaviors have nothing to do with + pixels are light effects -- this is merely how we commonly use them. + \section{How do I write a behavior?} + At the core of a behavior is its \texttt{ProcessResponse} method which + tells a behavior what to get on input. As you might expect, it has 2 + input ports, and two output ports. The `type' of inputs and outputs can be + anything -- numbers, strings, lists, however, in our system, the inputs + and outputs are all python dictionaries. This allows us to have an + arbitrary number of named parameters. As sample input might look + something like \texttt{{'Location':(20,20), 'Height':10}}. When we + return a value, we return a tuple of (list,list). Note that on a + process response method you will actually be given a \textbf{List of + dictionaries} and you should iterate over them. + \textbf{Important:} You should not directly modify the inputs! Use + \texttt{dict(input)} to create a copy of them! + \section{Exercise 1: addFive} + Our goal: Create a behavior that will add 5 to the 'Value' field of the + input. If no 'Value' field exists, we will set it to five. Below is a + sample \verb processResponse method to do this. Note that process + response is the only part of a behavior that must be written (everything + else happens behind the scenes when you \textbf{inherit} from the + \texttt{Behavior} class. + \begin{verbatim} + def processResponse(self, inputs, recurrences): + output = [] #empty list + for inp in inputs: + inpCopy = dict(inp) + if not ('Value' in inpCopy): + inpCopy['Value'] = 0 + inpCopy['Value'] += 5 + output.append(inpCopy) + return (output, []) #empty list, no recurrences + \end{verbatim} + \section{Exercise 2: A Sum-er} + Create a behavior that outputs the sum of all previous input. Hint: + You will need to use recurrences! + \section{Declaring and Configuring Behaviors} + Once you've written your behavior (or are using an already written + behavior, you will need to tell the light installation to use the + behavior. This is done via XML in the configuration file. When you + run the system, you specify a configuration file eg: + \texttt{python LightInstallation.py config/ConfigFile.xml} + + Behaviors are specified in the \verb BehaviorConfiguration section. + A sample behavior follows: + \begin{verbatim} + + behaviors.EchoBehavior + + echo + False + + + \end{verbatim} + + The ``Class'' attribute specifies the \textbf{Python} class for this + behavior. (The \verb behaviors. prefix tells Python to look in the + behaviors folder). You may recall that all classes SmootLight take a + single python dictionary as an argument -- this is embodied by the + \texttt{Args} tag. A dictionary is created from the XML at runtime + -- this dictionary would be: \texttt{{'Id':'echo', + 'RenderToScreen':False}} + The id we specify is the id that we can reference this behavior by + later. The \verb RenderToScreen attribute specifies whether or not + outputs from this behavior should be directed to the screen (some + behaviors act only as the building blocks for other + behaviors, and are never rendered directly to the screen) + + \section{Behavior Chains} + I have mentioned several times that the system allows for behaviors to + be chained together to create many different effects -- often the + ``motion'' effect and the ``coloring'' effects are two separate + behaviors. The result you see on the screen are these two pieces + connected together. This allows us to build up many different behaviors + from a library of simple pieces. Let's look at how we actually + accomplish this. + + Behavior Chaining is accomplished through the behavior chain class. + Here is an example of a behavior we declare (in XML) via a behavior + chain: + \begin{verbatim} + + behaviors.BehaviorChain + + runcolordecay + + pygame + randomLoc + + + colorchange + running + decay + + {'running':'acceleratedie'} + True + gaussmap + + + \end{verbatim} + + Note the importance of the `Id' field -- that is how we reference all + other components of the system. Let's walk through what is going on + here. We declare this behavior just like any other -- however, for + class, we specify \verb BehaviorChain . The \verb Inputs tag specifies + which inputs will be routed to this behavior. In this case, it is + \verb pygame and \verb randomLoc , two previously declared behaviors. + Inputs from these behaviors will be passed to the behavior chain via + sensorInputs. Next, we have the meet of this chain, the behaviors it is + composed of. This states that first, an input is routed through + \texttt{colorchange}. \verb colorchange adds a color field to the + sensor data. Next, the input is routed to \verb running a behavior + that makes pixels run back and forth. Finally, the input is routed to + \verb decay , a behavior that adds a decay ``PixelEvent'' that makes + individual pixels turn on and then decay. + + The next item we see is \verb RecursiveHooks . This is a special + feature of the \verb BehaviorChain that allows us to augment the + reccurences recursive events have. We specify that we will augment the + recursive behavior of \verb running with another behavior, + \verb acceleratedie which modifies increases the speed of the running + behavior, and stops the behavior after a certain number of iterations. + Note that recursive hooks take data in via their \textbf{external input} + port, and \textbf{not} their recursive port. + + Finally, we state that this behavior will indeed be rendered directly to + the screen. We also specify which PixelMapper we want to use. + + Phew. This isn't as complicated as it sounds. I promise. + + \end{document} -- cgit v1.2.3 From f34e1c732036553e4a68534dfc1b24a13ccd33ce Mon Sep 17 00:00:00 2001 From: rcoh Date: Tue, 15 Feb 2011 16:25:37 -0500 Subject: Adding images to the Behaviors Docs --- docs/Behaviors/Behavior.jpg | Bin 0 -> 21577 bytes docs/Behaviors/Behaviors.pdf | Bin 98731 -> 148809 bytes docs/Behaviors/Behaviors.tex | 24 ++++++++++++++++++------ docs/Behaviors/BehaviorwithRecursiveHook.jpg | Bin 0 -> 27186 bytes 4 files changed, 18 insertions(+), 6 deletions(-) create mode 100644 docs/Behaviors/Behavior.jpg create mode 100644 docs/Behaviors/BehaviorwithRecursiveHook.jpg (limited to 'docs/Behaviors/Behaviors.tex') diff --git a/docs/Behaviors/Behavior.jpg b/docs/Behaviors/Behavior.jpg new file mode 100644 index 0000000..c96ee84 Binary files /dev/null and b/docs/Behaviors/Behavior.jpg differ diff --git a/docs/Behaviors/Behaviors.pdf b/docs/Behaviors/Behaviors.pdf index 14eafa6..32c5b75 100644 Binary files a/docs/Behaviors/Behaviors.pdf and b/docs/Behaviors/Behaviors.pdf differ diff --git a/docs/Behaviors/Behaviors.tex b/docs/Behaviors/Behaviors.tex index 9021581..5105588 100644 --- a/docs/Behaviors/Behaviors.tex +++ b/docs/Behaviors/Behaviors.tex @@ -1,5 +1,6 @@ \documentclass{article} \usepackage{fullpage} +\usepackage{graphicx} \begin{document} \title{Behaviors: An Introduction and Exercises} \author{Russell Cohen} @@ -12,6 +13,9 @@ terminals. One gets released externally as output, and the other gets fed back to the behavior. At their core, behaviors have nothing to do with pixels are light effects -- this is merely how we commonly use them. + \begin{center} + \includegraphics[width=4 in]{Behavior.jpg} + \end{center} \section{How do I write a behavior?} At the core of a behavior is its \texttt{ProcessResponse} method which tells a behavior what to get on input. As you might expect, it has 2 @@ -20,7 +24,7 @@ and outputs are all python dictionaries. This allows us to have an arbitrary number of named parameters. As sample input might look something like \texttt{{'Location':(20,20), 'Height':10}}. When we - return a value, we return a tuple of (list,list). Note that on a + return a value, we return a tuple of \texttt{(list,list)}. Note that on a process response method you will actually be given a \textbf{List of dictionaries} and you should iterate over them. \textbf{Important:} You should not directly modify the inputs! Use @@ -86,7 +90,7 @@ connected together. This allows us to build up many different behaviors from a library of simple pieces. Let's look at how we actually accomplish this. - + Behavior Chaining is accomplished through the behavior chain class. Here is an example of a behavior we declare (in XML) via a behavior chain: @@ -134,10 +138,18 @@ behavior, and stops the behavior after a certain number of iterations. Note that recursive hooks take data in via their \textbf{external input} port, and \textbf{not} their recursive port. - + \begin{center} + \includegraphics[width=4 in]{BehaviorwithRecursiveHook.jpg} + \end{center} Finally, we state that this behavior will indeed be rendered directly to - the screen. We also specify which PixelMapper we want to use. - + the screen, by specifying: + \begin{center}\texttt{True} \end{center} + We also specify which PixelMapper we want to use (gaussmap): + \texttt{gaussmap}. \verb gaussmap is the id we assigned to the mapper when + we declared in the \verb PixelMappers section of the xml. + \begin{center} Phew. This isn't as complicated as it sounds. I promise. - + \end{center} + Browse around the behaviors to get an idea of what is possible and what has been done. They + all live in the behaviors folder. Enjoy! \end{document} diff --git a/docs/Behaviors/BehaviorwithRecursiveHook.jpg b/docs/Behaviors/BehaviorwithRecursiveHook.jpg new file mode 100644 index 0000000..84e99d6 Binary files /dev/null and b/docs/Behaviors/BehaviorwithRecursiveHook.jpg differ -- cgit v1.2.3