SharpCap Scripting

SharpCap now has a scripting language built in that allows simple programs to be written that can perform just about any action that you can perform when controlling SharpCap with the keyboard and mouse.

The built in scripting language is a variety of Python, called IronPython that integrates well with the C# programming language used to write SharpCap. You can find out more about Python here and IronPython here. If you are already a programmer, then Python shouldn’t take much getting used to, although the fact that indentation is significant may be a shock to those used to using ‘{‘ and ‘}’ to mark blocks of code!

You can launch an interactive Python console from the scripting menu, or run a .py script from file. You can also choose scripts that SharpCap should run at startup in the settings dialog. It’s probably best to get started using the interactive console.

The SharpCap Python Console

The Python console in SharpCap is based on the Console component of IronLab, it provides a good amount of automatic ‘intellisense’ suggestions as you are typing code, which really helps as you are getting ot grips with the system. Unfortunately it can’t make suggestions in some cases, so you may have to read the documentation! The code to the console component has been modified to work better inside SharpCap – the modified source can be found on github.

The console window shows two text entry areas – at the top you can enter commands one line at a time and they will be executed when you press enter. At the bottom you can type (or paste) a multi-line script and run it with the green ‘play’ button. In either case a script in progress can be aborted with the ‘stop’ button.

Controlling SharpCap is handled using the SharpCap object which is automatically loaded into each script session. Some simple commands would be…

SharpCap.SelectedCamera = None # Close the camera that is currently active

SharpCap.SelectedCamera = SharpCap.Cameras[0]  # Open the first camera in the Cameras menu and start previewing it
Once a camera is running, you can adjust its properties like this

SharpCap.SelectedCamera.Controls.Exposure.Value = 1000   # Set the exposure to 1000ms (1s)

SharpCap Scripting Object Model

The major objects available to control the application are

SharpCap    The main application object, all other objects are accessed via this object.
SharpCap.Cameras  A collection of available cameras (as shown in the Cameras menu)
SharpCap.SelectedCamera    The camera that is currently open (or ‘None’ if no camera open)
SharpCap.SelectedCamera.Controls  The controls available on the currently open camera. Many common controls can be access directly, but others will need you to check each item in the array to find the control you need.
SharpCap.Focusers     A collection of (ASCOM) focusers detected by SharpCap. You can use SharpCap.Focusers.SelectedFocuser to connect to a specific focuser and then access it via the SelectedCamera.Controls collection.
SharpCap.Mounts, SharpCap.Wheels  Collections of ASCOM mounts and filter wheels, work in the same way as Focusers.
SharpCap.Transforms  A collection of frame transforms that can be applied to the preview window by setting the SharpCap.Transforms.SelectedTransform property (buggy at the moment)
 SharpCap.MainWindow     The main application window of SharpCap. Take care changing properties or calling methods on this as you may break things!
 SharpCap.Reticules   Collection of reticule overlays that may be selected for drawing on the screen (like the transforms, also currently buggy)
 SharpCap.Settings     All application settings, alter with care and call ‘Save()’ after any changes to make them take effect

In general, the most used objects will be SharpCap.SelectCamera and SharpCap.SelectCamera.Controls.

The Camera Object

The most important methods and properties on the SelectedCamera object are (informational properties will work on other non-selected cameras)

 CanCapture, CanStillCapture  Indicate whether the camera can capture video and still frames, respsectively
 CanPause  Can the camera pause a video capture without stopping it?
 CaptureConfig  Settings controlling the type of capture to be performed, including frame limit, etc
 PrepareToCapture()  Must be called to set up a video capture before calling RunCapture()
 RunCapture()  Begins a prepared video capture. The capture will run until any limit is reached or StopCapture() is called. The output file(s) will be named according to the selected naming scheme.
 CancelCapture()     Cancel a capture that has been prepared (instead of running it using RunCapture).
 CaptureSingleFrame()  Capture a single frame snapshot (the output file will be named according to the selected naming scheme
 CaptureSingleFrameTo(string filePath)  Capture a single frame and save it to the specified output file name. The path will need to be a full path and the extension specified should match that selected in SharpCap.SelectedCameras.Controls.OutputFormat.Value
 Name  The name of the camera used in the application UI
 VideoDeviceId  In internal identifier for the camera (may be empty or rather geeky)
 StartPreview(), StopPreview()  Start and Stop previewing frames on the camera respectively
 RestartPreview()  Stop then re-start previewing frames on the camera
 GetStatus(boolean allStats)  Returns an object describing the status of the camera including frames captured, average frame rate, etc.
 IsOpen, IsPreviewing, CanCountFrames, Capturing  Informational properties, as named
 CapturedFrameCount  The number of frames processed by the camera (including preview frames) since the last time preview was started or capture was started or stopped.
 ApplySelectedTransform()  Reserved, internal use only

The following controls may be available directly on the Controls object for the SelectedCamera:

Binning, ColourSpace, Exposure, FilterWheel, Focus, Gain, OutputFormat, Resolution

Other controls are likely to be available within the Controls collection and must be searched for by name, ie

cooler = SharpCap.SelectedCamera.Controls.Find(lambda x: x.Name == "Cooler")

Note that the available controls vary from camera to camera, and only ColourSpace, Exposure, Resolution and OutputFormat are always available.

The Control Object

The following properties are available on each Control:

 Available  True if the control is actually available to read or write values.
 ReadOnly  True if the control can only be read from (for instance a sensor temperature readout)
 AutoAvailable      True if the control can be set into Auto mode
 Auto  Switch the control between Auto and Manual mode
 Name  The name of the control as displayed in the UI
 Id  An enumeration of common property types, currently including:   Other, Exposure, FrameRate, Pan, Tilt, Resolution, ColourSpace, OutputFormat, Focus, FilterWheel, FrameFilter, Binning, Gain
 Minimum, Maximum  Retrieve the minimum and maximum values of numeric controls
 Step  Integer controls may have a step value defined – they can only be changed in multiples of this value. This is very rarely encountered.
 Value  The value of the control, which can be retrieved and (if not ReadOnly) changed.
 Type  The type of value that the control has.

 Integer  Numeric, whole number values
 Double  Numeric, whole or decimal values
 Boolean  On/Off value (checkbox)
 Command  A single action, launched by a button in the UI
 MultipleChoice  A list of options, shown as a drop down control in the UI
 Custom  Any other type of control.
 AvailableValues  In the case of a MultipleChoice control, a list of the choices available.

Scripting Samples

Periodic Capture and Timestamp Image

The code below will capture a single PNG image approximately every 15 second and then write a timestamp into the image itself before saving it. It would be simple to modify the code to save each timestamped image under a different filename or to remove the timestamping step.

The code relies on a camera already being selected and previewing and that the camera can output to PNG files (ie will not work if the camera is in a 12/16 bit mode).

import time
clr.AddReference("System.Drawing")
import System.DrawingSharpCap.SelectedCamera.Controls.OutputFormat.Value = 'PNG files (*.png)'
if (SharpCap.SelectedCamera.Controls.Exposure.AutoAvailable):
   SharpCap.SelectedCamera.Controls.Exposure.Automatic = Truewhile True:
   SharpCap.SelectedCamera.CaptureSingleFrameTo("d:\capture.png")
   time.sleep(1)
   bm = System.Drawing.Bitmap("d:\capture.png")
   g = System.Drawing.Graphics.FromImage(bm)
   f = System.Drawing.Font("Arial", 12)
   g.DrawString(System.DateTime.Now.ToString(), f, System.Drawing.Brushes.Red, System.Drawing.Point(0,0))
   g.Dispose()
   f.Dispose()
   bm.Save("d:\\timestamped.png")
   bm.Dispose()
# do more with png file here
   time.sleep(15)