Recent changes to PluginGuide

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Tue, 18 Sep 2012 10:01:53 -0000

--- v9
+++ v10
@@ -137,7 +137,8 @@
 ### Actual Coding ###
 
 Now open Rotator.hxx and add the following code:
-~~~~~
+
+
 	template 
 	void Rotator::execute() {
 		//initialize the image in the output slot to the same size as the input slot
@@ -149,7 +150,7 @@
 			output()[l] = input()[l].get_rotate(angle()) ;
 		}
 	}
-~~~~~
+
 
 And that's about it. Hit compile or start make to build your plugin.

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Tue, 18 Sep 2012 10:00:47 -0000

--- v8
+++ v9
@@ -50,14 +50,14 @@
 * bool connected() * member function.
 
 ** MultiSlot: ** When selected, multiple OutputSlots can be connected to this InputSlot.
-You can accesss the data using STL syntax with iterators or the [] operator. 
+You can accesss the data using STL syntax with iterators or the \[\] operator. 
 Keep in mind that there is no fixed order on the input data.
 
 Output Slots lack the Optional and MultiSlot options. charon doesn't mind if and how many Plugins are connected to an OutputSlot.
 
-For now add one Input Slot named "input" with type "CImgList" and give it a meaningfull documentation like "Input image which will be rotated". Leave Optional and MultiSlot unchecked.
+For now add one Input Slot named "input" with type *CImgList* and give it a meaningfull documentation like "Input image which will be rotated". Leave Optional and MultiSlot unchecked.
 
-Additionaly create an Output Slot named "output" with the same type.
+Additionaly create an Output Slot named *output* with the same type.
 
 ### Parameters ###
 
@@ -76,7 +76,7 @@
 
 ** Default: ** The default value which will be used when the parameter is missing from the parameter file or isn't defined in ObjectInspector
 
-** ParameterList: ** When checked the Parameter is not a single instance of *type* but instead a std::vector. Each individual value can be accessed using STL syntax (e.g. operator[]). The values are saved in parameter files as a semicolon separated list.
+** ParameterList: ** When checked the Parameter is not a single instance of *type* but instead a std::vector. Each individual value can be accessed using STL syntax (e.g. operator\[\]). The values are saved in parameter files as a semicolon separated list.
 (Keep in mind that lists of strings may not contain semicolons; escaping them is currently not supported)
 
 Add a single float-type parameter named angle. We will use degree as unit, which is an execellent piece of information to put into the documentation field.
@@ -94,7 +94,7 @@
 Note that definitions of template functions must be present in the header files so the file structure will be different depending on this option (h, hxx and cpp files with a templated plugins and only h and cpp file for non-templated plugins)
 For this tutorial we will create a templated plugin
 
-** save header and source files in separate directories: ** this option will put *.h and *.hxx files in a separated include directory to ease installation in a unix directory structure. Leave it unchecked for the time being. Keep this unchecked for the time being.
+** save header and source files in separate directories: ** this option will put \*.h and \*.hxx files in a separated include directory to ease installation in a unix directory structure. Leave it unchecked for the time being.
 
 ** generate CMake project file: ** CMakeList.txt will be created to allow the direct creation of project or makefiles. This should only be unchecked if you write your own makefiles or combine multiple plugins into the same project.
 
@@ -137,20 +137,19 @@
 ### Actual Coding ###
 
 Now open Rotator.hxx and add the following code:
-~~~
-template 
-void Rotator::execute() {
-	//initialize the image in the output slot to the same size as the input slot
-	output().assign(input().width()) ;
-	
-	//iterate over every image in the the input list
-	cimglist_for(input(),l)
-	{	
-		//assign to each image in the output list the rotated input image
-		output()[l] = input()[l].get_rotate(angle()) ;
+~~~~~
+	template 
+	void Rotator::execute() {
+		//initialize the image in the output slot to the same size as the input slot
+		output().assign(input().width()) ;
+		//iterate over every image in the the input list
+		cimglist_for(input(),l)
+		{	
+			//assign to each image in the output list the rotated input image
+			output()[l] = input()[l].get_rotate(angle()) ;
+		}
 	}
-}
-~~~
+~~~~~
 
 And that's about it. Hit compile or start make to build your plugin.

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Tue, 18 Sep 2012 09:43:10 -0000

--- v7
+++ v8
@@ -104,6 +104,8 @@
 
 ** Output Path: ** Self Explainatory
 
+---
+
 After clicking "Finish" you will find 6 files in the output directory:
 
 ** Rotator.h: ** header file which describres your new plugin class. Unless you want to add new slots or parameters to your plugin, you can leave this file alone.
@@ -123,8 +125,43 @@
 ## Project creation ##
 
 Now we can create our build enviroment:
-Open cmake-gui (or use the command line version) and point "source directory" to the place where * CMakeLists.txt * is located. We strongly recommend out-of-source builds, so
-set the build directory to some other location.
-Hit configure and select the build enviroment of your choice.
+
+Open cmake-gui (or use the command line version) and point *source directory* to the place where *CMakeLists.txt* is located. 
+We strongly recommend out-of-source builds, so set the build directory to some other location.
+
+Hit **configure** and select the build enviroment of your choice.
 You will propably get an error message that charon-core_DIR was not found. In this case, set the variable to the correct location. (When the environment variable CHARON_DIR is set cmake will find charon automatically).
 You can also change the location CMAKE_INSTALL_PREFIX points to. (In Windows will point to the Program Files directory which will typically fail unless your working with administrator rights)
+Finally, hit **generate** and start up your IDE or editor
+
+### Actual Coding ###
+
+Now open Rotator.hxx and add the following code:
+~~~
+template 
+void Rotator::execute() {
+	//initialize the image in the output slot to the same size as the input slot
+	output().assign(input().width()) ;
+	
+	//iterate over every image in the the input list
+	cimglist_for(input(),l)
+	{	
+		//assign to each image in the output list the rotated input image
+		output()[l] = input()[l].get_rotate(angle()) ;
+	}
+}
+~~~
+
+And that's about it. Hit compile or start make to build your plugin.
+
+### Rotator in Action ###
+
+Start up Tuchulcha and got to Edit->Options->Paths. Here you can add the path were your plugin was build to *debug* or *release plugin path* (Depending on the build type, which defaults to debug on most systems). Paths can be supplied as semicolon separated lists.
+Also check that the correct build type was selected in *Config*.
+
+Now click on the update plugin information button (circle arrow).
+You can check the *show debug output* box and see if your Rotator plugin appears in the list.
+
+If the plugin was loaded correctly it should appear in the *Module Collection* window.
+
+That's it. You can open a new workflow and test your new Rotator plugin. Have fun.

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Tue, 18 Sep 2012 09:05:17 -0000

--- v6
+++ v7
@@ -15,6 +15,8 @@
 
 I suppose you've either build charon yourself or downloaded one of our binary builds 
 from the homepage. If not you can do so [here](https://sourceforge.net/projects/charon-suite/files/)
+
+## Templategenerator ##
 
 Now let's start up the templategenerator which is part of the charon-suite.
 
@@ -81,16 +83,48 @@
 
 ### Final Settings ###
 
+
+ 
+
+
+
+
 ** Templated / Non-Templated: ** For templated plugins are instanciated as either float, double or int types. This is mostly usefull for plugins using CImgLists or vigra images.
 Currently most of algorithms implemented in charon use image data of the CImgList type with double precission. (double is also the default template type). float can be used when memory consumption is an issue. Non-Template should be used when you use neither CImgLists nor vigra images.
 Note that definitions of template functions must be present in the header files so the file structure will be different depending on this option (h, hxx and cpp files with a templated plugins and only h and cpp file for non-templated plugins)
+For this tutorial we will create a templated plugin
 
-** save header and source files in separate directories: ** this option will put *.h and *.hxx files in a separated include directory to ease installation in a unix directory structure. Leave it unchecked for the time being.
+** save header and source files in separate directories: ** this option will put *.h and *.hxx files in a separated include directory to ease installation in a unix directory structure. Leave it unchecked for the time being. Keep this unchecked for the time being.
 
 ** generate CMake project file: ** CMakeList.txt will be created to allow the direct creation of project or makefiles. This should only be unchecked if you write your own makefiles or combine multiple plugins into the same project.
 
-** use CImg.h: ** CImg.h is part of charon-utils and the include paths will be set correctly when this option is active. Deactivate if you don't use CimgLists or want to use another version of the header file.
+** use CImg.h: ** CImg.h is part of charon-utils and the include paths will be set correctly when this option is active. Deactivate if you don't use CimgLists or want to use another version of the header file. For now keep it active.
 
-** use vigra MultiArrays: ** same for the vigra headers
+** use vigra MultiArrays: ** same for the vigra headers. Our plugin doesn't use vigra so you can uncheck this.
 
 ** Output Path: ** Self Explainatory
+
+After clicking "Finish" you will find 6 files in the output directory:
+
+** Rotator.h: ** header file which describres your new plugin class. Unless you want to add new slots or parameters to your plugin, you can leave this file alone.
+
+** Rotator.hxx: ** The file containing the execute function, all your code goes in here.
+
+** Rotator.cpp: ** This file contains functions related to managing plugin instances and is important for the creation of the shared library (.dll or .so file).
+Usually you don't have to touch it.
+
+** CImgConfig.cmake: ** Sets some preprocessor defines and compiler flags regarding CImg.h
+It is not strictly necessary.
+
+** InitFlags.cmake: ** Sets some additional platform specific compiler flags like -Wextra on GCC or _CRT_SECURE_NO_WARNINGS on MSVC. 
+
+** CMakeLists.txt: ** CMake uses this file to create makefiles or project files for specific build environments. If you wan't to use 3rd party libraries or add new source files to the project you have to enter them in here.
+
+## Project creation ##
+
+Now we can create our build enviroment:
+Open cmake-gui (or use the command line version) and point "source directory" to the place where * CMakeLists.txt * is located. We strongly recommend out-of-source builds, so
+set the build directory to some other location.
+Hit configure and select the build enviroment of your choice.
+You will propably get an error message that charon-core_DIR was not found. In this case, set the variable to the correct location. (When the environment variable CHARON_DIR is set cmake will find charon automatically).
+You can also change the location CMAKE_INSTALL_PREFIX points to. (In Windows will point to the Program Files directory which will typically fail unless your working with administrator rights)

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Fri, 14 Sep 2012 15:38:56 -0000

--- v5
+++ v6
@@ -20,15 +20,77 @@
 
 The program will look something like this:
 
- 
-You can ignore the first page, hit "Next >"
+ 
+Nothing to enter here so once you've read the information hit "Next >"
+
+### Basic Plugin Settings ###
 
- 
+ 
 Here fill in all the necessary fields. None of them may stay empty!
 Also Module name must start with a uppercase letter and may contain no spaces.
 Try to be very verbose with your Documentation.
-For example explain which dimensions the input image must or may have (RGB?, Grayscale? multiple frames?) and do the same for the output image.
+For example explain which dimensions the input image must or may have (RGB?, Grayscale? multiple frames?) and do the same for the output image. HTML is supported and encouraged.
+
+### Input and Output Slots ###
+
+
+ 
+Here we define input and output slots for our data.
+A input slot has the following properties:
+
+** Name: ** this is the variable name by which you can access the slot data in the code. So it must be a valid C++ identifier. Also each input, output and parameter name must be unique!
+
+** Documentation: ** A documentation string for the slot. This text will show up in the tuchulcha help browser. Again html is supported. You can only proceed if something was entered here.
+
+** Type: ** A valid C++ type. You can select one from the predefined types or enter your own ones. CImgList is the image class most often used in charon.
+
+** Optional: ** When unchecked, the slot is marked as mandatory and tuchulcha will raise an error when you try to start a workflow where the slot is not connected. When you mark the slot as optional you should check if there is valid data connected to this slot using the 
+* bool connected() * member function.
+
+** MultiSlot: ** When selected, multiple OutputSlots can be connected to this InputSlot.
+You can accesss the data using STL syntax with iterators or the [] operator. 
+Keep in mind that there is no fixed order on the input data.
+
+Output Slots lack the Optional and MultiSlot options. charon doesn't mind if and how many Plugins are connected to an OutputSlot.
+
+For now add one Input Slot named "input" with type "CImgList" and give it a meaningfull documentation like "Input image which will be rotated". Leave Optional and MultiSlot unchecked.
+
+Additionaly create an Output Slot named "output" with the same type.
+
+### Parameters ###
+
+
+ 
 
 
+Parameters are similar to Input Slots. But instead of getting the values from other plugins they are read from a parameter file or defined in the ObjectInspector widget in tuchulcha.
+They have the following options:
 
+** Name: ** Same rules as for Slot apply here
 
+** Documentation: ** And also here
+
+** Type: ** You can again use one of the predefined types or enter your own. A requisition is that the type is convertible to a string as the parameter values are saved in a ascii parameter file. The special types *FileOpen*, *FileWrite* and *Path* are actually strings, but using them tells tuchulcha to show a file dialog window when you want to edit them.
+
+** Default: ** The default value which will be used when the parameter is missing from the parameter file or isn't defined in ObjectInspector
+
+** ParameterList: ** When checked the Parameter is not a single instance of *type* but instead a std::vector. Each individual value can be accessed using STL syntax (e.g. operator[]). The values are saved in parameter files as a semicolon separated list.
+(Keep in mind that lists of strings may not contain semicolons; escaping them is currently not supported)
+
+Add a single float-type parameter named angle. We will use degree as unit, which is an execellent piece of information to put into the documentation field.
+
+### Final Settings ###
+
+** Templated / Non-Templated: ** For templated plugins are instanciated as either float, double or int types. This is mostly usefull for plugins using CImgLists or vigra images.
+Currently most of algorithms implemented in charon use image data of the CImgList type with double precission. (double is also the default template type). float can be used when memory consumption is an issue. Non-Template should be used when you use neither CImgLists nor vigra images.
+Note that definitions of template functions must be present in the header files so the file structure will be different depending on this option (h, hxx and cpp files with a templated plugins and only h and cpp file for non-templated plugins)
+
+** save header and source files in separate directories: ** this option will put *.h and *.hxx files in a separated include directory to ease installation in a unix directory structure. Leave it unchecked for the time being.
+
+** generate CMake project file: ** CMakeList.txt will be created to allow the direct creation of project or makefiles. This should only be unchecked if you write your own makefiles or combine multiple plugins into the same project.
+
+** use CImg.h: ** CImg.h is part of charon-utils and the include paths will be set correctly when this option is active. Deactivate if you don't use CimgLists or want to use another version of the header file.
+
+** use vigra MultiArrays: ** same for the vigra headers
+
+** Output Path: ** Self Explainatory

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Fri, 14 Sep 2012 14:07:51 -0000

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Fri, 14 Sep 2012 14:07:20 -0000

--- v3
+++ v4
@@ -19,11 +19,11 @@
 Now let's start up the templategenerator which is part of the charon-suite.
 
 The program will look something like this:
-
- 
+
+ 
 You can ignore the first page, hit "Next >"
-
- 
+
+ 
 Here fill in all the necessary fields. None of them may stay empty!
 Also Module name must start with a uppercase letter and may contain no spaces.
 Try to be very verbose with your Documentation.

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Fri, 14 Sep 2012 13:55:31 -0000

--- v2
+++ v3
@@ -19,8 +19,8 @@
 Now let's start up the templategenerator which is part of the charon-suite.
 
 The program will look something like this:
-
- 
+
+ 
 You can ignore the first page, hit "Next >"

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Fri, 14 Sep 2012 13:46:30 -0000

--- v1
+++ v2
@@ -6,16 +6,29 @@
 
 So you have taken a interest in charon (or maybe your supervisor told you to use it :) )
 Maybe you already have some fancy code and want to wrap it in a charon plugin.
-Fear not; here you will learn how to do it.
+Don't fear! Here you will learn how to do it.
 
 Let's start with something simple.
 We'll write a plugin that takes an image and rotates it by a certain angle.
+We'll also go over several charon peculiarities and pitfalls which will be usefull
+for more complicated plugins
 
 I suppose you've either build charon yourself or downloaded one of our binary builds 
 from the homepage. If not you can do so [here](https://sourceforge.net/projects/charon-suite/files/)
 
 Now let's start up the templategenerator which is part of the charon-suite.
 
+The program will look something like this:
+
+ 
+You can ignore the first page, hit "Next >"
+
+ 
+Here fill in all the necessary fields. None of them may stay empty!
+Also Module name must start with a uppercase letter and may contain no spaces.
+Try to be very verbose with your Documentation.
+For example explain which dimensions the input image must or may have (RGB?, Grayscale? multiple frames?) and do the same for the output image.
 
 
 
+

WikiPage PluginGuide modified by Stephan Meister

Stephan Meister — Fri, 14 Sep 2012 12:46:30 -0000

WORK IN PROGRESS ================ The definite guide to building your own plugin ============================================== So you have taken a interest in charon (or maybe your supervisor told you to use it :) ) Maybe you already have some fancy code and want to wrap it in a charon plugin. Fear not; here you will learn how to do it. Let's start with something simple. We'll write a plugin that takes an image and rotates it by a certain angle. I suppose you've either build charon yourself or downloaded one of our binary builds from the homepage. If not you can do so [here](https://sourceforge.net/projects/charon-suite/files/) Now let's start up the templategenerator which is part of the charon-suite.