OsiriX Development Guide
Welcome to the OsiriX development Guide. This Guide was brought to you by the OsiriX development Team.
Developing on macOS
Developing software on macOS is easy, great and it's totally free! The complete development environment is available with any Mac! The language you will use to develop an OsiriX plugin is Objective-C. Objective-C is a dynamic and object-oriented language, like Java. It is very similar to Java and C++. It uses the same syntax as Java and C++. It is much less complex than C++ and much faster than Java. If you already know Java or C++, you could probably learn Objective-C in less than 2 days...
The framework you will use is Cocoa. Cocoa is a powerful and object-oriented framework that will allow you to create any kind of plugin with complex graphic user interface.
We highly recommend you to read the following books:
- Cocoa Programming for Mac OS X by Aaron Hillegass
- Learning Cocoa with Objective-C by James Duncan Davidson & Apple, Inc.
- Programming in Objective-C by Stephen Kochan
Other useful resources to learn Cocoa and Objective-C:
The development environment is Xcode. Xcode is a really powerful development environment. Writing a plugin for OsiriX is much easier than developing in IDL or in ImageJ.
Creating a Plugin
The plugins architecture of OsiriX allows you to implements the features that you need. You will be able to access the images data, DICOM header data, make an integration of OsiriX in you specific Hospital environment, and much more.
To access the functions defined in OsiriX, you need to add the OsiriX API framework in your plugin. The latest version of the OsiriX API framework is available in all versions of OsiriX. It's located in the application package: /OsiriX.app/Contents/Frameworks/OsiriXAPI.framework
You can copy the OsiriX API framework to your plugin folder, or only link against it.
A complete iTunes U presentation: iTunes movies.
A blog about plugin development: Web Site
The Plugins Architecture of OsiriX
When OsiriX is launched, it will look in the 'plugin' folders for files with the
.plugin extensions. It will then try to find if the plugin contains a sub-class of
PluginFilter having a
-(long)filterImage:(NSString*)menuName; method. OsiriX will then run once the
initPlugin function if available.
Your plugin is a sub-class of
PluginFilter class is defined in
PluginFilter.m, available in the
OsiriX headers folder. Don't modify this file!
-(long)filterImage:(NSString*)menuName; method is the main function of a plugin. OsiriX will always use this function to call your plugin. The
menuName string contains the menu selected by the user. You can can define more than one menu for your plugin (in the
In your plugin you can call virtually any function of OsiriX.
Here is a non-exhaustive list of available classes in OsiriX:
PluginFilter: your plugin is a sub-class of this object, it contains some useful functions
NSWindowControllerof a '2D Viewer' window
NSOpenGLViewthat contains the displayed image
DCMPix: object that contains the pixel data of an image
dicomFile: an object that contains data about the DICOM file
ROI: an object that contains a ROI
MyPoint: an object that describes a 2D point
Look at the headers files of these objects to find which functions are available and how to call them.
pluginType field of the
info.plist file contains one of the following name:
imageFilter: your plug-in will appear in the 'Image Filters' menu
roiTool: your plug-in will appear in the 'ROIs tools' menu
other: your plug-in will appear in the 'Others' menu
fusionFilter: your plug-in will appear in the 'Fusion' window
Database: your plug-in will appear in the 'Database' menu
Some Plugins and Sample Code
HelloWorld plugin was created to help developers to understand how to interact with OsiriX.
The main class contains several sample methods showing some basic functionalities.
Distributing & Installing your Plugin
The distribution of your plugin is left to you. The OsiriX team does not host nor distribute 3rd party plugins. However, if your plugin match our quality standards, we can reference your plugin page from the Plugin Manager in OsiriX app. A place of choice to be wildly visible by our users. You will find the application form directly in the Plugin Manager window of OsiriX.
The OsiriX plugins can be installed in 2 different locations:
/Library/Application Support/OsiriX/Plugins/- The plugins installed in this folder will be accessible by any user of the computer
/Users/.../Library/Application Support/OsiriX/Plugins/- The plugins installed in this folder will be accessible only by the specified user (replace the
...by the user short name)
The installation of you plugin is automatic if you chose the
.osirixplugin extension. In this case, the user just has to double-clic the plugin icon and OsiriX will install it for the current user.
.plugin extension is still supported but will not provide this mechanism. The user will have to manually copy the plugin into one of the 3 directories.
Adding support for XML-RPC messages - RIS/HIS Integration
OsiriX is a DICOM Viewer, aka PACS Workstation, but it is not a HIS or a RIS software. If you have such software installed, it can be useful to 'control' OsiriX or 'get' informations from/to another application:
- an application running on the same computer. For example a Java application or a Web based software
- an application running on the same computer, but in a different environment. For example in Windows OS, in Parallels or VMware Fusion software.
- an application running on a different computer on the same network. For example a web server application, like an ASP software.
This application should be able to control OsiriX to facilitate the integration. For example, the other application should be able to:
- Check if a study is available in the OsiriX Database
- Open a specific study, and display the images
- Delete a study
OsiriX integrates an HTTP server with an XML-RPC protocol. It means that any software/computer that knows your network address can execute methods in OsiriX. Later, we added the osirix:// URL scheme, with the possibility of executing XMLRPC methods by providing the method name and parameters as part of the URL.
XMLRPC methods can be built-in in OsiriX or added in plugins. To turn the XML-RPC HTTP server, go to the Listener Preferences window in OsiriX.
Documentation is available here: HIS Integration
Build your own ITK library for your plugin
If you want to include your own version of ITK (or VTK) in your plugin, you need to be sure there are no conflicts with the compiled libraries included in the OsiriX main source code.
This document will help you to prepare and include your own ITK libraries in a plugin.
Special thanks to Brian Jensen.
See PetSpectFusion plugin in the plugins folder for an example.
If this guide does not answer all your questions, join our Help Center: