diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Behaviors/Behavior.jpg | bin | 0 -> 21577 bytes | |||
-rw-r--r-- | docs/Behaviors/Behaviors.pdf | bin | 0 -> 148809 bytes | |||
-rw-r--r-- | docs/Behaviors/Behaviors.tex | 155 | ||||
-rw-r--r-- | docs/Behaviors/BehaviorwithRecursiveHook.jpg | bin | 0 -> 27186 bytes | |||
-rw-r--r-- | docs/ClassOverview.pdf | bin | 0 -> 132526 bytes | |||
-rw-r--r-- | docs/XmlConfiguration.pdf | bin | 0 -> 152157 bytes | |||
-rw-r--r-- | docs/XmlConfiguration.tex | 223 | ||||
-rw-r--r-- | docs/designDocs.pdf | bin | 129631 -> 0 bytes | |||
-rw-r--r-- | docs/gettingStarted.pdf | bin | 0 -> 95402 bytes | |||
-rw-r--r-- | docs/gettingStarted.tex | 37 | ||||
-rw-r--r-- | docs/tex/Behaviors.tex | 143 | ||||
-rw-r--r-- | docs/tex/ClassOverview.tex (renamed from docs/designDocs.tex) | 16 |
12 files changed, 563 insertions, 11 deletions
diff --git a/docs/Behaviors/Behavior.jpg b/docs/Behaviors/Behavior.jpg Binary files differnew file mode 100644 index 0000000..c96ee84 --- /dev/null +++ b/docs/Behaviors/Behavior.jpg diff --git a/docs/Behaviors/Behaviors.pdf b/docs/Behaviors/Behaviors.pdf Binary files differnew file mode 100644 index 0000000..32c5b75 --- /dev/null +++ b/docs/Behaviors/Behaviors.pdf diff --git a/docs/Behaviors/Behaviors.tex b/docs/Behaviors/Behaviors.tex new file mode 100644 index 0000000..5105588 --- /dev/null +++ b/docs/Behaviors/Behaviors.tex @@ -0,0 +1,155 @@ +\documentclass{article} +\usepackage{fullpage} +\usepackage{graphicx} +\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. + \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 + 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 \texttt{(list<dict>,list<dict>)}. 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} + <Behavior> + <Class>behaviors.EchoBehavior</Class> + <Args> + <Id>echo</Id> + <RenderToScreen>False</RenderToScreen> + </Args> + </Behavior> + \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} + <Behavior> + <Class>behaviors.BehaviorChain</Class> + <Args> + <Id>runcolordecay</Id> + <Inputs> + <Id>pygame</Id> + <Id>randomLoc</Id> + </Inputs> + <ChainedBehaviors> + <Id>colorchange</Id> + <Id>running</Id> + <Id>decay</Id> + </ChainedBehaviors> + <RecursiveHooks>{'running':'acceleratedie'}</RecursiveHooks> + <RenderToScreen>True</RenderToScreen> + <Mapper>gaussmap</Mapper> + </Args> + </Behavior> + \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. + \begin{center} + \includegraphics[width=4 in]{BehaviorwithRecursiveHook.jpg} + \end{center} + Finally, we state that this behavior will indeed be rendered directly to + the screen, by specifying: + \begin{center}\texttt{<RenderToScreen>True</RenderToScreen>} \end{center} + We also specify which PixelMapper we want to use (gaussmap): + \texttt{<Mapper>gaussmap</Map>}. \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 Binary files differnew file mode 100644 index 0000000..84e99d6 --- /dev/null +++ b/docs/Behaviors/BehaviorwithRecursiveHook.jpg diff --git a/docs/ClassOverview.pdf b/docs/ClassOverview.pdf Binary files differnew file mode 100644 index 0000000..530dfa6 --- /dev/null +++ b/docs/ClassOverview.pdf diff --git a/docs/XmlConfiguration.pdf b/docs/XmlConfiguration.pdf Binary files differnew file mode 100644 index 0000000..9136232 --- /dev/null +++ b/docs/XmlConfiguration.pdf diff --git a/docs/XmlConfiguration.tex b/docs/XmlConfiguration.tex new file mode 100644 index 0000000..6f45de2 --- /dev/null +++ b/docs/XmlConfiguration.tex @@ -0,0 +1,223 @@ +\documentclass{article} +\usepackage{fullpage} +\begin{document} + \title{XML in SmootLight: Configuration++} + \author{Russell Cohen} + \date{\today} + \maketitle + \section{Motivation} + Why use XML (or any non-code language for that matter) to configure code? 2 Reasons: + \begin{itemize} + \item We would like small changes (like changing the color, speed, or type of behavior) + to be as quick as possible, and require modifying only 1 piece of code. + \item We would like these changes to be able to be made \emph{programmatically} + \item (Not applicable to python, but important in languages like Java or C): We want to + be able to make changes \textbf{without} having to recompile the source. + \end{itemize} + As you will see, however, XML in SmootLight goes beyond simple configuration. XML in + SmootLight allows us to declare a LightSystem (an inherently non-declarative thing) in the + same way you might write a webpage in HTML. We will refer to the XML system here-on-in as + `SmootConf'. \textbf{The fastest way to get familiar with SmootConf is simply to look at + the XML files in the configuration file. However, if you want a more structured approach to + its feature and subtleties this document should do the job.} Without any further ado, lets start looking at + how this all works. + \section{Declaring a class in SmootConf} + The most common thing done is SmootConf is declaring a class -- Class declaration code will + get parsed by SmootLight at runtime and \emph{actually} \textbf{declare} your classes for + you, exactly how you describe them. Classes are declared under a broader + \texttt{Configuration} tag which we will describe later. Lets look at the declaration of + \texttt{PygameInput}, an input that takes data from a Pygame window. + \begin{verbatim} + <InputElement> + <Class>inputs.PygameInput</Class> + <Args> + <Id>pygameclick</Id> + <RefreshInterval>10</RefreshInterval> + <Clicks>True</Clicks> + </Args> + </InputElement> + \end{verbatim} + The first attribute we see is the \texttt{Class} attribute. This specifies what + fully-qualified Python class to this object should be an instance of. In this case, it is + an instance of PygameInput, which lives in the inputs module/folder. Next, we see the + \texttt{Args}. The Args are where \emph{every} piece of configuration (except the actual + Class) goes. Let me repeat that, becuase it is a common sticking point. If you place + something in the configuration outside of the \texttt{Args} tag, it will not be read. + Period. + + If you are familiar with the SmootLight system, you will know that many objects in + SmootLight behave like dictionaries -- you can use statements like + \texttt{Self['ParamName']} to access parameters. If you have ever wondered where this + mystery dictionary is filled from, look no further -- it is here in the Args tag. + + Lets dig into the contents of the Arg tag. First we see \texttt{Id}. All components in the + SmootLight system are \emph{not} explicitly required to have an Id + specified.\footnote{Components declared without Id's will get a randomly assigned Id at + declaration time} + However, if you want to be able to reference this class in other places in the XML (which + we will look into later), you will need to specify and Id. The other two parameters are + simply bits of configuration which will get passed to PygameInput when it gets instantiated. + + \section{The Structure of a SmootLight Configuration Document} + The individual class declarations are the `leaves' of a full configuration document that + gets interpreted by the parser. In order for the parser to know what to do with them, it + also needs the branches. The structure of these `branches' (tags) follow: + \begin{verbatim} + <LightInstallation> + <InstallationConfiguration> + <Defaults /> + </InstallationConfiguration> + <PixelConfiguration /> + <PixelMapperConfiguration /> + <RendererConfiguration /> + <InputConfiguration /> + <BehaviorConfiguration /> + </LightInstallation> + \end{verbatim} + Under each of the tags indicated, place the classes that you want to instantiate in that + category. Each category has a different child tag: + \begin{itemize} + \item PixelConfiguration: PixelStrip + \item PixelMapperConfiguration: PixelMapper + \item RendererConfiguration: Renderer + \item InputConfiguration: InputElement + \item BehaviorConfiguration: Behavior + \end{itemize} + Some further clarification on this: Recall in the previous section we inspected the + declaration of the Input element. The input configuration for that system might have looked + like: + \begin{verbatim} + <InputConfiguration> + <InputElement> + <Class>inputs.PygameInput</Class> + <Args> + <Id>pygameclick</Id> + <RefreshInterval>10</RefreshInterval> + <Clicks>True</Clicks> + </Args> + </InputElement> + </InputConfiguration> + \end{verbatim} + \texttt{InputElement}s live under the broader \texttt{InputConfiguration} tag. Thats all in + terms of basic configuration -- all other features are going to be specific to the + particular class you are declaring (and the class should specify those). However, the + system also offers a lot of features to give you more power and flexibility, as well as + minimizing repeated XML. + \section{XML Inheritance} + SmootConf allows you have XML objects inherit from this other. Think of this as an + X:Include crossed with OO style inheritance, if those are familiar concepts. The most basic + tag of inheritance in SmootConf is the \texttt{InheritsFrom} tag. Here is a quick example + of it in action: + \begin{verbatim} + <Renderer Scale="4"> + <InheritsFrom>renderers/Pygame.xml</InheritsFrom> + </Renderer> + \end{verbatim} + + And the contents of \texttt{renderers/Pygame.xml}: + \begin{verbatim} + <Renderer> + <Class>renderers.PygameRenderer</Class> + <Args> + <Id>pygamerender</Id> + <displaySize>(1300,50)</displaySize> + </Args> + </Renderer> + \end{verbatim} + + The \texttt{InheritsFrom} tag indicates to look in the XML File indicated, parse it, and + recursively merge its tags with the siblings of the \texttt{InheritsFrom} tag. From a high + level, the algorithm works as follows: + + \begin{itemize} + \item For every tag: + \item If the tag is in the inheriter, use that. Otherwise, use the inherited tag. + \item Recurse to children. + \end{itemize} + + SmootConf adds a bit of syntactic sugar that allows you override args in the args dict when + doing inheritance by simply specifying them as attributes of the parent. The example below + comes from a pixel layout config: + \begin{verbatim} + <PixelConfiguration> + <PixelStrip Id="strip1.1" originLocation="(0,0)" Reverse="True"> + <InheritsFrom>layouts/50PixelStrip.xml</InheritsFrom> + </PixelStrip> + <PixelStrip Id="strip1.2" originLocation="(200,0)"> + <InheritsFrom>layouts/50PixelStrip.xml</InheritsFrom> + </PixelStrip> + \end{verbatim} + + The contents of \texttt{layouts/50PixelStrip.xml} are: + \begin{verbatim} + <PixelStrip> + <Class>layouts.LineLayout</Class> + <Args> + <pixelToPixelSpacing>4</pixelToPixelSpacing> + <spacing>4</spacing> + <numPixels>50</numPixels> + </Args> + </PixelStrip> + \end{verbatim} + + A careful reading of the algorithm will reveal some behaviors which are not specified. What if there are + multiple instances of identical sibling tags? The answer is that this is not currently + supported. It may be supported in the future. + + If you want your tags to be added to an inherited config without trying to merge, put them + in an \texttt{APPEND} tag like so: + + \begin{verbatim} + <Behaviors> + <InheritsFrom>behaviors/StockBehaviors.xml</InheritsFrom> + <APPEND> + <Beavhior> + <InheritsFrom>behaviors/SomethingElse.xml</InerhitsFrom> + </Behavior> + <Behavior> + <Class>blah.blah</Class> + <Args> + </Args> + </Behavior> + </APPEND> + </Behaviors> + \end{verbatim} + \section{Variable Bindings} + SmootConf allows developers to reference other variables within the \texttt{<Args>} tag. These + references are dynamic, and are bound for the lifetime of the object and will updated as + their bound values update. Here is an example: + \begin{verbatim} + <Behavior> + <Class>behaviors.SomeClass</Class> + <Args> + <Id>dimming</Id> + <DecayCoefficient>${DecayTime}$*5</DecayCoefficient> + <DecayTime>10</DecayTime> + </Args> + </Behavior> + \end{verbatim} + In this (fake) example, we bind the DecayCoefficient to the value of DecayTime, which allows us to + set decay in a reasonable unit, decoupled from the coefficient required by the behavior + itself. + + Under the hood, this feature is done with lambda functions. When you query arguments on the + object, the lambda gets resolved (look at \texttt{operationscore/SmootCoreObject.py} for the + implementation of this). Because of this, we also have to ability to go 1 layer deeper. + + Let's say you wanted to operate on another dictionary -- say, the current behavior packet or + and args of another behavior. By surrounding your variable in quotes, querying its value + with product a lambda function, which, when given another dictionary, will resolve the + value. + \begin{verbatim} + <Behavior> + <Class>behaviors.SomeClass</Class> + <Args> + <Id>stayinbounds</Id> + <MaxX>100</MaxX> + <OutOfBounds>'${x}$' < ${MaxX}$</OutOfBounds> + </Args> + </Behavior> + \end{verbatim} + If you call \texttt{self['OutOfBounds']}, and pass it a dictionary with a value at key + \texttt{x}, it will return a boolean stating whether or not \texttt{x > MaxX}. +\end{document} diff --git a/docs/designDocs.pdf b/docs/designDocs.pdf Binary files differdeleted file mode 100644 index 78eb646..0000000 --- a/docs/designDocs.pdf +++ /dev/null diff --git a/docs/gettingStarted.pdf b/docs/gettingStarted.pdf Binary files differnew file mode 100644 index 0000000..4d295f7 --- /dev/null +++ b/docs/gettingStarted.pdf diff --git a/docs/gettingStarted.tex b/docs/gettingStarted.tex new file mode 100644 index 0000000..4d88ace --- /dev/null +++ b/docs/gettingStarted.tex @@ -0,0 +1,37 @@ +\documentclass{article} +\usepackage{fullpage} +\usepackage{hyperref} +\begin{document} + \title{150 Smoots Getting Started on Linux} + \author{Andrew Chen} + \date{\today} + \maketitle + \section{Repository Access} + \begin{itemize} + \item \textbf{Install} Git packages with \texttt{sudo apt-get install git-core git-gui git-doc}. Set up your basic git settings \href{http://help.github.com/git-email-settings/}{like so}. + \item \textbf{Sign up} for a GitHub account (\href{https://github.com/signup/free}{here}) then ask Russell to add your account as a collaborator to the rcoh/SmootLight code repository. + \item \textbf{Connect} to the SmootLight GitHub code repository. Generate SSH keys and upload the public one to GitHub by following the instructions \href{http://help.github.com/linux-key-setup/}{here}. + \item \textbf{Clone and branch} the code repository; use \href{http://help.github.com/git-cheat-sheets/}{this cheatsheet} for help as necessary. + \end{itemize} + \section{Testing on Pygame} + \begin{itemize} + \item \textbf{Install} Pygame with \texttt{sudo apt-get install python-pygame}. + \item \textbf{Setup} logging by running \texttt{./setup.sh}. + \item \textbf{Run} your LightInstallation code with \texttt{python LightInstallation.py}. + \end{itemize} + \section{Repository Check In} + \begin{itemize} + \item \textbf{Stage} files to be committed with \texttt{./ga}. + \item \textbf{Commit} your changes locally with \texttt{git commit}. + \item \textbf{Push} your changes to your branch with \texttt{git push origin yourbranchname}. + \item \textbf{Request a pull} to the source repository by following instructions \href{http://help.github.com/pull-requests/}{here}. + \item \textbf{Learn more} about working with remote repositories \href{http://help.github.com/remotes/}{here}. + \end{itemize} + \section{Latex Documentation} + \begin{itemize} + \item \textbf{Install} Latex packages to be consistent with current documentation style. I had to run \texttt{sudo apt-get install texlive-fonts-recommended texlive-latex-extra} to successfully convert Russell's .tex to pdf. + \item \textbf{Edit} the .tex files with any text editor. I use vim for quick edits and gedit with the Latex plugin for autocompletion and quick previews. Get the Latex plugin with \texttt{sudo apt-get install gedit-latex-plugin}. + \item \textbf{Publish to PDF} with \texttt{pdflatex yourfile.tex}. + \item \textbf{View PDF} with \texttt{evince yourfile.pdf}. + \end{itemize} +\end{document} diff --git a/docs/tex/Behaviors.tex b/docs/tex/Behaviors.tex new file mode 100644 index 0000000..9021581 --- /dev/null +++ b/docs/tex/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<dict>,list<dict>). 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} + <Behavior> + <Class>behaviors.EchoBehavior</Class> + <Args> + <Id>echo</Id> + <RenderToScreen>False</RenderToScreen> + </Args> + </Behavior> + \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} + <Behavior> + <Class>behaviors.BehaviorChain</Class> + <Args> + <Id>runcolordecay</Id> + <Inputs> + <Id>pygame</Id> + <Id>randomLoc</Id> + </Inputs> + <ChainedBehaviors> + <Id>colorchange</Id> + <Id>running</Id> + <Id>decay</Id> + </ChainedBehaviors> + <RecursiveHooks>{'running':'acceleratedie'}</RecursiveHooks> + <RenderToScreen>True</RenderToScreen> + <Mapper>gaussmap</Mapper> + </Args> + </Behavior> + \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} diff --git a/docs/designDocs.tex b/docs/tex/ClassOverview.tex index 8e62edc..00d55ec 100644 --- a/docs/designDocs.tex +++ b/docs/tex/ClassOverview.tex @@ -56,8 +56,7 @@ be named classname.params and look like a python dict (\texttt{\{'key':value, 'key2':value2\}} ) \end{itemize} - Note that at this point, the only class using this functionality - is the PixelEvent class.} + } {No required parameters in argDict} \classDoc{PixelAssembler}{SmootCoreObject}{LineLayout, ZigzagLayout}{ PixelAssembler is a class that defines the positions of lights. It @@ -103,17 +102,11 @@ \classDoc{Behavior}{SmootCoreObject}{EchoBehavior, DebugBehavior}{ Abstract class for a behavior. On every time step, the behavior is passed the inputs from all sensors it is bound to as well as any recursive inputs that it -spawned during the last time step. Inheriting classes MUST define -\texttt{processBehavior}. \texttt{processBehavior} should return a list of dictionaries which -define the properties of the light response. The must return a location -\texttt{PixelEvent} class. Soon be be deprecated:\textit{They must give a location and -color. They may define a function pointer which defines a custom mapping. -[More on this later. Bug Russell if you want to do it].} -Call \texttt{recursiveResponse} to queue a input on the next iteration with a dictionary -argument. This will be passed in via recursive inputs.} +spawned during the last time step. Inheriting classes MUST define \texttt{processResponse}. Look +at the Behaviors documentation for more details.} {\begin{itemize} \item \texttt{Inputs}: A list of input Ids specifying input to the - behavior. In the future, this may also contain behavior ids. + behavior. \end{itemize}} \classDoc{PixelEvent}{SmootCoreObject}{StepResponse}{ Abstract class defining the behavior of a light after it has been turned on. @@ -155,6 +148,7 @@ argument. This will be passed in via recursive inputs.} directly, unless you really know what you're doing. Well, actually you should never need to do that. never. Don't do it.}{Takes a \texttt{LayoutBuilder} as an argument.} + \end{itemize} \section{Best Practices} \subsection{Variable and function naming} I'm pretty bad about being consistent. However, in all future |