Development

Introduction

The Pulsefield software includes the capability of adding new applications that make use of the people-tracking, multi-projector display and music/audio subsystems. This can be done by adding a new class to the Java Tracker application as described below. Apps can be run and tested in a simulation mode where the output is shown in a window and the mouse can be used to simulate movement of people in the space.

Note that Pulsefield development is currently done only under MacOS. Although the Java code is portable to other platforms, there are some native libraries (specifically Syphon) in the repository that are MacOS-specific.

Setup

To install and setup the software:

  1. Clone the pulsefield repository from github into a local folder, “pulsefield”, using: git clone https://github.com/btownshend/Pulsefield.git pulsefield
  2. Install Eclipse for Java if you don’t already have it ( http://www.eclipse.org/downloads/ ). Other IDEs or a plain editor can also be used, but the setup in the repository is for Eclipse. I’ve been using Eclipse Neon version 3 with java JDK 1.8.0_131. The JDK can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html
  3. Open Eclipse and use Import>General>Existing Projects into Workspace and import $PFROOT/modules/Tracker into the workspace.
  4. Set the environment variable, PFROOT, the root directory of the local copy (in this example, the full path to “pulsefield”). This can be done in Eclipse’s run configurations in the “Environment” tab.

Running apps

Once Tracker is launched, it will open 2 windows; one showing the display as it will be mapped to the ground, and another small GUI control window. The control window can be used to select which app is currently active. In the display window clicking and dragging will add a simulated person with ID #1. Typing a digit, 1-9, on the keyboard will switch to controlling another person with that ID#. Typing ‘c’ will clear all people.

Source Tree

The Pulsefield repository will setup the following src tree:

$PFROOT/                  - root of install
doc/                      - documentation
doc/AppDevelopment.md     - this document
doc/PROTOCOL.txt          - details of the OSC protocols used between subsystems

modules/                  - high-level modules for Pulsefield
modules/Tracker/          - Java-based software to generate Pulsefield apps
modules/FrontEnd/         - people-tracking system; sends OSC messages to Tracker and other subsystems (C++)
modules/Calibrator/       - module for calibration of Pulsefield (C++)
modules/Chuck/            - music-module to support the "chuck" app in Tracker
modules/GPUFluid/         - GPU-based code for Navier-Stokes simulation to support the "NavierOF" app in Tracker

lib/
lib/C++Util               - common code for some of the C++ subsystems

config/                   - configuration files
config/urlconfig.txt      - configuration of IP addresses and ports of subsystems
config/tracker-config.json - configuration of tracker

OSC/                      - software relation to Open Sound Control (OSC)
OSC/TouchOSC              - templates for iPad control of Pulsefield via TouchOSC

RUN/                      - setup for launching and running Pulsefield systems

Matlab/                   - Matlab utilities, primarily for monitoring performance of tracking 

For doing application development, only the modules/Tracker folder is relevant. Apps can be run and tested standalone without using any of the other subsystems. The only exception is if the app uses real-time control via TouchOSC, in which case the OSC/TouchOSC templates can be editted using TouchOSC Editor.

Adding a new app

Applications within Tracer are implemented as classes derived from Visualizer, typically named VisualizerXXX. There are numerous examples of different apps within the code, and an empty template called VisualizerTemplate that can be copied. A good place to start (or derive from) is VisualizerDot which draw dots on the ground that track each person. Each of these implements the following interface:

constructor - called once when the system is started up;  there
will only be a singleton of each app constructed by the system.

start() - called each time the app becomes active

stop() - called each time the app is deactivated

update() - update internal state based on passed-in location of
all the people currently in the pulsefield

draw() - called at the refresh frame rate (~20/second).  This is
where the app should update the display to be imaged onto the
ground by drawing into a canvas passed in.

Drawing is based on Processing drawing calls. A PGraphics instance is passed in and drawing can be done using any processing calls. There are also some utility functions within the Visualizer base class for drawing text, images, and shapes. In particular, drawing text using basic processing calls causes the text to be mirror-imaged as the default coordinate axes under Pulsefield are mapped to the ground (in units of meters) and flipped from normal drawing conventions to a video screen.

The location and other information about each person in the Pulsefield is passed into update() and draw() in a class called People. See the code for details of the available methods.

To register a new app with the system, a small piece of code needs to also be added to Tracker.java of the form: addVis(“XXX”,new VisualizerXXX(this),true); This is added where all the other addVis() calls are in that code.

Apps with sound

There are additional facilities for apps to access synthesizers or control Ableton. Most of the existing apps used one or the other and can be used as a template for adding to a new app. Let me know if this is of interest, and I will write more documentation.

Questions/Comments/Help

Feel free to contact me with any questions or comments at info@pulsefield.com or check on the Pulsefield website.

Leave a Reply

Your email address will not be published. Required fields are marked *