Tools

Along with the framework itself, the normal distributions of f.r.e.e. contains several tools. These tools allow the utilization of different features of f.r.e.e as well as realize features by using the f.r.e.e. framework. The source code of these tools can be found in the application sub directory. In the following the tools will be briefly introduced.

freeAdapt

This tool can be used to generate adapted setups by utilizing a given generic setup as template and an adaptation element or list. FreeAdapt will generate one adapted setup for each adaptation element. These adapted setups will be saved in a specified project path. The pattern for the filename creation of adapted setups can be specified by the user.

Usage

freeAdapt <setup-file> <adaptation-list> [options]

Command line options:

• -ad
  Set this flag to use the description of an adaptation element as adaptation suffix of the generated adapted setup files. If not set, the suffix will be the index of the adaptation element.
• -an <name>
  Defines the template of file names of the generated adapted setups. If not specified it will be the name of the generic setup.
• -g
  Start freeAdapt in GUI-mode. FreeAdapt will always start in GUI-mode, if no flag has been specified. Remark: This option is not available if freeAdapt is built without GUI (see version information).
• -pp <path>
  Defines the project path (place where to save all adapted setups). If flag is not present, the path is used where freeCL is executed.
• -v
  Shows version of freeAdapt.
• -?
  Shows this help.

Example:
freeAdapt generic.fre cases.ial -an adaptedSetup
Executing freeAdapt will adapt the generic setup stored in "generic.fre" with each adaptation in "cases.ial" and store the adapted setups in the current working directory. The file names will be "adaptedSetup_1.fre", "adaptedSetup_2.fre" and so on.

Adapted setup name pattern

The file name of adapted setups will be generated using following pattern:
<setup-name>_<adaptation-suffix>
<Setup-name> is the name of the generic setup (not the file name!) or can be specified by the command line option -an. <Adaptation-suffix> is by default the index of the adaptation in the adaptation list. Using the command line option -ad, freeAdapt will use the description tag of each adaptation instead. See above for an example.

freeCL

This is one of the central tools in the tool set. FreeCL is the command line processor of f.r.e.e.. It allows the goal driven processing of setup files. Therefore the user can specify the result media of the setup that should be generated. Via backward chaining the data for the chosen result media will be gathered and processed. By default all result media will be generated. The whole setup processing can be logged and stored for further analysis.

Media drain

Because freeCL processes setups goal driven, the setups need to specify all result media that they offer. This is done via a media drain component added to the setup and linked to all offered result media. The media drain must always have the id MediaFinal. FreeCL searches by default for this media drain and computes all linked media. By use of the -sm flag the media that should be computed can be selected explicitly.

Usage

freeCL <free-setup-file> [options]

Command line options:

• -a <file>
  Defines an adaptation list that should be used as data basis. If an adaptation list is defined, the setup will be adapted to each list element and then processed. The project name for each adaptation will be <project_name>_<adaptation_info>. Project_name is the name of the project (see -pn) and adaptation_info is the index of the adaptation or its adaptation description if -ad is set.
• -ad
  Set this flag to use the description of an adaptation element as adaptation info. Otherwise the index of the adaptation will be used. This flag is only relevant if -a is set.
• -d
  The logfile of freeCL stores also the information of the detailed registration process (every iteration step).
• -fp
  Forces freeCL to create the project path, if it doesn't exists.
• -g
  Start freeCL in GUI-mode. FreeCL will always start in GUI-mode, if no flag has been specified. Remark: This option is not available if freeCL is built without GUI (see version information).
• -pn <name>
  Defines the name of the project. If flag is not present the name is given by the setup file (name of the setup).
• -pp <path>
  Defines the project path (place where to save all results) if not defined otherwise. If flag is not present, the path is used where freeCL is executed.
• -s
  FreeCL creates a statistic of the registration process and saves it in the project path.
• -sl
  FreeCL uses the saving locations specified by the MediaDrain. Otherwise the storing location will be the project path and the filenames will be created by combining project name and media id.
• -sm <media>
  By default freeCL saves all media that are linked to the MediaDrain '/MediaFinal'. Using that flag you can specify which media should be generated and stored. If this flag is used, only media specified by using this flag will be generated and saved. The flag can be used multiple times, one for each medium that should be stored.
• -ss <path>
  Redefines the suffix for the statistic file. The default suffix is _stats.txt. The suffix includes the file extension of the file.
• -v
  Shows version of freeCL.
• -x <file>
  Defines an xml style sheet that will be linked to the saved statistic.
• -?
  Shows this help.

Example:

• freeCL reg.fre -pp ./result -pn demo
  This will execute freeCL using reg.fre. The project will be named demo, the project path is ./result and all final media will be generated and saved.
  
• freeCL reg2.fre -sm image -sm field
  This will execute freeCL using reg2.fre. The project will only generate and save the final media "image" and "field". The storage location will be the current working directory.

freeDiag

This tool is used to get information about the controllers available on the system. You can list all controllers or search for controllers and the location of their associated dynamic linked library. The tools also allows the view the basic profile of a controller with its parameters, media io and sub components.

Usage

freeDiag [<ControllerID>] [options]

Command line options:

• -ex <File>
  Export the profile of the specified controller as xml. The profile will be saved as the specified file. This option will not work when -l is set.
• -m <MediaIDe>
  Will output the information of the specified media component. Requires an unambiguous ControllerID.
• -p <Parameter name>
  Will output the information of the specified parameter.Requires an unambiguous ControllerID.
• -l
  Search for any controller that matches the given controller ID and print out the location. Using this flag ControllerID may be only a part of the ID.
• -s
  Show profile of a controller in a brief version.
• -v
  Shows version of freeEval.
• -?
  Shows this help.

Example:
freeDiag Media -l
This will produce a list of all controllers which have a controller id that matches or contain the search string "Media" (e.g. "Media Container", "Media Drain" or "Intensity 2D Image Media"). The list contains the location of the DLL and the status of the controller.

freeDiag "Binary Threshold 2D Image Filter"
This will show the profile of the controller "Binary Threshold 2D Image Filter".

freeEval

This tool is used to evaluate a setup file by using an adaptation list serving as test case set and a setup defining the metric that should measure the quality. Results of the evaluation will be stored in an evaluation statistic file. The structure depends like the measure on the chosen metric. The evaluation metric can arbitrarily be defined via a setup (further information see paragraph "Evaluation metric").

Evaluation metric

The metric used for the evaluation is defined in an extra setup file (metric setup). Every metric can be used, as long as the metric is derived from SetupOptimizationMetric (controller id: SetupOptimizationMetricBase). The component id of the evaluation metric in the setup has to be "EvaluationMetric". If these requirements are met, the setup/metric can be used to evaluate the target setup.

Usage

freeEval <metric-setup-file> <target-setup-file> <adaptation-list> [options]

Command line options:

• -g
  Start freeEval in GUI-mode. FreeEval will always start in GUI-mode if no flag has been specified. Remark: This option is not available if freeEval is built without GUI (see version information).
• -pn <name>
  Defines the name of the project. If flag is not present the name is given by the setup file (name of the setup) with suffix "_eval".
• -pp <path>
  Defines the project path (place where to save all results) if not defined otherwise. If flag is not present, the path is used where freeEval is executed.
• -v
  Shows version of freeEval.
• -x <file>
  Defines an xml style sheet that will be linked to the saved statistic.
• -?
  Shows this help.

Example:
freeEval metric.fre reg.fre cases.ial -pp ./result -pn demo
Executing freeEval with these parameters will evaluate reg.fre with the adaptation list cases.ial by using the evaluation metric defined in metric.fre. The result file will be demo.txt.

freeSO

This tool is used to optimize a target setup file by a user defined optimizing strategy. The optimizing strategy is defined by an optimization setup that defines all components that will be used for the optimization of the target setup. The optimization setup normally also defines the target setup and an adaptation list that is used as training set for the optimization.
Optimization progress and results of the setup optimization evaluation will be stored in a statistic file. The structure of the file depends on the chosen optimzation strategy and the used evaluation metric (further information see paragraph "Setup Optimization").

Setup Optimization

Every setup optimization is driven by a setup optimization processor. Therefor an optimization setup must contain such a processor as a component with ID "Setup Optimization". For more information about setup optimization itself see feature description. A setup optimization process always has a metric (derived from SetupOptimizationMetric) to evaluate the quality of a setup, an optimizer (derived from SetupOptimizationOptimizer) and a setup transform (based on SetupTransform). Usually the target setup and the adaptation list are set as parameters in the optimization setup, but it is also possible to define both via command line options.

Usage

freeSO <optimization-setup-file> [options]

Command line options:

• -a <file>
  Defines an adaptation list that should be used as data basis. Overwrites the setting of the adaptation list in the optimization setup.
• -g
  Starts freeSO in GUI-mode. FreeSO will always start in GUI-mode, if no flag has been specified. Remark: This option is not available if freeEval is built without GUI (see version information).
• -if
  Ignores failed evaluations. If this flag is set, failed evaluations will not be logged in freeSO.log.
• -pn <name>
  Defines the Name of the project. If flag is not present, the name is given by the setup file (name of the setup).
• -pp <path>
  Defines the project path (place where to save all results) if not defined otherwise. If flag is not present, the path is used where freeSO is executed.
• -s <file>
  Defines the target setup that should be optimized. Overwrites the setting of the target setup in the optimization setup.
• -v
  Shows version of freeSO.
• -x <file>
  Defines an xml style sheet that will be linked to the saved statistic.
• -?
  Shows this help.

Example:
freeSO SetOp.fre -pn demo -s target.fre
Executing freeSO with these parameters will optimize target.fre with the adaptation list and optimization strategy defined in SetOp.fre. The result file will be demo_stat.xml.

---