Contributing to GumTree (Version 1.1) Presenter: Tony Lam (Gumnix Lab)
Jan 02, 2016
Tutorial Prerequisite
• GumTree Development Environment should be correctly setup on your machine Check out the latest “GumTree Platform” and “GumTree
Common Library” from Sourceforge Run Gumzilla demo instrument to check your GumTree
installation Have the tutorial note & source ready in your Eclipse workspace
• Basic J2SE 5.0 Programming Skill
• Some ideas on using Java Development Tool (JDT) and under Eclipse
Tutorial Outcomes
• What can you expect:1. Be able to write simple plug-in for GumTree and
Eclipse
2. Understand the design philosophy of GumTree
3. Contribute to GumTree by using the GumTree Platform API
• An instrument plug-in (Gumnut) for you to take home
Tutorial Outline
Basic GumTree Concept
• Say “Hello World” to GumTree
• Data Handling
• Experiment Modelling
• Data Acquisition
• Instrument Adaptation
What is GumTree?
• Official GUI for NBIP instruments
• A highly Integrated Scientific Experiment Environment ISEE!!
• An Eclipse based Rich Client Platform (RCP) application
• An open source GUI framework for collaboration
• ANSTO’s secret software weapon for total world domination (just kidding)
• http://gumtree.sourceforge.net
GumTree Architecture
core
cs
device
experiment
Java 5 VM
Instrument Control System Bridge
Instrument Specific Component
Data Acquisition
(DAQ)
Data Reduction and Analysis
(DRA)
Workbench Modelling
Instrument Specific
Leveraged Technology
GumTree Platform
Instrument Plugin
ui vis data
RCPEclipse
EcosystemOpen Source Technology
PlatformInfrastructure
common
Contributing to GumTree• What can be extended in
GumTree? Control System adaptation Visualisation Rendering Engine Data Format Support… and more
• When? Integrating new features to existing
instrument Writing new instrument front end
• Where? In a new GumTree plug-in
• How? Using Eclipse IDE and GumTree
Framework API
Eclipse RCP Runtime
Data
CS
DeviceACC
DRAVIS
UI
GumTree Platform
GumTree Project
Core
Your Plug-ins
Games
Clock
Other Eclipse Plug-ins
Their Plug-ins
HIPD
HRPD
TAS
SANS
REFL
REST
MRPD
GumNIX
Multimedia
Accessaries
Simulation Device
Environment Control Device
(Ancillary)
SDK Testing Framework
Data Analysis Algorithm
Instrument Operation Procedure
Contribution Rules
• Everything is a contributionAdd, do not modify
• Contribution code is only loaded when it is needed.Lazy loading mechanism
• Separate core functionality from UI functionality.
• Keep non-API codes to internal packagesDo not risk your plug-in
Eclipse Plugin Architecture• Plug-in – set of contributions
Example: Instrument specific data reduction & analysis (DRA) module
• Extension point - named entity for collecting contributions Example: Data format support
• Extension - a contribution Example: customised data format reader
Eclipse Plugin Architecture
• Plug-in details spelled out in the plug-in manifest Manifest declares
contributions Code implements
contributions and provides API
plugin.xml file in root of plug-in subdirectory
Tutorial Outline
Basic GumTree ConceptSay “Hello World” to GumTree
• Data Handling
• Experiment Modelling
• Data Acquisition
• Instrument Adaptation
Tutorial 1.1
• Learning ObjectivesWriting plug-in and simple Eclipse UI extension for
GumTreeFirst touch with the GumTree Visualisation API
• Performance IndicatorsA new plug-in with view to be displayed in the
GumTree WorkbenchGroup view into a view categoryDisplay “Hello World” in 1D GraphTwo buttons to control display on/off
Tutorial 1.2
• Learning ObjectivesGrouping UI contribution to a single screenUsing existing GumTree UI component
• Performance IndicatorsA perspective with Hello World view and
GumTree device navigator
Tutorial Outline
Basic GumTree ConceptSay “Hello World” to GumTreeExperiment Modelling
• Data Acquisition
• Data Handling
• Instrument Adaptation
Experiment Framework
• Experiments are modelled as objects users can operate GumTree in their familiar
scientific domainEssential elements are modelled as
experiment components eg, user metadata, instrument operations
• GumTree manages experiment lifecycleOnly one experiment to be activated at a time
Experiment LifecycleLogin
Hardware Setup (Expert Only)
Experiment Setup
Scan(Single Run)
Batch Run(Automated Data Collection /
Scheduled Scan)
Visualise / Process / Analyse Result
Export Data
Typical lifecycle
Modelling Gumnut Experiment
• For this tutorial, we will create a simple experiment which is capable of:Storing user metadata (name, address and email)
Performing a simple scan without driving any device
Collecting 2 monitor counts for each scan point
Importing and exporting experiment data with customised HDF5 reader and writer
Tutorial 2.1
• Learning ObjectivesUsing experiment extension pointUsing dummy SICS extension point
• Performance IndicatorsCreate a new experiment objectCreate dummy SICS objects
Four different SICS variables Two dummy SICS monitors A dummy SICS scan object
Experiment Component Library
• Each experiment object has a group of experiment components Components are grouped in an experiment component library Components are stored in a tree structure Each component has an unique path, eg, /user/name,
/sample/sampleInfo/NaCl, /acquisition/scan/centerScan
• Experiment should provide the structure of the component library via a component library advisor Advisor provides basic tree structure and hooks for further
expansion
Gumnut Library Advisor
Root/
User/user
Instrument/instrument
Scan/scan
Name (user metadata)/user/name
Address (user metadata)/user/address
Email (user metadata)/user/email
(hook)/instrument/additions
(hook)/scan/additions
(hook)/user/additions
Tutorial 2.2
• Learning Objectives Experiment component and component library Tasting the adaptor design pattern Using experiment component extension point Basic device proxy concept (more on Data Acquisition section)
• Performance Indicators Setup a new component library Create user metadata objects (experiment components) Create a experiment browser UI adaptor for user metadata
objects Customise the appearance of component group Create an instrument info object and hook to the component
library
AdaptorFactory(IAdapterFactory)
Client:Experiment Browser
Adaptor Pattern
UserMetadata(IUserMetadata)
UserMetadataBrowserPart(IBrowserUIPart)
1. Experiment Browser wants User Metadata class to provide the functionalities which are specified in IBrowserUIPart
2. If User Metadata object cannot provide this, the Experiment Browser will use the adaptor factory to resolve this
3. Adaptor Factory returns an object that implements IBrowserUIPart. This object knows how to communicate with User Metadata
Advantages:
• Customisable and reusable
• All User Metadata share only a single instance of IBrowserUIPart
Tutorial Outline
Basic GumTree ConceptSay “Hello World” to GumTreeExperiment ModellingData Acquisition
• Data Handling
• Instrument Adaptation
Data Acquisition• Data acquisition (DAQ) in GumTree is a set of sequential
(and possibly combinational) logic for controlling and sampling data from hardware.
• DAQ module in GumTree stores data in the experiment data object for data export and further data analysis
• DAQ module can be a scan, batch or any other possible method
• GumTree controls hardware via device proxy
• Control system adaptor in GumTree is responsible to provide the handle of device proxy
Working with Device Proxy• Device Proxy is a thin wrapper for objects in control system
SICS object: sics variable, monitor, virtual motor, etc TANGO object: device proxy EPICS object: process variable or artificial device object Device proxy interface is consist regardless which control system
GumTree connects to
• Device Proxy supports Execute commands synchronously / asynchronously Read attributes synchronously / asynchronously Write attributes synchronously / asynchronously Generate events and deliver them to event listeners
• Writing device proxy for GumTree will NOT be covered in this tutorial
Device Proxy API
DeviceData data = monitor1.syncReadAttribute(
ISicsGenericMonitor.Attribute.COUNT, DeviceSource.EXTERNAL);
int value = ((Integer)data.getData()).intValue();
Scan Template
• GumTree support generic scan routine via the scan template pattern
• Scan template is an object forControlling control system to perform scanVisualising live data during the scan processStoring data to centralised data object during an
experiment lifecycle
• Current GumTree scan framework requires scan template to supply UI for scan control and visualisation
Scan Template in Gumnut
SimpleExperimentGumnutScanTemplate
(IScanTemplate)
GumnutScanController
(IScanControlUIPart)
GumnutScanVisualiser(IScanVisUIPart)
CountCollector
Data(GTD)
SICSmonitor1
SICSScan object
SICSmonitor2
= SICS object
= Java class
= GumTree Data Object
1D Plot
Data Visualisation
• GumTree is capable of displaying 1D, 2D and 3D data with various rendering engine
1D
Tutorial 3.1
• Learning ObjectivesUnderstanding scan template design pattern
• Performance IndicatorsCreate a scan template for collecting 2
monitor counts at each scan pointDisplay live scan data
Tutorial Outline
Basic GumTree ConceptSay “Hello World” to GumTreeExperiment ModellingData AcquisitionData Handling
• Instrument Adaptation
GumTree Data Object• GumTree Data (GTD) Object is a data container for internal
application data• GTD has hierarchy data structure
GTDItem (data set container) GTDGroup (GTDItem container) GTDAttribute (attrbitute for GTDItem and GTDGroup)
root(GTDGroup)
Node 1(GTDGroup)
Node 2(GTDGroup)
Data(GTDItem)
Attribute 1(GTDAttribute)
Data 1(GTDItem)
Node 2.1(GTDGroup)
Data 2(GTDItem)
Attribute 2(GTDAttribute)
Data Exchange
• GTD can be used forChanging data format
Storing experiment data
XML GTD NeXus
HistogramDevice
Device Data GTD NeXus
GumTree
GumTree
Tutorial 4.1
• Learning ObjectivesUsing GTD ObjectWrite data to experiment data object
• Performance IndicatorsMake experiment object to handle data from
scan
Data Format
• A GTD object can be import from and export to different data format if adaptors exist. GumTree supports:HDF, NeXus, CSV, XML, etc.
• Data reader (importing) and data writer (exporting) can be customised to preserve the structure of GTD
Tutorial 4.2
• Learning ObjectivesUsing file formatCustomise file format reader and writer
• Performance IndicatorsA new HDF5 reader and writer for the Gumnut
experimentBe able to export data from experiment
Tutorial Outline
Basic GumTree ConceptSay “Hello World” to GumTreeExperiment ModellingData AcquisitionData HandlingInstrument Adaptation
Instrument Support
• GumTree supports one (or zero) instrument at runtime
• Each instrument in GumTree needs to map to a control system adaptor
• Instrument feature plug-in defines plug-in set for an instrument
Product, Feature and Plug-in
• Product Basic unit of an application Eclipse (RCP) support 0 or 1 product definition
• Feature Defining a group of plug-ins Disabling a feature will disable all its declared plug-ins
• Plug-in Set of contributions wrapped in a single unit
• Instrument Plug-in A plug-in with a single instrument extension declared
• Instrument Feature Feature which contains an instrument plug-in Feature should have id identical to its instrument id
Final Goal
• Toward the end of this tutorial:Create a GUI for out imaginary instrument,
GumnutPass all our contributions to GumnutRun GumTree with Gumnut, not Gumzilla
We do not want any contribution from Gumzilla!
Product, Feature and Plug-in
FeatureGumzilla
FeatureGumTreePlatform
ProductISEE
Plug-inSycamore
InstrumentPlug-inGumzilla
Plug-inGumnut
Plug-in…
Plug-in…
Plug-in…
#Instrument Plug-in: 1
Product, Feature and Plug-in
FeatureGumnut
FeatureGumzilla
FeatureGumTreePlatform
ProductISEE
Plug-inSycamore
InstrumentPlug-inGumzilla
InstrumentPlug-inGumnut
Plug-in…
Plug-in…
Plug-in…
#Instrument Plug-in: 2 -> Bad
Product, Feature and Plug-in
FeatureGumnut
FeatureGumzilla
FeatureGumTreePlatform
ProductISEE
Plug-inSycamore
InstrumentPlug-inGumzilla
InstrumentPlug-inGumnut
Plug-in…
Plug-in…
Plug-in…
#Instrument Plug-in: 1
Tutorial 5.1
• Learning ObjectivesUnderstanding instrument plug-in activation
with GumTree
• Performance IndicatorsWrapping contributions to a new instrument
plug-inLaunch GumTree with Gumnut
Reference
• Contributing to Eclipse: Understanding and Writing Plug-ins http://eclipsecon.org/2005/presentations/EclipseCon2005_Tutorial1.pdf
• GumTree Wiki
http://gumtree.sourceforge.net/wiki