Imaris Open - Frequently Asked Questions

System Requirements

Find the recommended Hardware requirements for Imaris Open here

To use Imaris XT requires that you have Imaris 7.3 or higher.

The most commonly used Imaris XTensions are written in MATLAB. Recently, Imaris added an easy integration of Python scripts and their plug-ins.

The usable variables of Imaris can be found under the programming reference manual under Help > Programming Interface.

How to install a downloaded XTension?

PC Users

The first step of integrating the XTension within Imaris is to specify the folder with the downloaded XTension file. To do that, under the Edit menu, select Preference and then choose the Custom Tools option. Under the XTensions Folders option ,click on the Add button to add the downloaded XTension file paths to the list. After that, all XTensions within the selected folder are ready to be used and no additional steps are required.

Please make sure that the paths to Python executables are set correctly.

Mac users

The first step of integrating the XTension within Imaris is to specify the folder with the downloaded XTension file. To do that, go to the Preference and then choose the Custom Tools option. Under the XTensions Folders option, click on the Add button to add the path to the downloaded XTension folder to the list. After that, all XTensions within the selected folder are ready to be used and no additional steps are required.

Please make sure that the paths to Matlab/ Python executables are set correctly.

How to join the Imaris XT Developer Program?

From the starting page, click on the Become a Developer button located in the left hand menu. Once you have completed the application form and it is accepted by the Bitplane support team, you can start submitting your XTensions.

What are the coding regulations?

This guide is oriented towards developers and covers the technical details of the MATLAB/Python script integration within Imaris.

It provides a step-by-step procedure how to establish connections between the MATLAB/Phyton and Imaris and how to embed a newly developed MATLAB/Python script as an XTension function.

Please note:

If you are a MATLAB developer, please refer to the part of the document entitled MATLAB code regulations.
If you are a Python developer, please refer to the part of the document entitled Python code regulations.
When you build an Xtension, you can either do this from scratch, or download the Matlab / Python XT example XTension and modify it
When building XTension from scratch, please refer to the MATLAB/Python code example page find out how to structure it.
To ensure that Imaris can start your MATLAB/ Python script when the user launches an XTension, a setup step is required.
In the following section, we will describe the changes and show the code example necessary to convert your Matalb/ Python code or XT example into a new XTension.

1. Download the XT example XTension from Imaris Open, and extract it.
2. Add the folder location to the Imaris under the Edit -> Preferences -> CustomTools" and add the folder location into the "XTension folders"
3. Open XTexample.m in MATLAB

To expand the Imaris interface beyond the predefined configuration, a special header must be added to the MATLAB file.

As this MATLAB/Phyton function is no longer launched within the MATLAB/Python interface, a few lines of the MATLAB/Python file need to be adjusted: 

A commented xml structure where the new command is defined as well as the location in the Imaris menu.
Several lines that connect to the interface of Imaris and MATLAB/Python
Lines that define the vImarisApplication variable
An XTension is added to the menu by specifyingThe MATLAB/Python function to be called must have the same name as the MATLAB/Python file that contains this function. It is the entry point of the script.

4. Change the name for your XTension from XT example to a name you like.This must be done in the XML part at the beginning of the file (MatlabXT::XTexample(%i)), and in the function definition (function XTexample(aImarisApplicationID))..
5. Adjust the tooltip and the description of your XTension
6. Delete all the whole code below the line that says 'XTension specific code starts here'. The whole code between the function definition (function XTexample(aImarisApplicationID) ) and that line is the same for all XTensions.
7. Implement your XTension.Refer to the Imaris Programming Interface or the ImarisOpen page for details on how to write XTensions.
8. Finally, rename your file to the new name of your XTension that you have chosen in the step above. Note that the file must end on .m./p

What are the recommended files for uploading an XTension?

To upload a new created XTension, a few additional files need to be created.

If you have the opportunity to compile your XTension and make it available to other users, please include compiled exe/app and xml files in the ZIP folder.

XTension generated with MATLAB Compiler components can be used even if MATLAB is not installed on the end-user's system.

Note: If you choose this option, please deploy ImarisLib.jar with your compiled XTension.

Write your own instruction document or modify the HowToTest.txt file with a description of how to use your XTension.

Create a sample image that can be used to test your XTension. Alternatively, describe in HowToTest.txt a way to test your XTension with one of the images that are part of Imaris.

Create one or several meaningful screenshot that illustrate your XTension results

Create a zip file containing your XTension (*.M file and preferably complied XTension files *.exe and *.xml) , the HowToTest.txt file and the sample image.

Upload the zip file and the screenshots to ImarisOpen.

Please note once your XTension is submitted, you will not be able to make any modifications until it has passed through the review process.

After your XTension has been verified by the ImarisOpen team, it will be available on the ImarisOpen XTension Exchange page.

What are the steps in the approval process?

The overall objective of the XTensions approval process is to provide a comprehensive, safe and structured pool of XTensions to Imaris users.

In order to satisfy high demands of trustworthiness, our manual approval process involves the validation, verification and acceptance testing of XTensions.

The subsequent steps are performed in the approval process: 

Reviewing and inspecting the source code
Evaluating the source code against Bitplane requirements
Assess the quality of the information/essential information contained for its relevance to the users
Imaris integration testing
Program execution
Setting the verification flags

How long does the verification process take?

All uploaded XTensions are manually verified and this could take up to a few days to complete. If our support team requires additional information on top of already submitted ones, it may add to our verification time. Make sure that all of your contact information is correct so that we can get in touch with you if needed.

XTension Approval Status

At the top of your developer profile page, you will find the status of your submitted XTension. The following labels will explain the status:

Approved

If your XTension has met our requirements, it is approved and available on the XTension Exchange list.

Additional Review

To complete a review, our support team may request additional information and your XTension would then be listed for additional review. Note that you cannot make any changes to your XTension once you have re-submitted it for additional review.

If the XTension does not meet our minimum standards and quality guidelines/requirements, it will not be approved.

Our support team can reject the XTension if it fails to meet the criteria, or mark it for Awaiting Feedback and pass it back to the user for modifications

Denied

Your XTension review was completed, but your submission did not meet the requirements.

How to modify the uploaded XTension?

Once an XTension is approved, the user can modify the XTension at any time by going into their profile. Confirming the changes will remove the XTension from the XTension Exchange list and submit it for further approval.

If the changes are accepted and the XTension is once more approved, it will be again available in the Exchange list and its Comments and Ratings will be unaffected.

However if the modifications are evaluated to be major and sufficient to justify a new upload, Support will reject the proposed changes and request that a new XTension is uploaded in its place. In this case, the comments and ratings will not be preserved.

All change requests must be sent via email to our support team for approval. If your XTension requires additional review, please make the appropriate changes to ensure that the modifications you have made meet our guidelines and requirements.

Any request to modify an XTension must be clearly defined and described, including the change to be made and the issues or reasons for the modification.

Once your XTension status changes, an email will be sent informing you of this change and any issues or reasons for the change if applicable.

What to do if the verification e-mail is not received?

It’s possible that your e-mail junk or spam filter has caught the verification mail, so check there first.

Otherwise, if you haven’t received an e-mail within 48 hours of uploading your XTensions, please contact customer service via the “Support” tab in the navigation bar of this page.

Can I suggest some changes to categorization?

Categories in Imaris Open are constantly evolving to cope with the increasing amount of XTensions. We do our best to provide a good categorization to fit all the XTensions listed. If you feel that an XTension deserved to be in a new category, please let us know about your suggestion. You can also post your feedback on our forum.

If you are unsure where to publish your XTension, a good starting point would be to look at other related XTensions and find how they are listed.