<!--- * [Testing your code](#testing-your-code) -->
*[Testing code](#testing-code)
*[Commit guidelines](#commit-guidelines)
*[Commit guidelines](#commit-guidelines)
*[Commit 101](#commit-101)
*[Commit 101](#commit-101)
*[Commit messages](#commit-messages)
*[Commit messages](#commit-messages)
...
@@ -15,9 +15,8 @@
...
@@ -15,9 +15,8 @@
*[Syncing repositories](#syncing-repositories)
*[Syncing repositories](#syncing-repositories)
*[Data Management](#data-management)
*[Data Management](#data-management)
*[Add Data](#add-data)
*[Add Data](#add-data)
*[Fetch Data for your examples](#fetch-data-for-your-examples)
*[Fetch Data](#fetch-data)
*[Use external data in your examples](#use-external-data-in-your-examples)
*[Data Usage](#data-usage)
*[Update your Data](#update-your-data)
*[Dashboards](#dashboards)
*[Dashboards](#dashboards)
...
@@ -45,7 +44,7 @@ git checkout -b new-feature
...
@@ -45,7 +44,7 @@ git checkout -b new-feature
git push myremote new-feature
git push myremote new-feature
```
```
7. [Create a merge request] once your branch is ready for merging, or earlier as [WIP] if this is a long merge request and need other developpers to discuss it.
7. [Create a merge request] once your branch is ready for merging, or earlier as [WIP] if this is a long merge request and need other developers to discuss it.
8. Stay available for the review process: you might need to address some issues and push new changes.
8. Stay available for the review process: you might need to address some issues and push new changes.
...
@@ -64,26 +63,21 @@ git pull origin master
...
@@ -64,26 +63,21 @@ git pull origin master
See the [Imstk Coding Guide](https://gitlab.kitware.com/iMSTK/iMSTK/-/tree/master/Docs/CodingGuide.md)
See the [Imstk Coding Guide](https://gitlab.kitware.com/iMSTK/iMSTK/-/tree/master/Docs/CodingGuide.md)
#### Code style check
#### Code style check
You should use the `uncrustify` tool to check and/or adjust code style of your files. It is run as part of git's pre-commit hook, as part of test suite invoked by CTest or by building *RUN_TESTS* target in Visual Studio. You can also run it manually by building *uncrustifyRun* target, but in that mode your files will be overwritten so make sure you commit your work beforehand to easily see the style changes automatically made by `uncrustify`.
You should use the `uncrustify` tool to check and/or adjust code style of your files.
To temporarily disable style checking as part of a commit hook, run:
* Visual Studios: Build the uncrustify target in the Innerbuild.sln.
```sh
* Linux: Run `./install/bin/uncrustify --replace --no-backup -c ../iMSTK/Utilities/Uncrustify/iMSTKUncrustify.cfg -F Innerbuild/uncrustify.list`. Ensure your uncrustify.list is up to date by running cmake.
git config uncrustify.skip true
```
\*INDENT-ON\* and \*INDENT-OFF\* keywords in comments can be used to disable uncrustify's style check for a portion of the code, this is currently used to avoid some issues uncrustify has with macros.
Then commit your changes. Then build *uncrustify* target, e.g.:
```sh
make uncrustify
```
You can view the changes by running `git diff`. If the changes are minor, add them to your previous commit, `git commit --amend`. If the changes make the style uglier (it can happen sometimes), the best solution is usually to re-write your original code to avoid the questionable style changes from having to be made. Only rarely should you use \*INDENT-ON\* and \*INDENT-OFF\* keywords in comments to disable uncrustify's style check for a portion of the code. Once everything is sorted out, enable uncrustify:
```sh
git config uncrustify.skip false
```
<!---
#### Testing Code
### Testing your code
A developer with `Developer` role in giltab may run tests on MRs submitted. Assign or ping one for review and to run tests on our machines. A developer may run:
*Coming soon - Please refer to the rest of the code in the meantime*
*`do: test`: To run an incremental build
-->
*`do: test --clean`: To run a clean build. May be useful for dependency, build, or data changes.
*`do: test --stop`: Will stop issuing build commands, does not currently stop mid build.
*`do: test --help`: For information on more commands.
Test results are repoted to our [CDash](https://open.cdash.org/index.php?project=iMSTK). Here you will find a Merge Requests section with cmake configure, build, & test sections.
## Commit guidelines
## Commit guidelines
...
@@ -137,13 +131,15 @@ Proper commit messages are important as they allow to speed up the review proces
...
@@ -137,13 +131,15 @@ Proper commit messages are important as they allow to speed up the review proces
Describe the topic in a couple words while being as specific as possible. "Improve rendering" or "Fix controllers" would be considered too broad.
Describe the topic in a couple words while being as specific as possible. "Improve rendering" or "Fix controllers" would be considered too broad.
6. Use the appropriate title prefix to help quickly understand broad context
6. Use the appropriate title prefix to help quickly understand broad context
***ENH:** For enhancement, new features, etc.
*`BUG`: Fix for runtime crash or incorrect result
***PERF:** For improved compile and runtime performance and algorithmic optimizations.
*`COMP`: Compiler error or warning fix
***BUG:** For fixing bugs of all kinds.
*`DOC`: Documentation change
***COMP:** For compilation error fix.
*`ENH`: New functionality
***TEST:** For new or improved testing.
*`REFAC`: Rework of existing functionality
***DOC:** For documentation improvements.
*`PERF`: Performance improvement
***STYLE:** For changes which do not impact the code output but rather the way the code is presented or organized.
*`TEST`: Test change
*`STYLE`: No logic impact (indentation, comments)
*`WIP`: Work In Progress not ready for merge
### Editing previous commits
### Editing previous commits
...
@@ -290,35 +286,27 @@ This process consists of rewriting the branch history, therefore re-syncing it w
...
@@ -290,35 +286,27 @@ This process consists of rewriting the branch history, therefore re-syncing it w
## Data Management
## Data Management
* ### Add Data
iMSTKs data sits in a separate repository https://gitlab.kitware.com/iMSTK/imstk-data managed with git LFS. It is downloaded by iMSTK's superbuild when either the testing or the examples is enabled.
The proper way to add data to iMSTK, is to:
- Contact a project manager to upload your data in the [Girder's iMSTK collection](https://data.kitware.com/#collection/58ab34918d777f073240dc02).
- Add the key file to `iMSTK-Source/Data` (Download the key file from girder as shown on the following picture).
> * `exampleExecutableName` is usually `${PROJECT_NAME}` in an example CMakeLists.txt.
> * `dataList` need to contain the list of data names which are needed in the example. Those names are relative to `iMSTK-Source/Data`.
3. Copy the sha of the desired commit to pull in iMSTK's `CMake/External/External_iMSTKData.cmake` file.
> * Regular expressions can be used to populate the file list using [REGEX](https://cmake.org/cmake/help/v3.8/module/ExternalData.html#referencing-associated-files).
The data will be downloaded from Girder to `iMSTK-build/Innerbuild/ExternalData/Data`: the `Objects` directory is the datastore, and the `Data` directory holds symbolic links to that data with expected file names.
4. Clean build or rebuild the iMSTKData target.
* ### Use external data in your examples
### Fetch Data:
A clean build will always acquire the latest changes. If incrementally building, go up to the superbuild and rebuild the iMSTKData target.
### Data Usage:
The path to the data directory is defined by iMSTK_DATA_ROOT which can be used in your C++ code as shown below :
The path to the data directory is defined by iMSTK_DATA_ROOT which can be used in your C++ code as shown below :
- Contact the project manager to update your data in the [Girder iMSTK collection](https://data.kitware.com/#collection/58ab34918d777f073240dc02).
- Update the key file to `iMSTK-Source/Data` as described in the [Add Data section](#add-data).
## Dashboards
## Dashboards
Dashboards - powered by [CDash] - helps visualizing the latest state of iMSTK builds on Windows, MacOSx, and Linux, to avoid introducing regressions when offering changes to the toolkit:
Dashboards - powered by [CDash] - helps visualizing the latest state of iMSTK builds on Windows, MacOSx, and Linux, to avoid introducing regressions when offering changes to the toolkit:
After updating your fork you can proceed with the beginning of this guide on how to pull a different source.
After updating your fork you can proceed with the beginning of this guide on how to pull a different source.
\ No newline at end of file
# Adding data to the data repository
iMSTKs data sits in a separate repository https://gitlab.kitware.com/iMSTK/imstk-data. It is downloaded by iMSTK's superbuild when either the testing or the examples is enabled. To add new data to the repository two steps are necessary
**1. Add Data to repository**
The repository is already checked out as an external dependency in your build directory (if using superbuild) as `<build_dir>\External\iMSTKData\src\Data`, data can be added to the folder here and directly commited and pushed.
**2. Update SHA in `ExternalData.cmake`**
The file that controls the downloading of the data is `CMake/External/External_iMSTKData.cmake`. After commiting and pushing a change in the `iMSTKData` repository, the SHA to checkout needs to be updated to the SHA matching the latest commit.
*[Getting the source code](#1-getting-the-source-code)
*[Getting the source code](#1-getting-the-source-code)
*[Setting up your SSH key](#2-setting-up-your-ssh-key)
*[Setting up your SSH key](#2-setting-up-your-ssh-key)
*[Building iMSTK](#3-building-imstk)
*[Building iMSTK](#3-building-imstk)
*[On Linux/macOS](#on-linuxmacos)
*[On Windows](#on-windows)
*[Phantom Omni Support](#phantom-omni-support)
*[VRPN Support](#vrpn-support)
*[Offscreen Rendering](#offscreen-rendering)
*[Renderless](#renderless)
## About
## About
### Overview
### Overview
...
@@ -32,7 +38,7 @@ iMSTK is licensed under [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.
...
@@ -32,7 +38,7 @@ iMSTK is licensed under [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.
## Resources
## Resources
### Documentation
### Documentation
Click [here](https://imstk.readthedocs.io/en/latest/) for detailed documentation.
Click [here](https://imstk.readthedocs.io/en/latest/) for user documentation.
Click [here](https://imstk.gitlab.io/) for doxygen code documentation.
Click [here](https://imstk.gitlab.io/) for doxygen code documentation.
...
@@ -74,59 +80,65 @@ The build process will check out external dependency sources with the SSH protoc
...
@@ -74,59 +80,65 @@ The build process will check out external dependency sources with the SSH protoc
### 3. Building iMSTK
### 3. Building iMSTK
We use [CMake] to configure the project on every platform. See how to run it [HERE](https://cmake.org/runningcmake/).
We use [CMake] to configure the project on every platform. See how to run it [HERE](https://cmake.org/runningcmake/).
* ##### On Linux/macOS
Type the following commands from the same location you cloned the code. This will configure the build in a directory adjacent to the source directory. To easily change some configuration variables like `CMAKE_BUILD_TYPE`, use `ccmake` instead of `cmake`.
```sh
mkdir iMSTK-build
cd iMSTK-build
cmake ../iMSTK #/path/to/source/directory
make -j4#to build using 4 cores
```
You can also use [Ninja] for a faster build instead of Unix Makefiles. To do so, configure the cmake project with `-GNinja`:
```
cmake -GNinja ../iMSTK
ninja
```
This will checkout, build and link all iMSTK dependencies. When making changes to iMSTK [base source code](/Base), you can then build from the `Innerbuild` directory.
* ##### On Windows
Run CMake-GUI and follow the directions described [HERE](https://cmake.org/runningcmake/). You will have to choose which version of Visual Studio you'd like to use when configuring the project, make sure to select **Microsoft Visual Studio C++ 15 2017 or 2019**. CMake will generate a `iMSTK.sln` solution file for Visual Studio at the top level. Open this file and build all targets, which will checkout, build and link all iMSTK dependencies. When making changes to iMSTK [base source code](/Base), you can then build from the `iMSTK.sln` solution file located in the `Innerbuild` directory.
If you would like to build on multiple cores add /MP[N] to CMAKE_CXX_FLAGS in CMake-GUI, where N is optional representing the number of cores (without N supplied, the build will use as many cores as available on the device).
If you check out the unit tests or the examples make sure to run `git install lfs` to make sure that `git lfs` is installed.
* ##### Phantom Omni Support
To support the [Geomagic Touch (formerly Sensable Phantom Omni)](http://www.geomagic.com/en/products/phantom-omni/overview) haptic device, follow the steps below:
1. Install the [OpenHaptics] SDK as well as the device drivers:
- for [Windows](https://3dsystems.teamplatform.com/pages/102774?t=r4nk8zvqwa91)
- for [Linux](https://3dsystems.teamplatform.com/pages/102863?t=fptvcy2zbkcc)
2. Reboot your system.
3. Configure your CMake project with the variable `iMSTK_USE_OpenHaptics` set to `ON`.
4. After configuration, the CMake variable `OPENHAPTICS_ROOT_DIR` should be set to the OpenHaptics path on your system.
* ##### VRPN Support
The `VRPNDeviceModule` enables access to a large number devices supported by VRPN. The `VRPNDeviceModule` expects a `vrpn_server` to be running. The iMSTK superbuild builds and
installs a server with some default settings but if you want to configure a specific server
it might be easier to separately build a server. The file `CMake\External\External_VRPN.cmake`
shows how to pass configuration into VRPN in case you want to modify the modules enabled and
disabled by the build
The `vrpn.cfg` that is installed by default doesn't have any devices enabled, before use you
* #### On Linux/macOS
will need to uncomment the devices that you would like to use. If you use the one inside the
Type the following commands from the same location you cloned the code. This will configure the build in a directory adjacent to the source directory. To easily change some configuration variables like `CMAKE_BUILD_TYPE`, use `ccmake` instead of `cmake`.
iMSTK install directory please note that it will be overwritten every time the superbuild is
```sh
run.
mkdir iMSTK-build
cd iMSTK-build
Currently iMSTK supports VRPN `Analog`, `Button` and `Tracker` devices. Future support will
cmake ../iMSTK #/path/to/source/directory
depend on user demand.
make -j4#to build using 4 cores
```
* ##### Offscreen Rendering
You can also use [Ninja] for a faster build instead of Unix Makefiles. To do so, configure the cmake project with `-GNinja`:
To render without the usage of a GPU or without the usage of a screen on linux (or WSL), iMSTK's VTK renderer may be built with OSMesa.
This will checkout, build and link all iMSTK dependencies. When making changes to iMSTK [base source code](/Base), you can then build from the `Innerbuild` directory.
2. Set `iMSTK_USE_VTK_OSMESA` to `ON`
3. Proceed to build iMSTK
* #### On Windows
Run CMake-GUI and follow the directions described [HERE](https://cmake.org/runningcmake/). You will have to choose which version of Visual Studio you'd like to use when configuring the project, make sure to select **Microsoft Visual Studio C++ 15 2017 or 2019**. CMake will generate a `iMSTK.sln` solution file for Visual Studio at the top level. Open this file and build all targets, which will checkout, build and link all iMSTK dependencies. When making changes to iMSTK [base source code](/Base), you can then build from the `iMSTK.sln` solution file located in the `Innerbuild` directory.
If you would like to build on multiple cores add /MP[N] to CMAKE_CXX_FLAGS in CMake-GUI, where N is optional representing the number of cores (without N supplied, the build will use as many cores as available on the device).
If you check out the unit tests or the examples make sure to run `git install lfs` to make sure that `git lfs` is installed.
* #### Phantom Omni Support
To support the [Geomagic Touch (formerly Sensable Phantom Omni)](http://www.geomagic.com/en/products/phantom-omni/overview) haptic device, follow the steps below:
1. Install the [OpenHaptics] SDK as well as the device drivers:
- for [Windows](https://3dsystems.teamplatform.com/pages/102774?t=r4nk8zvqwa91)
- for [Linux](https://3dsystems.teamplatform.com/pages/102863?t=fptvcy2zbkcc)
2. Reboot your system.
3. Configure your CMake project with the variable `iMSTK_USE_OpenHaptics` set to `ON`.
4. After configuration, the CMake variable `OPENHAPTICS_ROOT_DIR` should be set to the OpenHaptics path on your system.
* #### VRPN Support
The `VRPNDeviceModule` enables access to a large number devices supported by VRPN. The `VRPNDeviceModule` expects a `vrpn_server` to be running. The iMSTK superbuild builds and
installs a server with some default settings but if you want to configure a specific server
it might be easier to separately build a server. The file `CMake\External\External_VRPN.cmake`
shows how to pass configuration into VRPN in case you want to modify the modules enabled and
disabled by the build
The `vrpn.cfg` that is installed by default doesn't have any devices enabled, before use you
will need to uncomment the devices that you would like to use. If you use the one inside the
iMSTK install directory please note that it will be overwritten every time the superbuild is
run.
Currently iMSTK supports VRPN `Analog`, `Button` and `Tracker` devices. Future support will
depend on user demand.
* #### Offscreen Rendering
To render without the usage of a GPU or without the usage of a screen on linux (or WSL), iMSTK's VTK renderer may be built with OSMesa.
