Installation and Conventions


  1. GPU and GPU drivers supporting OpenGL 3.3 minimum but better 4.6
  2. windows or linux (manual was tested on ubuntu 20.4)
  3. install git
  4. install cmake (on Windows internal build system can be used instead of cmake)
  5. install compiler (gcc,clang,visual studio)
  6. on linux install libXi-devel by, for example with
    sudo apt-get install libxi-dev
  7. open shell/command prompt in parent of source directory (avoid paths with spaces such as windows desktop, home or library paths)
  8. clone current version with git
    git clone

Using CMake

  1. switch to develop branch
    git checkout develop
  2. set environment variable CGV_DIR to cgv directory created by git
    • windows:
      reg ADD HKEY_CURRENT_USER\Environment /v CGV_DIR /t REG_SZ /d source_parent_dir\cgv
    • ubuntu: append
      export CGV_DIR=source_parent_dir/cgv
      to ~/.bashrc and restart shell
  3. use cmake or cmake-gui as usual with your favorite generator (choosing a build directory serving also as cmake cache)
    • for debug support on linux set CMAKE_BUILD_TYPE=Debug.
    • during development enable shared libraries with BUILD_SHARED_LIBS=True
    • when using Visual Studio ensure choose configuration after starting
    • on windows building and starting without specific choice of generator could look like this
      mkdir build
      cd build
      cmake .. -DBUILD_SHARED_LIBS=True
      cmake --build . --target examples --config Debug
      bin\Debug\cgv_viewer.exe plugin:cg_fltk plugin:cg_ext plugin:cg_icons plugin:crg_stereo_view plugin:crg_antialias plugin:crg_depth_of_field plugin:crg_light plugin:cg_meta plugin:cmi_io plugin:cmv_avi plugin:crg_grid plugin:co_web plugin:cmf_tt_gl_font plugin:examples
    • on linux building and starting without specific choice of generator could look like this
      mkdir build
      cd build
      cmake --build . --target examples -j8
      bin/cgv_viewer plugin:cg_fltk plugin:cg_ext plugin:cg_icons plugin:crg_stereo_view plugin:crg_antialias plugin:crg_depth_of_field plugin:crg_light plugin:cg_meta plugin:cmi_io plugin:crg_grid plugin:cmf_tt_gl_font plugin:examples
    • to debug in IDE add launch target with cgv_viewer as program and command line arguments as in examples above

Using Internal Build System (Windows only)

For a fast start under windows with visual studio do the following:

  • Choose directory into which to clone the cgv source tree and run the following commands:
  • create a build directory where the temporary files should be stored
  • in case you want to use the x64 platform start the define_platform.bat script and follow instructions
  • in case you do not want to use the most current visual studio toolset start the define_windows_sdk.bat script and follow instructions
  • use 2 explorer windows to drag build directory onto cgv/define_system_variables.bat alternatively you can run the following command in the command prompt:
    define_system_variables.bat <global-path-to-build-directory>
  • select your configuration, typically [i] for MS VS 2019
  • close the command prompt and optionally open a new to ensure that the systems variables have been updated
  • bind the extension .pj to cgv/bin/generate_makefile.bat by right clicking cgv/plugins/examples/examples.pj and finding cgv/bin/generate_makefile.bat as the default application for .pj files. This generates the solution of the examples plugin.
  • alternatively you can run cgv/build_example_solution.bat or drag and drop cgv/plugins/examples/examples.pj onto cgv/bin/generate_makefile.bat
  • after visual studio started, select configuration "Debug Dll" or "Release Dll"
  • ensure that examples plugin is the active project
  • build solution
  • run examples project and select example from menu (try bump mapper, which can also be created by <Ctrl-B>)
  • press <F1> to blend in help on shortcuts and mouse control of the view
  • try out to mouse control of the view by rotating the view, translating it and zooming in and out
  • try out the shortcuts
  • click through the user interface

System Configuration

In order to be able to work with the cgv framework, the following environment variables need to be set

  • obligatory: CGV_DIR ... path of cgv framework
  • CGV_INSTALL ... path, where compiled libraries and applications are installed. If not defined the Windows build rules for resource files and shaders won't find the corresponding tools and therefore fail. If these are not needed, CGV_INSTALL defaults to CGV_DIR. Executables and shared libraries / dlls are copied to "$(CGV_INSTALL)/bin" and libraries to "$(CGV_INSTALL)/lib"
  • optional: PATH ... the directories "$(CGV_INSTALL)/bin" and "$(CGV_DIR)/bin" should be added to the path variable
  • optional: CGV_BUILD ... path, where the intermediate files are created. For example "c:/temp/build_cgv". If not set,CGV_BUILD defaults to CGV_DIR/build.
  • optional: CGV_PLATFORM ... can be WIN32 or x64 and can be defined with define_platform.bat script (defaults to WIN32)
  • optional: CGV_WINDOWS_SDK ... since VS 2017; can be one of the installed toolsets of visual studio and can be defined with define_windows_sdk.bat (defaults to most current toolset version of selected visual studio version)
  • optional: CGV_CHARSET ... only for Visual Studio; can be MultiByte (char is 8 bit) or Unicode (char is 16 bit) and defaults to MultiByte. Use define_charset.bat to change the value.
  • optional: CGV_OPTIONS ... semicolon separated further options, where currently only NO_OPENVR is supported to avoid initialization of steam vr. Use define_options.bat to change the value.
  • optional: CGV_DATA ... the root paths for datasets which are used in the cgv_data to find files.

Under windows the following six scripts - located in the root directory of the cgv framework - help to manage the necessary environment variables. Just double click them to execute them:

  • show_system_variables.bat ... shows the current settings
  • define_system_variables.bat ... can be started without or with one parameter. It allows to set all necessary environment variables interactively or automatically. One has to answer at least the first question for the used compiler. The CGV_DIR is derived from the location of the script file. CGV_BUILD is set to the parameter passed to the script or without parameter it is set to CGV_DIR/build. To specify the build path as parameter, you can drag the build path with the mouse onto the script. If the build path is set through the command line parameter, CGV_INSTALL is set to CGV_BUILD, otherwise to CGV_DIR. The variable CGV_COMPILER (see section on Makefile generation) is set from the user interaction. Finally, the user specific path extension is augmented by "$(CGV_DIR)/bin" and "$(CGV_INSTALL)/bin".
  • define_project_dir.bat ... sets the system variable CGV_PROJECT_DIR. The script is started with one parameter - the path to the cgv project directory. The parameter can be defined by dragging the project directory in the windows explorer onto the batch script.
  • define_support_dir.bat ... sets the system variable CGV_SUPPORT_DIR. The script is started with one parameter - the path to the cgv support directory. The parameter can be defined by dragging the support directory in the windows explorer onto the batch script.
  • define_data_dir.bat ... sets the system variable CGV_DATA. The script is started with one parameter - the path to the cgv data directory. The parameter can be defined by dragging the data directory in the windows explorer onto the batch script.
  • undefine_system_variables.bat ... removes all cgv specific settings from the system variables.
  • build_example_solution.bat ... after definition of the system variables invoke this script to start the makefile generation process on the examples solution.

Third Party Libraries

The framework uses the following platform independent third party libraries with completely free licenses

  • zlib
  • libjpeg
  • libpng
  • libtiff
  • fltk
  • ann (used in point_cloud lib to build knn graph)
  • glew
  • webserver (no real dependency, pretty unknown little lib)

glew is included on both plattforms. When using the cgv framework, the GL/glew.h header need not be included directly. Normally, one includes the header cgv/render/gl/gl.h, which includes the glew header. If the GL/wglew.h header is needed too, include cgv/render/gl/wgl.h instead. For all other libraries except ann, one typically installs them independent of the cgv framework.

The following third party libraries are used and are typically preinstalled on most platforms

  • opengl
  • glu

Internal Makefiles (Windows only)

The cgv framework comes with a generator for visual studio solutions. It is based on cgv specific project files with the extension ".pj". All project files are located in the source directories. Currently, the following target platforms are supported

  • Visual Studio 2005 (vs8)
  • Visual Studio 2008 (vs9)
  • Visual Studio 2008 Express (vs9e)
  • Visual Studio 2010 (vs10)
  • Visual Studio 2012 (vs11)
  • Visual Studio 2013 (vs12)
  • Visual Studio 2015 (vs14)
  • Visual Studio 2017 (vs141)
  • Visual Studio 2019 (vs142)

vs8, vs9, vs9e, vs10, vs12, vs14, vs141, and vs142 are the shortcuts for the target compiler / development environment. The environment variable CGV_COMPILER is to be set to this shortcut (with the script define_system_variables.bat)

Hint: A template project file is located at CGV_DIR/make/ppp/templates/pj.ppp. It documents all possible entries to a project file. To write a new project file, one typically copies this template, renames it to something like "my_project.pj" and edits it with a favorite text editor. The current version of this file is inserted to the end of this page

After a project file has been created, one can simply transform it to the target platform by passing the file as command line argument to the batch-script "generate_makefile.bat" located in CGV_DIR/bin. This script only runs if the system variable CGV_COMPILER is set.

Hint: It is very convenient to bind the "generate_makefile.bat" script as default program to the extension "*.pj". This can be done by double clicking a pj-file and selecting "generate_makefile.bat" as default program.

Hint: In the cgv root directory there is a windows script "build_example_solution.bat" that can be double clicked after the system variables have been set correctly with the script define_system_variables.bat. It calls "generate_makefile.bat" with the examples plugin pj-File as argument. This allows you to get started very easily.

Careful! Since Visual Studio 2008 ppp also generates "*.user" files, which define the to be executed application and the command line arguments when starting the application from Visual Studio. If a project is opened in Visual Studio while ppp is used to generate project, solution and user files, Visual Studio only reloads the solution and the project files but not the user file. Therefore the command line arguments are not updated and newly added plugins won't be read when starting the application from Visual Studio. Thus take care to close or unload the main project in Visual Studio before rebuilding changed user files.

The current version of the template for project files is


// previous line ensures that one can use the direct mode of ppp
// on entering this file, the following variables are predefined:
// - SYSTEM ... one of "windows" or "linux"
// - INPUT_DIR ... directory containing the currently processed project file
// - INPUT_PATH ... full path to the currently processed project file
// - INPUT_FILE ... name of the project file with extension
// - CGV_DIR ... from the obligatory environment variable CGV_DIR
// - CGV_INSTALL ... from environment variable CGV_INSTALL or if not defined
// defaults to CGV_DIR
// - CGV_BUILD ... from environment variable CGV_BUILD or if not defined
// defaults CGV_DIR/build
// - CGV_BUILD_DIR ... CGV_BUILD extended by compiler / ide specific sub directory
// - CGV_SUPPORT_DIR ... from environment variable CGV_SUPPORT_DIR or undefined if
// environment variable not defined
// - CGV_CHARSET ... from environment variable CGV_CHARSET or Unicode if
// environment variable is not defined. Use define_charset.bat to set environment variable
// - CGV_DATA ... from environment variable CGV_DATA or undefined if
// environment variable not defined
// - CGV_COMPILER ... from environment variable CGV_COMPILER or if not defined
// the defaults are "vs9" for "windows" and "gcc" for "linux"
// - CGV_COMPILER_VERSION ... 8, 9, 10, 12, 14 for the visual studio compilers
// "vs8", "vs9", "vs10", "vs12", "vs14"
// - CGV_IDE ... from environment variable CGV_IDE or from command line
// argument to ppp. Defaults to "visual studio" for vs compilers.
// For gcc also "eclipse" is allowed.
// there is only one obligatory define:
// the globally unique identifier of project
projectGUID = "E4E3902D-4700-4EE9-A64E-6BD4DD762E4D";
// optional project definition
//projectType can take the values
// - "library" ... library that can be compiled to static and shared version
// - "static_library" ... library that can be compiled only in static version
// - "shared_library" ... library that can be compiled only in shared version
// - "plugin" ... same as library but used as plugin to an application
// - "application" ... executable that can take arguments of the form "plugin:my_plugin"
// - "application_plugin" ... has the same configurations as a plugin plus two additional
// configurations called "Release Exe" and "Debug Exe" that generate an
// executable with all plugins statically linked in. The solution of an
// application_plugin uses the new configurations by default in the static
// solution configurations "Release" and "Debug". When an application_plugin
// is a dependent plugin of another application_plugin, the other solution uses
// the "Release" and "Debug" configurations of the application_plugin to link
// it into the other executable.
// - "tool" ... executable used during the build process like ppp
// - "test" ... plugin to the tester tool that provides boolean functions to test code
//if not specified, the projectType defaults to "plugin"
projectType = "library";
//name of project defaults to INPUT_NAME without extension
projectName = "my_project";
//list of individual source files that must be specified with full path
sourceFiles = [INPUT_DIR."my_source.cxx", INPUT_DIR."my_resource.png"];
//Specify a list of files that should be excluded from the project.
//The files must be specified by the same path as in the sourceDirs.
//If you specify INPUT_PATH, the "*.pj"-file is excluded from the project.
//If a file is listed in sourceFiles AND excludeSourceFiles it is INCLUDED.
excludeSourceFiles = [INPUT_PATH];
//list of directories that are scanned recursively for source files,
//defaults to empty list [] if sourceFiles are defined or to [INPUT_DIR] if
//sourceFiles is not defined
sourceDirs = [INPUT_DIR."/my_subdir"];
//specify subdirs in the source directories that should be excluded
excludeSourceDirs = [];
// define additional directories, in which project files are located.
// By default the directories CGV_DIR/cgv, CGV_DIR/apps and CGV_DIR/tool
// are project directories.
addProjectDirs = [
//Define projects on which this project depends. All projects that are
//handled by the cgv-framework need to be added as addProjectDeps and
//not as addDependencies even if the resulting libraries are installed
//on the system. Please add the following libraries which are installed
//under linux to addProjectDeps:
//- zlib
//- libjpeg
//- libpng
//- libtiff
//- fltk
//- glew
//ppp will automatically classify them as dependencies under linux and
//as dependent projects under windows.
//If a plugin depends on an application, this application
//is used as executable for running and debugging the plugin.
//A "test" project is always dependent on the "tester" tool.
//Default dependencies are the tools used during the build process.
//The tool projects specified in the rules are added to the solution
addProjectDeps = ["cgv","cgv_viewer","fltk"];
// By default all projects on which this project depends are included to the workspace (solution).
// By setting "referenceDeps" to 0, only the workspace only contains this project. This feature is
// currently only supported for Visual Studio 2010 and works only in the shared version of application
// plugins as all registration code of statically compiled plugins is discarded when the plugin is not
// included in the solution.
referenceDeps = 0;
// add additional command line arguments. The most common usage of this
// is to add a default config file as in the given example
addCommandLineArguments = ['config:"'.INPUT_DIR.'/my_config.def"'];
// working directory in which the resulting program should be started
// this defaults to the platform specific default directories
workingDirectory = INPUT_DIR;
//additional include paths, which are appended to the default paths
//that include CGV_DIR and the list of paths defined in the INCLUDE
//environment variable that are automatically recognized by the compiler.
//To export include paths to projects that depend on this project, specify
//the include path in a list of two strings with the second entry equal to "all"
addIncDirs = [ INPUT_DIR."/my_include_subdir",
[ env::CGV_SUPPORT_DIR."/libs/capture", "all"]
//additional preprocessor definitions for all configurations. By default the
//following symbols are defined:
// - INPUT_DIR ... is defined to the input directory of the project
// - CGV_DIR ... is defined to the cgv directory active during compilation
//Both predefined paths come without enclosing double quotes. You can use the
//macro QUOTE_SYMBOL_VALUE defined in <cgv/defines/quote.h> to enclose the directories
//in double quotes.
//To export defines to projects that depend on this project, specify
//the define in a list of two strings with the second entry equal to "all"
addDefines = ["LOCAL_DEFINE", ["EXPORTED_DEFINE", "all"] ];
//additional preprocessor definitions for shared configurations
//To export shared defines to projects that depend on this project, specify
//the shared define in a list of two strings with the second entry equal to "all"
addSharedDefines = ["CGV_FORCE_EXPORT", ["FL_SHARED", "all"] ];
//additional preprocessor definitions for static configurations
//To export static defines to projects that depend on this project, specify
//the static define in a list of two strings with the second entry equal to "all"
addStaticDefines = [];
//additional library paths. The default library paths include
//CGV_DIR/lib and the path list defined in the environment
//variable LIBRARIES that is automatically recognized by the
//To export lib dirs to projects that depend on this project, specify
//the lib dir in a list of two strings with the second entry equal to "all"
addLibDirs=["regular_lib_dir", ["exported_lib_dir", "all"] ];
//define a dependency by specification of a configuration specific library name either
//for current project only or to be exported to all dependent projects
addMapDeps = [
[ "testlib2", ["testlib1_s10","testlib1_sd10","testlib1_10","testlib1_d10"] ],
[ ["testlib1", ["testlib1_s10","testlib1_sd10","testlib1_10","testlib1_d10"] ], "all" ]
//external libraries on which the project depends. If one project
//depends on another, it is sufficient to add the project to the
//addProjectDeps list without entry in addDendencies. As library names
//are platform dependent, the platform and configuration specific
//library names of the following libraries are tabulated and translated
//from the given name correctly:
// - "opengl"
// - "glu"
// - "glew"
//In order to extend the translation mapping use the syntax addMapDeps variable
//The library paths to the corresponding libs need to be present
//in the environment variable LIBRARIES or need to be added with a
//addLibDirs declaration.
//To export dependencies to projects that depend on this project, specify
//the dependency in a list of two strings with the second entry equal to
// - "static" ... dependency exported only to static configurations
// - "shared" ... dependency exported only to shared configurations
// - "all" ... dependency exported to all configurations
addDependencies = ["opengl","glu","glew",["Vfw32", "static"] ];
// enable openmp support by the following line (0 is default value)
useOpenMP = 1;
// set the C++ language standard to "stdcpp14" or "stdcpp17" by the following line
cppLanguageStandard = "stdcpp17";
// overwrite windows character set used to encode string, which defaults to "Unicode" or if set env::CGV_CHARSET
charset = "MultiByte";
// overwrite windows subsystem used for linking of executables, which defaults to "Console"
subsystem = "Windows";
//set the name of the definition file, in which the symbols are
//defined that should be exported in a dll which has been implemented
//with extern "C" declarations. An example usage is in the project
//file for libtiff.
defFile = INPUT_PATH."/my_definition_file.def";
//DEPRECATED as the current version of the make file generation allows
//to generate rule files also via the addRules variable.
//Add the entries of the given list as rule files to the project.
//To export a rule file to projects that depend on this project, specify
//the rule file in a list of two strings with the second entry equal to "all"
//Add new rules that specify how to handle extensions during makefile
//generation. Each rule is defined by a MAP with the following entries:
// - extensions : LIST of STRING ... list of extensions covered by this rule
// - folder : STRING ... project folder into which the corresponding
// files should be sorted
// - excl_cfg_idxs : LIST of INT ... list of configuration indices for which the rule
// should not be applied. The following indices can be used:
// 0 ... Release
// 1 ... Debug
// 2 ... Release Dll
// 3 ... Debug Dll
// 4 ... Release Exe (for application plugins)
// 5 ... Debug Exe (for application plugins)
// - tool : optional STRING ... project name of tool used to transform the file
// - rules : optional LIST of MAP ... list of rules to be applied to the source file in order
// to generate new source files. Each list entry of type
// MAP can have the following entries:
// - keep_extension : optional BOOL ... whether to keep extension of source file name
// - suffix : optional STRING ... suffix added to the source file name before adding the extension
// - extension : STRING ... extension of file generated with the tool from the source file
// - path : STRING ... path to the directory where the generated file can be found
// - command_line : LIST of STRING/INT ... list of components of the command line to be executed by
// the rule. First entry defines the command. Other entries of type
// STRING are directly used. Integer entries correspond to
// 0 ... input file
// 1 ... first rule target
// 2 ... second rule target
// 3 ... etc
the cgv namespace
Definition: vr_calib.cxx:9