Scripting

Intermediate

Making protocols

So far we've just been using sample protocols that didn't do anything special, and we haven't explained what the different fields are. But to make full use of your chamber, you'll want to know exactly how these protocols work.

Declaring a new protocol

You've probably seen this a few times before:

var protocol = new CameraProtocol("example")

That's declaring a new protocol. Note that the name given in the constructor is not the same as actual variable name. In general that's bad practice, and remember that once the script is compiled, only the name provided in the constructor is remembered!.

In general, the name provided isn't really important. It's just to differentiate it from other protocols, and isn't generally used when analyzing data. Just remember that it has to be unique.

Setting the AnalysisID

While the name isn't important for analysis, the AnalysisID certantly is! This field tells analysis software what type of image was being recorded, and how it should go about processing it.

You set this field like this:

  protocol.setAnalysisID("f0fm")

Selecting cameras

You'll notice that in the protocols we used so far we never had to select a camera: that's because if the system only has one set of cameras it will automatically use them when you don't specify.

But what if you DON'T want it to use every camera? Or what if you have more than one set of cameras? Thats when you have to specify:

  // Use cameras '0' and '2' from group '0'
  protocol.setSensorGroup ("0")
  protocol.setSensors     ("0,2")

There are two functions there:

  • setSensorGroup()

    This line specifies which set of cameras you'll be using.

    Setting this to * (the default setting when not otherwise specified) attempts to select the only SensorGroup, when the system only has one. That won't work if you have more than one!

    Note that in this example, we're choosing the group with id "0". (It's a String, not a number!)

  • setSensors()

    This line specifies which cameras from that group it will use.

    Setting this to * (the default setting when not otherwise specified) selects all cameras from the SensorGroup.

    Note that in this example, we're chosing Sensors "0" and "2" (Also Strings! They don't have to correspond with numbers, that's just convention)

Number of loops

Okay, so that's the general stuff: now we have to tell it HOW to take the images. There are a whole bunch of settings here and most of them rely on this first setting.

  // The protocol will have 6 distinct stages, each with different behaviour.
  protocol.setNumberLoops(6)

Frames per loop

The next field determines how many times each of those behaviours is executed.

  // The first stage will execute 5 times, the second 2 times, and so on.
  protocol.setFramesPerLoop([5, 2, 5, 2, 5, 2])

Measuring light

Now we want to determine which stages use which measuring light during image capture. Measuring light is determined by an integer, with each number referring a different light.

  • 0 - no light
  • 1 - red light
  • 2+ - other lights (not installed as of yet)
  // Run red measuring light on second to first and second to last stages.
  protocol.setMeasuringLight([0, 1, 0, 0, 1, 0 ])

Saturation flash

The Saturation flash is one of the core features of the chamber: it releases a array of batteries into the main lights for a brief period of time in order to fully saturate plants- resulting in a glow consistant with their photosysthesis rates.

  // Run saturation flash on first 3 stages
  protocol.setSaturationFlash([1, 1, 1, 0, 0, 0])

Exposure

We have to tell the cameras how long to capture for, by setting Exposure.

  // Expose cameras for 35 μs.
  // Most cameras do not support different exposure settings in one protocol.
  protocol.setExposure("35us")

This field takes a TimeType. It's not recommended you set it higher than a few seconds though!

Frame interval

I don't even know what this one does. We usually just set it to like, 70us

  protocol.setFrameInterval("20ms")

The full protocol

The full protocol looks like this:

var protocol = new CameraProtocol("example")

  protocol.setAnalysisID("f0fm")

  // Use cameras '0' and '2' from group '0'
  protocol.setSensorGroup ("0")
  protocol.setSensors     ("0,2")

  // The protocol will have 6 distinct stages, each with different behaviour.
  protocol.setNumberLoops(6)

  // The first stage will execute 5 times, the second 2 times, and so on.
  protocol.setFramesPerLoop([5, 2, 5, 2, 5, 2])

  // Run red measuring light on second to first and second to last stages.
  protocol.setMeasuringLight([0, 1, 0, 0, 1, 0 ])

  // Run saturation flash on first 3 stages
  protocol.setSaturationFlash([1, 1, 1, 0, 0, 0])

  // Expose cameras for 35 μs.
  // Most cameras do not support different exposure settings in one protocol.
  protocol.setExposure("35us")

  protocol.setFrameInterval("20ms")

And now you should know how to modify it to your liking.

Going further

There are more fields you can set still, and more may be added as we develop new functionality. There may even be more than one type of protocol! Go to protocols for the full list.