<xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"></meta>
<title>The CImg Library - C++ Template Image Processing Toolkit</title>
<meta content="David Tschumperle" name="author"></meta>
<link rel="shortcut icon" type="image/x-icon" href="http://cimg.sourceforge.net/favicon.ico"></link>
<link rel="icon" type="image/png" href="favicon.png"></link>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
<style type="text/css">
<!--
body {background-color:#C0C0C0; font-family:sans-serif; }
a { font-weight:bold; color:#636363; }
a:active{text-decoration:none; color:#000000}
a:link{text-decoration:none; color:#000000}
a:visited{text-decoration:none; color:#000000}
a:hover{text-decoration:underline; color:#4E9F71}
-->
</style>
<script language="JavaScript" type="text/javascript">
<!-- Original: Eric King (eric_andrew_king@hotmail.com) is used to display images in popup windows -->
<!-- Web Site: http://redrival.com/eak/ -->
<!-- This script and many more are available free online at -->
<!-- The JavaScript Source!! http://javascript.internet.com -->
<!-- Begin
function NewWindow(mypage, myname, w, h, scroll) {
var winl = (screen.width - w) / 2;
var wint = (screen.height - h) / 2;
winprops = 'height='+h+',width='+w+',top='+wint+',left='+winl+',scrollbars='+scroll+',resizable'
win = window.open(mypage, myname, winprops)
if (parseInt(navigator.appVersion) >= 4) { win.window.focus(); }
}
// End -->
</script>
<script type="text/javascript" src="../jquery-1.11.0.min.js"></script>
<script type="text/javascript">
$(document).ready(function() {
$('#cssmenu > ul').prepend('<li class="mobile"><a href="#"><span>Menu <i>☰</i></span></a></li>');
$('#cssmenu > ul > li > a').click(function(e) {
$('#cssmenu li').removeClass('active');
$(this).closest('li').addClass('active');
var checkElement = $(this).next();
if((checkElement.is('ul')) && (checkElement.is(':visible'))) {
$(this).closest('li').removeClass('active');
checkElement.slideUp('normal');
}
if((checkElement.is('ul')) && (!checkElement.is(':visible'))) {
$('#cssmenu ul ul:visible').slideUp('normal');
checkElement.slideDown('normal');
}
if( $(this).parent().hasClass('mobile') ) {
e.preventDefault();
$('#cssmenu').toggleClass('expand');
}
if($(this).closest('li').find('ul').children().length == 0) {
return true;
} else {
return false;
}
});
});
</script>
<link rel="stylesheet" type="text/css" href="../header.css" />
</head>
<body>
<table align="center" cellpadding="12" cellspacing="0" width="1024" style="border-style:solid; border-width:0px; border-color:black" bgcolor="#FFFFFF">
<tr><td>
<center>
<hr noshade="noshade" size="1" width="90%"></hr>
<br/>
<a href="http://cimg.sourceforge.net"><img src="http://cimg.sourceforge.net/img/CImgLogo2.jpg" alt="" border="0"></img></a><br/>
<br/>
<hr noshade="noshade" size="1" width="90%"></hr>
<table width="90%" align="center">
<td width="18%"> </td>
<td width="65%">
<div id='cssmenu'>
<ul>
<li class='first'><a href='http://cimg.sourceforge.net/index.shtml'><span>Home</span></a></li>
<li><a href='http://cimg.sourceforge.net/download.shtml'><span>Download</span></a></li>
<li><a href='http://cimg.sourceforge.net/screenshots.shtml'><span>Screenshots</span></a></li>
<li><a href='http://cimg.sourceforge.net/reference/group__cimg__faq.html'><span>FAQ</span></a></li>
<li><a href='http://cimg.sourceforge.net/reference/group__cimg__tutorial.html'><span>Tutorial</span></a></li>
<li><a href='http://cimg.sourceforge.net/reference/index.html'><span>Documentation</span></a></li>
<li><a href='http://sourceforge.net/projects/cimg/forums/forum/334630'><span>Forum</span></a></li>
<li><a href='http://cimg.sourceforge.net/links.shtml'><span>Links</span></a></li>
</ul>
</div>
</td>
<td align="right">
<script type="text/javascript">
var flattr_url = 'http://cimg.sourceforge.net';
var flattr_btn='compact';
</script>
<script src="http://api.flattr.com/button/load.js" type="text/javascript"></script>
</td>
</tr></table>
</center>
</td></tr>
<tr><td>
<!-- Generated by Doxygen 1.8.8 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">FAQ : Frequently Asked Questions.</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="ssf0"></a>
FAQ Summary</h1>
<ul>
<li><a href="#sf1">General information and availability</a><ul>
<li><a href="#ssf11">What is the CImg Library ?</a></li>
<li><a href="#ssf12">What platforms are supported ?</a></li>
<li><a href="#ssf13">How is CImg distributed ?</a></li>
<li><a href="#ssf14">What kind of people are concerned by CImg ?</a></li>
<li><a href="#ssf15">What are the specificities of the CeCILL license ?</a></li>
<li><a href="#ssf16">Who is behind CImg ?</a></li>
</ul>
</li>
<li><a href="#sf2">C++ related questions</a><ul>
<li><a href="#ssf21">What is the level of C++ knowledge needed to use CImg ?</a></li>
<li><a href="#ssf22">How to use CImg in my own C++ program ?</a></li>
<li><a href="#ssf23">Why is CImg entirely contained in a single header file ?</a></li>
</ul>
</li>
<li><a href="#sf3">Other resources</a><ul>
<li><a href="#ssf31">Translations</a></li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="sf1"></a>
1. General information and availability</h1>
<h2><a class="anchor" id="ssf11"></a>
1.1. What is the CImg Library ?</h2>
<p>The CImg Library is an <em>open-source C++ toolkit for image processing</em>.<br />
It mainly consists in a (big) single header file <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> providing a set of C++ classes and functions that can be used in your own sources, to load/save, manage/process and display generic images. It's actually a very simple and pleasant toolkit for coding image processing stuffs in C++ : Just include the header file <code>CImg.h</code>, and you are ready to handle images in your C++ programs.</p>
<h2><a class="anchor" id="ssf12"></a>
1.2. What platforms are supported ?</h2>
<p>CImg has been designed with <em>portability</em> in mind. It is regularly tested on different architectures and compilers, and should also work on any decent OS having a decent C++ compiler. Before each release, the CImg Library is compiled under these different configurations : </p><ul>
<li>PC Linux 32 bits, with g++. </li>
<li>PC Windows 32 bits, with Visual C++ 6.0. </li>
<li>PC Windows 32 bits, with Visual C++ Express Edition. </li>
<li>Sun SPARC Solaris 32 bits, with g++. </li>
<li>Mac PPC with OS X and g++.</li>
</ul>
<p>CImg has a minimal number of dependencies. In its minimal version, it can be compiled only with standard C++ headers. Anyway, it has interesting extension capabilities and can use external libraries to perform specific tasks more efficiently (Fourier Transform computation using FFTW for instance).</p>
<h2><a class="anchor" id="ssf13"></a>
1.3. How is CImg distributed ?</h2>
<p>The CImg Library is freely distributed as a complete .zip compressed package, hosted at the <a href="http://sourceforge.net/project/showfiles.php?group_id=96492">Sourceforge servers</a>.<br />
The package is distributed under the <a href="http://www.cecill.info">CeCILL license</a>.</p>
<p>This package contains :</p><ul>
<li>The main library file <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> (C++ header file).</li>
<li>Several C++ source code showing <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/examples/">examples of using CImg</a>.</li>
<li>A complete library documentation, in <a href="index.html">HTML</a> and <a href="../CImg_reference.pdf">PDF</a> formats.</li>
<li>Additional <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/plugins/">library plug-ins</a> that can be used to extend library capabilities for specific uses.</li>
</ul>
<p>The CImg Library is a quite lightweight library which is easy to maintain (due to its particular structure), and thus has a fast rythm of release. A new version of the CImg package is released approximately every three months.</p>
<h2><a class="anchor" id="ssf14"></a>
1.4. What kind of people are concerned by CImg ?</h2>
<p>The CImg library is an <em>image processing</em> library, primarily intended for computer scientists or students working in the fields of image processing or computer vision, and knowing bases of C++. As the library is handy and really easy to use, it can be also used by any programmer needing occasional tools for dealing with images in C++, since there are no standard library yet for this purpose.</p>
<h2><a class="anchor" id="ssf15"></a>
1.5. What are the specificities of the CeCILL license ?</h2>
<p>The <a href="http://www.cecill.info">CeCILL license</a> governs the use of the CImg Library. This is an <em>open-source</em> license which gives you rights to access, use, modify and redistribute the source code, under certains conditions. There are two different variants of the CeCILL license used in CImg (namely <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> and <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a>, all open-source), corresponding to different constraints on the source files :</p><ul>
<li>The <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a> license is the most permissive one, close to the <em>GNU LGPL license</em>, and <em>applies <b>only</b> on the main library file <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a></em>. Basically, this license allows to use <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> in a closed-source product without forcing you to redistribute the entire software source code. Anyway, if one modifies the <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> source file, one has to redistribute the modified version of the file that must be governed by the same <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a> license.</li>
<li>The <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> license applies to all other files (source examples, plug-ins and documentation) of the CImg Library package, and is close (even <em>compatible</em>) with the <em>GNU GPL license</em>. It <em>does not allow</em> the use of these files in closed-source products.</li>
</ul>
<p>You are invited to read the complete descriptions of the the <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a> and <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> licenses before releasing a software based on the CImg Library.</p>
<h2><a class="anchor" id="ssf16"></a>
1.6. Who is behind CImg ?</h2>
<p>CImg has been started by <a href="http://tschumperle.users.greyc.fr/">David Tschumperle</a> at the beginning of his PhD thesis, in October 1999. He is still the main coordinator of the project. Since the first release at Sourceforge, a growing number of contributors has appeared. Due to the very simple and compact form of the library, submitting a contribution is quite easy and can be fastly integrated into the supported releases. List of contributors can be found on the front page.</p>
<h1><a class="anchor" id="sf2"></a>
2. C++ related questions</h1>
<h2><a class="anchor" id="ssf21"></a>
2.1 What is the level of C++ knowledge needed to use CImg ?</h2>
<p>The CImg Library has been designed using C++ templates and object-oriented programming techniques, but in a very accessible level. There are only public classes without any derivation (just like C structures) and there is at most one template parameter for each CImg class (defining the pixel type of the images). The design is simple but clean, making the library accessible even for non professional C++ programmers, while proposing strong extension capabilities for C++ experts.</p>
<h2><a class="anchor" id="ssf22"></a>
2.2 How to use CImg in my own C++ program ?</h2>
<p>Basically, you need to add these two lines in your C++ source code, in order to be able to work with CImg images : </p><div class="fragment"><div class="line"><span class="preprocessor">#include "CImg.h"</span></div>
<div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacecimg__library.html">cimg_library</a>;</div>
</div><!-- fragment --><h2><a class="anchor" id="ssf23"></a>
2.3 Why is CImg entirely contained in a single header file ?</h2>
<p>People are often surprised to see that the complete code of the library is contained in a single (big) C++ header file <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a>. There are good practical and technical reasons to do that. Some arguments are listed below to justify this approach, so (I hope) you won't think this is a awkwardly C++ design of the CImg library :<br />
</p><ul>
<li>First, the library is based on <em>template datatypes</em> (images with generic pixel type), meaning that the programmer is free to decide what type of image he instanciates in his code. Even if there are roughly a limited number of fully supported types (basically, the "atomic" types of C++ : <em>unsigned char, int, float, ...</em>), this is <em>not imaginable</em> to pre-compile the library classes and functions for <em>all possible atomic datatypes</em>, since many functions and methods can have two or three arguments having different template parameters. This really means <em>a huge number</em> of possible combinations. The size of the object binary file generated to cover all possible cases would be just <em>colossal</em>. Is the STL library a pre-compiled one ? No, CImg neither. CImg is not using a classical <em>.cpp</em> and <em>.h</em> mechanism, just like the STL. Architectures of C++ <em>template-based</em> libraries are somewhat special in this sense. This is a proven technical fact.</li>
<li>Second, why CImg does not have several header files, just like the STL does (one for each class for instance) ? This would be possible of course. There are only 4 classes in CImg, the two most important being <em>CImg<T></em> and <em>CImgList<T></em> representing respectively an image and a collection of images. But contrary to the STL library, these two CImg classes are strongly <em>inter-dependent</em>. All CImg algorithms are actually not defined as separate functions acting on containers (as the STL does with his header <algorithm>), but are directly methods of the image and image collection classes. This inter-dependence practically means that you will undoubtly need these two main classes at the same time if you are using CImg. If they were defined in separate header files, you would be forced to include both of them. What is the gain then ? No gain.<br />
Concerning the two other classes : You can disable the third most important class <em>CImgDisplay</em> of the CImg library, by setting the compilation macro <em>cimg_display</em> to 0, avoiding thus to compile this class if you don't use display capabilities of CImg in your code. But to be honest, this is a quite small class and doing this doesn't save much compilation time. The last and fourth class is <em>CImgException</em>, which is only few lines long and is obviously required in almost all methods of CImg. Including this one is <em>mandatory</em>.<br />
As a consequence, having a single header file instead of several ones is just a way for you to avoid including all of them, without any consequences on compilation time. This is both good technical and practical reasons to do like this.</li>
<li>Third, having a single header file has plenty of advantages : Simplicity for the user, and for the developers (maintenance is in fact easier). Look at the <code>CImg.h</code> file, it looks like a mess at a first glance, but it is in fact very well organized and structured. Finding pieces of code in CImg functions or methods is particularly easy and fast. Also, how about the fact that library installation problems just disappear ? Just bring <code>CImg.h</code> with you, put it in your source directory, and the library is ready to go !</li>
</ul>
<p>I admit the compilation time of CImg-based programs can be sometime long, but don't think that it is due to the fact that you are using a single header file. Using several header files wouldn't arrange anything since you would need all of them. Having a pre-compiled library object would be the only solution to speed up compilation time, but it is not possible at all, due to the too much generic nature of the library.</p>
<h1><a class="anchor" id="sf3"></a>
3. Other resources</h1>
<h2><a class="anchor" id="ssf31"></a>
3.1 Translations</h2>
<p>This FAQ has been translated to <a href="http://science.webhostinggeeks.com/cimg-biblioteka">Serbo-Croatian</a> language by <a href="http://webhostinggeeks.com/">Web Geeks </a>. </p>
</div></div><!-- contents -->
</td></tr></table>
<center>
<p>
<a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=96492&type=3" border="0" height="37" width="125"></img>
</a>
<a href="http://sourceforge.net/donate/index.php?group_id=96492"><img src="http://images.sourceforge.net/images/project-support.jpg" width="88" height="32" border="0" alt="Support This Project" /> </a>
</p>
</center>
<!-- Start of StatCounter Code -->
<script type="text/javascript" language="javascript">
<!--
var sc_project=895001;
var sc_invisible=1;
var sc_partition=7;
var sc_security="5ea85181";
//-->
</script>
<script type="text/javascript" language="javascript" src="http://www.statcounter.com/counter/counter.js"></script><noscript><a href="http://www.statcounter.com/" target="_blank"><img src="http://c8.statcounter.com/counter.php?sc_project=895001&java=0&security=5ea85181&invisible=1" alt="counter stats" border="0"></a> </noscript>
<!-- End of StatCounter Code -->
<!-- Google Analytics -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-16976814-2']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<!-- End Google Analytics -->
</body>
</html>
