OsiriX Development Guide

Welcome to the OsiriX development Guide. This Guide was brought to you by the OsiriX development Team and is frequently updated.

For global information about the project, contributors, visit GitHub.

Developing on Mac OS X

Developing software on Mac OS X is really 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:

Other useful resources to learn Cocoa and Objective-C:

The development environment is Xcode. Xcode is a really powerful development environment, based on the open-source GCC compiler. Writing a plugin for OsiriX is much easier than developing in IDL or in ImageJ...

Getting OsiriX Source Code

You will find here a quick step by step to download OsiriX Source Code from GitHub.

Before starting anything, make sure that you have the following installed:


To download the plugins distributed with OsiriX:

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.

A small presentation to start writing an OsiriX plugin: Keynote presentation.

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 .osirixplugin or .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. The PluginFilter class is defined in PluginFilter.m, available in the OsiriX headers folder. Don't modify this file!

The -(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 Info.plist file).

In your plugin you can call virtually any function of OsiriX.

Here is a list of available objects in OsiriX:

Look at the headers files of these objects to find which functions are available and how to call them.

The pluginType field of the info.plist file contains one of the following name:

Some Plugins and Sample Code

The OsiriX Plugins project on GitHub provides a large variety of sample plugins.

The 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 3 different locations:

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.

The generic .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:

This application should be able to control OsiriX to facilitate the integration. For example, the other application should be able to:

With OsiriX 3.0, we introduced a very easy and powerful protocol for such control. OsiriX integrates now 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.

A sample plugin is available in the Plugins folder in the SVN repository: XML-RPC-Plugin

Documentation is available here: HIS Integration

URL protocol : osirix

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 from another application on the same computer: for example a Java application or a Web based software.

This technique uses an URL protocol : osirix. This method is simpler than the XML-RPC messages: the syntax is shorter, and you simply 'open' an URL to execute it. The disadvantages compared to the XML-RPC messages : the other application needs to run on the same computer and in the same environment (MacOS). This technique can only send an order to OsiriX, it cannot retrieve informations.

The other application can, for example:

This URL protocol supports has been introduced with OsiriX 3.9 and higher.

This protocol supports the built-in XML-RPC protocols (not the XML-RPC protocols supported through plug-ins).

For example, you can post these messages from another application:

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.

More Help?

If this guide does not answer all your questions, please try our developers mailing-list:


Your can directly subscribe through here:

Subscribe to OsiriX Developers group