DSX Software Development Kit: Difference between revisions
No edit summary |
m (Text replacement - "http://www.c-motion.com" to "https://www.c-motion.com") |
||
(44 intermediate revisions by the same user not shown) | |||
Line 3: | Line 3: | ||
__NOTOC__ | __NOTOC__ | ||
To enable users of the [[DSX_Overview|DSX Suite]] to expand the suite with their own code, a DSX Software Development Kit (<b>DSX SDK</b>) is released with the suite. The DSX SDK comes in its own installer file and needs to be installed separately from the DSX Suite. | To enable users of the [[DSX_Overview|DSX Suite]] to expand the suite with their own code, a DSX Software Development Kit (<b>DSX SDK</b>) is released with the suite. The DSX SDK comes in its own installer file and needs to be installed separately from the DSX Suite. In order to add their own algorithms to DSX, the user would use the SDK to compile and build additional dynamic library files (dll files) that most DSX applications will load during start-up. | ||
In order to add their own algorithms to DSX, the user would use the SDK to compile and build additional dynamic library files (dll) that most DSX applications will load during start-up. | |||
Currently the SDK enables our DSX users to develop their own LCS algorithms that can be applied in [[Orient3D_Overview|Orient3D]]. We plan the expand the SDK in the future. | Currently the SDK enables our DSX users to develop their own LCS algorithms that can be applied in [[Orient3D_Overview|Orient3D]]. We plan the expand the SDK in the future. | ||
Line 14: | Line 12: | ||
| | | | ||
:In order for the generated dll files to work properly with the DSX applications they need to be compiled and build with the same compiler that is used for DSX Suite. Currently this is: <b>Microsoft Visual Studio 2019</b>. | :In order for the generated dll files to work properly with the DSX applications they need to be compiled and build with the same compiler that is used for DSX Suite. Currently this is: <b>Microsoft Visual Studio 2019</b>. | ||
:In order to debug the newly developed code, the <b>DSX Suite</b> needs to be installed as well. | |||
:The use of the Qt and/or VTK libraries is not required, but if they are used, their versions need to match the ones with which the DSX Suite is developed. | |||
:Current <b>Qt</b> version: 5.13.1 | :Current <b>Qt</b> version: 5.13.1 | ||
:Current <b>VTK</b> version: 8.2 | :Current <b>VTK</b> version: 8.2 | ||
Line 24: | Line 24: | ||
|- | |- | ||
| | | | ||
:C-Motion software is all downloaded over the Internet at [ | :C-Motion software is all downloaded over the Internet at [https://www.c-motion.com www.c-motion.com]. | ||
:Customers are provided login information to access the download page. | :Customers are provided login information to access the download page. | ||
:After you log in at [ | :After you log in at [https://www.c-motion.com www.c-motion.com], you will see a screen similar to this: | ||
[[File:Down1.jpg]] | [[File:Down1.jpg]] | ||
Line 46: | Line 46: | ||
:Your computer may ask you to confirm that you trust the source of the program you are installing. | :Your computer may ask you to confirm that you trust the source of the program you are installing. | ||
:The installer will install a number of header files in the <i>include</i> folder, one source file (CMGlobalTime.cpp) in the <i>src</i> folder, | :The installer will install a) a number of header files in the <i>include</i> folder, b) one source file (CMGlobalTime.cpp) in the <i>src</i> folder, c) 4 static library files in the <i>lib</i> folder, and d) a working example in the <i>Example</i> folder. It will also add the <b>CM_DSXSDK_DIR</b> variable to the computer's registry. This environment variable enables the DSX applications to find your dll files. If the installer is run with admin privileges, it will become a system-wide environment variable, otherwise it will only be available to the current user. | ||
:When the Completed dialog appears the DSX SDK has been successfully installed on your computer. | :When the Completed dialog appears the DSX SDK has been successfully installed on your computer. | ||
Line 57: | Line 57: | ||
|- | |- | ||
| | | | ||
:The easiest way to get started is to copy the contents of the <i>Example</i> folder in the SDK installation folder to a location where you have write permission. The names of the three .vcxproj files can be changed in Windows Explorer (e.g. into MyDll.vcxproj, MyDll.vcxproj.filters, and MyDll.vcxproj.user) as long as all three files have the same name and their extensions remain unchanged. The project can be loaded into Visual Studio by double clicking on the .vcxproj file or by starting Visual Studio, selecting 'Open a project or solution' and selecting the .vcxproj file in the file dialog. | :The easiest way to get started is to copy the contents of the <i>Example</i> folder in the SDK installation folder to a location where you have write permission. The names of the three *.vcxproj files can be changed in Windows Explorer (e.g. into MyDll.vcxproj, MyDll.vcxproj.filters, and MyDll.vcxproj.user) as long as all three files have the same name and their extensions remain unchanged. The project can be loaded into Visual Studio by double clicking on the *.vcxproj file or by starting Visual Studio, selecting 'Open a project or solution' and selecting the .vcxproj file in the file dialog. | ||
:The names of the header and source files can be changed in Visual Studio. New files (with new C++ classes) can be added as well. | |||
: | :On exit Visual Studio will give the opportunity to save the *.sln (solution) file. This is not required, but is a means of keeping multiple VS projects (i.e., multiple dlls) together. | ||
==Export directive== | ==Export directive== | ||
:The LCSExampleModule.h (or MyDllModule.h) file defines a macro that defines the export directive. When the name of the macro is changed, the LCSExampleTransform.h (or MyTransform.h) and LCSExampleFactory.cpp (or MyFactory.cpp) files need to be edited accordingly as well. Make sure the | :The LCSExampleModule.h (or MyDllModule.h) file defines a macro that defines the export directive. When the name of the macro is changed, the LCSExampleTransform.h (or MyTransform.h) and LCSExampleFactory.cpp (or MyFactory.cpp) files need to be edited accordingly as well. Make sure the MYLCS_EXPORT<b>S</b> entry matches the preprocessor definition in the properties of the project for both Debug and Release mode. | ||
==Algorithm class== | ==Algorithm class== | ||
:To implement a new LCS algorithm, one would create a C++ class like the LCSExampleTransform class; the new class would inherit from CMLCSTransformBase, and its constructor and internalUpdate() are the only functions that need to be overloaded. | :To implement a new LCS algorithm, one would create a C++ class like the LCSExampleTransform class; the new class would inherit from CMLCSTransformBase, and its constructor and internalUpdate() are the only functions that need to be overloaded. | ||
:*The <i> | :*The <i>Description</i> variable is the identifier that is displayed in the O3D gui and is set using the setDescription() function. Internally, this string is used for the instantiation of the correct algorithm class object. | ||
:*The <i>m_Side</i> | :*The <i>m_Side</i> variable enables the implementation of both the proximal and distal LCS algorithms for a particular bone in one C++ class. | ||
:*The <i>m_Landmarks</i> variable stores the mandatory and optional landmarks used by the algorithm. Each landmarks constructor takes a string for the name that is displayed in the application gui | :*The <i>m_Landmarks</i> variable stores the mandatory and optional landmarks used by the algorithm. Each landmarks constructor takes a string for the name that is displayed in the application gui. By default a landmark is not optional; use the setOptional() function to change this. | ||
:The implementation of the algorithm goes into the internalUpdate() function. | :The implementation of the algorithm goes into the internalUpdate() function. The function will use the object's surface model data (<i>m_Mesh</i>; for the CM3DFmtBase class see the CM3DFmt.h file in the \include\CMLib\CMCore\CM3DFmt folder in the DSX SDK installation folder) and the landmark data (<i>m_Landmarks</i>) to determine the elements of the 4x4 row-major <b>Matrix</b> member variable. The transformation matrix represents the transform from the object's CT coordinate system to its local coordinate system ([[DSX_Definitions#Coordinate Systems|LCS]]). | ||
==Factory== | ==Factory== | ||
Line 85: | Line 87: | ||
<code> | <code> | ||
<!--<source lang="cpp" line="1">--> | <!--<source lang="cpp" line="1">--> | ||
<b>MyFactory</b>::<b>MyFactory</b>(const char* identifier | <b>MyFactory</b>::<b>MyFactory</b>(const char* identifier) | ||
: cmFactoryBase(identifier)</br> | : cmFactoryBase(identifier)</br> | ||
{ | { | ||
Line 92: | Line 94: | ||
:this->registerClass("CMLCSTransformBase", // changes for different algorithm types</br> | :this->registerClass("CMLCSTransformBase", // changes for different algorithm types</br> | ||
:::lcs_algo->getClassName(),</br> | :::lcs_algo->getClassName(),</br> | ||
:::lcs_algo->getDescription | :::lcs_algo->getDescription(),</br> | ||
:::0,</br> | :::0,</br> | ||
:::cmObjectFactoryCreate<b>MyTransform</b>);</br> | :::cmObjectFactoryCreate<b>MyTransform</b>);</br> | ||
Line 100: | Line 102: | ||
<!--</source>--> | <!--</source>--> | ||
==Caveats== | |||
*Depending on the situation, each factory uses either the string returned with <i>CMObjectbase::getClassName()</i> or <i>CMObjectbase::getDescription()</i> to create one of its registered class objects. In case of duplicates the first instance that is found is used. | |||
*Ignore the warning C4275: non dll-interface class 'A' used as base for dll-interface class 'B' that Visual Studio generates. | |||
|} | |} | ||
==Debugging your code== | {| class="mw-collapsible mw-collapsed wikitable" width="80%" | ||
! style="text-align:left;" | Debugging your code | |||
|- | |||
| | |||
:Debugging code created with the DSX SDK requires the DSX Suite to be installed as well. Because the applications in the DSX suite are release builds, you can only debug the release build of your dll. The *.vcxproj.user file in the DSX SDK Example installation folder ensures the Orient3D application is started when debugging is started (F5 key) in Release mode. | |||
:<b>Note:</b> Realize that debugging release code means certain parts of the code might have been removed from the optimized code. Some additional information can be found [https://docs.microsoft.com/en-us/cpp/build/how-to-debug-a-release-build?view=vs-2019 here] and [https://www.codeproject.com/Tips/727711/Debugging-Release-Projects-in-Cplusplus-Finding-th here]. | |||
|} | |||
{| class="mw-collapsible mw-collapsed wikitable" width="80%" | |||
! style="text-align:left;" | Including your dll in DSX applications | |||
|- | |||
| | |||
:The DSX applications need to know in which folder to look for your dll file. To accomplish this create an environment variable <b>CM_DSX_USER_DIR</b> that points to this folder. | |||
[[Image:SDK_CM_DSX_USER_DIR.png|800px|center]] | |||
|} |
Latest revision as of 16:18, 20 May 2024
Language: | English • français • italiano • português • español |
---|
To enable users of the DSX Suite to expand the suite with their own code, a DSX Software Development Kit (DSX SDK) is released with the suite. The DSX SDK comes in its own installer file and needs to be installed separately from the DSX Suite. In order to add their own algorithms to DSX, the user would use the SDK to compile and build additional dynamic library files (dll files) that most DSX applications will load during start-up.
Currently the SDK enables our DSX users to develop their own LCS algorithms that can be applied in Orient3D. We plan the expand the SDK in the future.
DSX SDK Software Requirements |
---|
|
Downloading the DSX SDK |
---|
|
Installing the DSX SDK |
---|
|
Use of the DSX SDK |
---|
Export directive
Algorithm class
Factory
Caveats
|
Debugging your code |
---|
|