CamiTK Extension Project

What is a CamiTK Extension Project?

CamiTK Extension Project (CEP) is a way of managing source code tree as well as extension archiving and distributing. In simple words: it is a way of organizing your extensions and group them by themes.

A CEP helps you to maintain the source code of any extension. A CEP can contain the following things:

• action extensions
• component extensions
• application extensions
• viewer extensions
• specific libraries that are needed for this CEP.

The main idea is to group the actions, components, applications and viewers that are specific to one scientific field. A CEP helps to define a perimeter for the collaboration of a group of people who are working on a common (research) project. It therefore simplifies dependency management: a CEP should contain everything needed for building the provided actions or component extensions (and if not, it should be built on top of another CEP).

When a directory contains more that one CEP subdirectory, we call that a CEP Set (CEPS).

What is CamiTK Community Edition?

The CamiTK Community Edition is a set of CEP. It provides:

• the SDK (Sofware Development Kit) CEP is the base of all CamiTK development. It provides the CamiTK core library, some basic but useful component and action extensions as well [four applications]/docs/getting-started/applications/). It is required to do any development in CamiTK. The SDK is based on VTK Qt (and CodeSynthesis XSD), and that’s all. Additionally to CamiTK core, it provides two useful libraries: coreschema (the CamiTK Core XML data-binding library), qtpropertybrowser (to build GUI for Qt’s meta-property).
• the Imaging CEP contains all the action and component extensions that are useful for processing medical imaging. It provides the dicom and itkimage components, the itk filters and itk segmentation actions. It depends on… ITK.
• the Modeling CEP contains all the action and component extensions that are useful for biomechanical processing. It provides the LML,PML and MML libraries, and the related components and actions.
• the tutorials CEP contains example code. This is where you should look for [C++ examples on how to do things]/docs/tutorials/).

The CamiTK SDK is named because not only you get the fundamental source code and the CamiTK Core library, where the service layer is defined, but you also get [four end-user applications]/docs/getting-started/applications/) that are required or can help you to develop your own Computer Assisted Medical Intervention application:

• [camitk-imp]/docs/getting-started/applications/imp/)
• camitk-config
• camitk-wizard
• camitk-actionstatemachine

What is the structure of a CEP?

This figure shows an example of the recommended tree structure for a CEP. You do not have to do this, but it is what we use for our projects CEP (including in the Communty Edition CEPS), and what we recommend. See also at the end of this section, the little note about CEPS.

This example shows a CEP called cepname. Everything useful for the project development is inside a directory called cepname.

There are three sub-directories at the top level of cepname:

• subdirectory src contains all the CEP source code. You can also name this directory cepname, which can facilitate the use of a version control system, such as git.
• subdirectory doc contains all the external/specific documentation about this cep
• subdirectory build is the build directory needed by CMake, it contains all generated files and can be deleted/regenerated at any time (notice that on this screenshot it is in italic, which means it is a link to a temporary directory somewhere outside the source tree to avoid unnecessary backup of generated object/binary).

Source subdirectory

The source subdirectory itself contains:

• README (optional but recommended), it contains some general information about your CEP (this is not the same as the description found in CEPDescription.cmake). You can explain some specific things about your CEP in the README (this is good practice). It will be the first thing other CamiTK developers will read before bombarding you with questions (got the tip?)
• COPYRIGHT contains the copyright information about the source code of the entire CEP. By default it follows the same COPYRIGHT as CamiTK (LGPL-v3), so if you have a different copyright do not forget to edit this file for reflecting your licence.
• the top-level CMakeLists.txt and the FindCamiTK.cmake files are needed to build the CEP (default version of this file should work out-of-the-box, once you have set up CEPDescription.cmake)
• subdirectories actions, components, applications and viewers contains all the extensions provided by the CEP. Depending on your CEP these directories might stay empty.
• subdirectory libraries includes all the specific libraries that are needed for this CEP

Note on Copyrights and License

If your CEP is still a work in progress, you don’t need to think too hard about its copyright and the license under which it will distributed. Although you don’t need to decide at the beginning if your CEP can/should be distributed as an Open-Source CEP, but it won’t hurt to start thinking about it.

If for any reason you think you can not keep the LGPL-v3, please do not forget to edit COPYRIGHT accordingly.

What are the different step when developing a CEP?

There are several steps during the development of a CEP:

1. Run the camitk-wizard application in order to create the initial structure of your CEP
2. Setup a git repository or ask the CamiTK team to host your project (and commit regularly during the next steps!)
3. Develop your code, in your ‘src’ directory, iterate, check your code
4. Do your basic tests using camitk-imp which automatically load your compiled extensions from the ‘build’ directory
5. If you want to test your code with a version already installed on your computer or if you have more than one CEP with dependencies, do a ‘global-install’ or a ‘local-install’. Test your changes again.
6. You may setup automatic unit/integration test thanks to the CamiTK test framework
7. Once you think your work is mature enough to be released, you may decide to share it in CamiTK Community Edition or distribute privately within your organization

This can be summarized in the following figure:

This section contains different questions about these steps.

How do I start a CEP from scratch?

camitk-wizard provides a way to automatically build a source code skeleton for a new CEP. You can also create a new CEP from scratch.

Can you host my CEP?

When you start working on a CEP, it might not be ready to be publicly available. This step of the code maturaty level is called CEP incubation.

The different phase of your development process are based on the maturity level of your code, its organization, the level of tests, continuous integration, documentation…etc…

CEP can be incubated in a special area of the application lifecycle management called gitlab, hosted at our university. This area are called “incubator”.

There are two types of incubators:

• the public incubator where you may store your CEP with extensions that are open-source and publicly available. If your project is hosted in our public incubator, it is available worldwide without restriction access.

For instance the albert project can be clone directly like this:

git clone git@gricad-gitlab.univ-grenoble-alpes.fr:CamiTK/CamiTK-Incubator/albert.git

• the private incubator where your code may not be visible from people outside of the CamiTK project team. Use this incubator if your CEP has copyrighted source code or is not really for public scrutiny yet.

Do not hesitate to ask us: we can host your project in the main CamiTK project on our gitlab instance, and even protect it from external eyes.

Of course you can self host your project and this decision is entirely up to you!

Can I integrate my CEP into CamiTK Community Edition?

Yes!

Once you feel your CEP is ready for exhibition, you might want to integrate it into CamiTK Community Edition. The CamiTK project will help you, so don’t worry. Do feel free to contact us. This is a great opportunity: more freely available extensions for everyone and less management for you!

Where and how should I install my CEP extensions?

The extensions of a CEP have to be installed in an [extension repository]/docs/getting-started/extensions/#extension-repository).

You don’t need to install your extensions during the development process: they are automatically installed in the build directory at compile time. Once you are satisfied with them you can either install it in the global or local repository.

There are two specific types of installation of a CEP:

• Global installation (build target cepname_global_install). This will install your CEP extensions in the global repository (the same place where the CamiTK is installed). You might need superuser privilege to do so (depending on where the global repository is located on your machine). If the SDK is accessible to all users of the machine, the main advantage is the global installation is that all users can then use your extension.
• Local installation (build target cepname_local_install). This will install your CEP in the local repository (i.e., %APPLICATION\_DATA% on Windows, $HOME/.config on Unix and MacOs). It will only be available to you only. The main advantage is that you do not need administrative right but your extensions will still be available locally (for instance if you have a second CEP with extensions that depends on the first CEP).

When a CamiTK application (imp, actionstatemachine or any other application) is launched, it will load all the install extensions from the three possible repository the following order of priority:

• build directory (to ensure the currently developed version is used proprietarily to previously installed versions)
• local directory
• global directory

If you do not want to install your extension, you can still ask CamiTK to load your extension automatically at runtime by registering your extension shared object (.so, .dllor.dylib). To do so, run camitk-imp` and go to the preferences dialog, then manually add your action, component or viewer extension.

This is not a very recommended way, but might help you in some case/

Can I generate a source package of my CEP?

Yes!

Once you have configure your CEP using CMake you can use the specific build target package_source to generate a source package containing all your code.

On the command line, go to the build directory and type:

cmake --build . --parallel 8 --config Release --target package_source

In an IDE select the build target package_source.

This target will generate a .tar.gz and .zip that contains the same structure and files as your source directory. It will be named depending on the description you gave in the CEPDescription.cmake file and the CamiTK version you are currently using. For instance, the foo CEP produces two files: foo-5.0.0-Source.zip and foo-5.0.0-Source.tar.gz.

This way you can easily archive or share your code outside of your gitlab project.

Can I generate a binary package of my CEP?

Yes!

Once your CEP is configured you can also generate a binary archive.

The binary archive is a very easy way, independent from the chosen source code license, to distribute / send your extensions to your colleague, fellow researcher, clinicians, or any other type of partner who will need / want to check or use your code.

To build a binary package of your CEP, you can use the camitk_extension_package target.

On the command line, just go to the build directory and type:

cmake --build . --parallel 8 --config Release --target camitk_extension_package

In an IDE select the build target camitk_extension_package.

This target will generate a .cep file, which in fact is a tar.gz archives with the same directory structure as a CamiTK extension repository.

Once CEP binary archive is unzipped, your recipients just have to manually register or install your extensions in the appropriate [extension repository]/docs/getting-started/extensions/#extension-repository). Then she/he can run camitk-imp or camitk-actionstatemachine to be able to start using it!

Where should I go next?

Ready to go? These are probably the next steps:

• Understand CamiTK applications: What are available applications in CamiTK?
• Examples: Check out some example code!