 |
Phenom Programming Interface
|
|
Phenom Programming Interface
|
The Phenom G2 desktop SEM internally runs two processes, a "microscope server" and a "client", the graphical user interface. The client communicates with the server via two SOAP webservices; one to send commands and retrieve settings and images, and the other to receive events from the system.
In the G2 Pro edition, these webservices are exposed to external clients. This is what the applications in the Phenom Pro Suite use to communicate with the Phenom. This API ("Application Programming Interface") is also available to advanced users of the system, so you can control the Phenom, alter specific settings, query the Phenom for current parameters and settings and acquire images directly in your own software application.
The advantages of using webservices is that they are platform-independent, "discoverable" (self-describing), and that no client-side proxies need to be installed. In practice, it works "out of the box" for C#/.NET clients and Python, and C++ clients have been implemented on Linux (on the Phenom itself), iOS, Mac OS X, and Windows using gSOAP. A drawback is that no real ("push") events are supported, so they are implemented using a separate webservice and blocking calls.
For .NET, point Visual Studio to the URI of the Phenom (port 8888 for the command webservice and port 9999 for the events webservice) and "add Web reference". For gSOAP, point wsdl2h to the URIs mentioned above, and it will generate a header file for the proxies (generate implementation with soapcpp2). The code below is an example in Python:
from suds.client import Client import Image import base64 phenom = Client('http://PhenomG2.local:8888?om') imagingDevice = phenom.factory.create('ns1:imagingDevice') phenom.service.SelectImagingDevice(imagingDevice.SEMIMDEV) result = phenom.service.SEMGetLiveImageCopy(1) image = Image.frombuffer('L', (684, 684), base64.b64decode(result.aImageBuffer)) image.show()
It is important to realize that everything you can do with the Phenom using the graphical user interface (GUI), you can also do using the webservices: the GUI uses the exact same webservices. This also includes alignment settings and calibrations. The complete "command" webservice has more than 130 methods and defines over 100 data types. Some data types (such as the acquired image itself) are passed on the webservice in a format which is difficult to use directly in most programming languages. For the vast majority of end-user applications, the interface is much too detailed and elaborate.
This is also visible in the Python example above, which suffers from "leaky abstractions": The imagingDevice type is not native to Python and has to be created with a factory method, and the fact that the image data is returned in a base64-encoded array is one of the things "you need to know".
For this reason, Phenom-World has defined a higher-level interface in the form of a C++ library which you can link your applications against, and which offers an easy-to-use interface which hides most of the nitty-gritty details. This documentation describes this library and its use.
This documentation is aimed at developers who want to integrate Phenom control and/or acquisition into their own applications. The documentation assumes proficiency in C++ but the code avoids features from the C++11 standard so it should be compatible with older compilers.
The code has been tested with Xcode on a Mac (with the Clang compiler), Visual Studio on Windows (including Visual Studio Express Edition) and GCC on Linux. The code is 64-bit clean.
The image below illustrates the set-up:
The command API of the Phenom is devided in five "sections":
All methods use HTTP authentication with an instrument-specific username/password pair (contact Phenom-World for more information). This is also for security reasons; a Phenom connected to your company LAN will happily expose its webservices to anyone querying for it. Without the username/password pair, anyone in your LAN could remotely operate your Phenom. There is also a setting in the "Network" section of the Phenom advanced settings pages which lets you disable remote access completely.
Every method returns an om::RetVal value, which is an enumeration of OK, FAIL (generic error), CONTEXT (command currently rejected; Phenom busy), COMM-ERROR (communication problem), CLIPPED (value was clipped to available range), or UNCAL (Phenom is in an uncalibrated state).
In the Phenom proxy documented here, functions do not return error codes but throw exceptions (of type PhenomTypes::Error) when an error occurs. The structure contains an error code and a textual description.
The archive comes with a sample project for a command-line tool to control the Phenom and acquire images. This can serve as a template for your own code.
To save images, this sample project makes use of existing open-source libraries which are not included in this distribution, but which can be found at http://www.remotesensing.org/libtiff (a library for reading and writing TIFF image files), http://www.ijg.org (a library for reading and writing JPEG files) http://zlib.net (a library for data compression). Please follow the instructions at those websites to install these libraries on your own system. The sample project can also be compiled without support for saving images, in which case you do not need these libraries.
