# Image1.cxx¶

Example source code (Image1.cxx):

/*
* Copyright (C) 1999-2011 Insight Software Consortium
* Copyright (C) 2005-2020 Centre National d'Etudes Spatiales (CNES)
*
* This file is part of Orfeo Toolbox
*
*     https://www.orfeo-toolbox.org/
*
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* Unless required by applicable law or agreed to in writing, software
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
*/

// This example illustrates how to manually construct an \doxygen{otb}{Image}
// class.  The following is the minimal code needed to instantiate, declare
// and create the image class.
//
// \index{Image!Instantiation}
//
// First, the header file of the Image class must be included.

#include "otbImage.h"

int main(int, char* [])
{
// Then we must decide with what type to represent the pixels
// and what the dimension of the image will be. With these two
// parameters we can instantiate the image class. Here we create
// a 2D image, which is what we often use in remote sensing
// applications, anyway, with \code{unsigned short} pixel data.
//
using ImageType = otb::Image<unsigned short, 2>;

// The image can then be created by invoking the \code{New()} operator
// from the corresponding image type and assigning the result
// to a \doxygen{itk}{SmartPointer}.
//
// \index{Image!Pointer}
// \index{Image!New()}
//
ImageType::Pointer image = ImageType::New();

// In OTB, images exist in combination with one or more
// \emph{regions}. A region is a subset of the image and indicates a
// portion of the image that may be processed by other classes in
// the system. One of the most common regions is the
// \emph{LargestPossibleRegion}, which defines the image in its
// entirety. Other important regions found in OTB are the
// \emph{BufferedRegion}, which is the portion of the image actually
// maintained in memory, and the \emph{RequestedRegion}, which is
// the region requested by a filter or other class when operating on
// the image.
//
// In OTB, manually creating an image requires that the image is
// instantiated as previously shown, and that regions describing the image are
// then associated with it.
//
// A region is defined by two classes: the \doxygen{itk}{Index} and
// \doxygen{itk}{Size} classes. The origin of the region within the
// image with which it is associated is defined by Index. The
// extent, or size, of the region is defined by Size. Index
// is represented by a n-dimensional array where each component is an
// integer indicating---in topological image coordinates---the initial
// pixel of the image. When an image is created manually, the user is
// responsible for defining the image size and the index at which the image
// grid starts. These two parameters make it possible to process selected
// regions.
//
// The starting point of the image is defined by an Index class
// that is an n-dimensional array where each component is an integer
// indicating the grid coordinates of the initial pixel of the image.
//
// \index{Image!Size}
// \index{Image!SizeType}
//
ImageType::IndexType start;

start[0] = 0; // first index on X
start[1] = 0; // first index on Y

// The region size is represented by an array of the same dimension of the
// image (using the Size class). The components of the array are
// unsigned integers indicating the extent in pixels of the image along
// every dimension.
//
// \index{Image!Index}
// \index{Image!IndexType}
//
ImageType::SizeType size;

size[0] = 200; // size along X
size[1] = 200; // size along Y

// Having defined the starting index and the image size, these two
// parameters are used to create an ImageRegion object which basically
// encapsulates both concepts. The region is initialized with the
// starting index and size of the image.
//
// \index{Image!itk::ImageRegion}
// \index{Image!RegionType}

ImageType::RegionType region;

region.SetSize(size);
region.SetIndex(start);

// Finally, the region is passed to the \code{Image} object in
// order to define its extent and origin. The \code{SetRegions}
// method sets the LargestPossibleRegion, BufferedRegion, and
// RequestedRegion simultaneously. Note that none of the operations
// performed to this point have allocated memory for the image pixel
// data. It is necessary to invoke the \code{Allocate()} method to
// do this. Allocate does not require any arguments since all the
// information needed for memory allocation has already been
// provided by the region.
//
// \index{Image!Allocate()}
// \index{Image!SetRegions()}

image->SetRegions(region);
image->Allocate();

return EXIT_SUCCESS;
}