Blended pixel value calculation for two overlaped rasters. More...

#include <Blender.h>

Inheritance diagram for te::rp::Blender:

Public Types
enum	BlendMethod { InvalidBlendMethod = 0, NoBlendMethod = 1, EuclideanDistanceMethod = 2 }

Public Member Functions
	Blender ()

void	getBlendedValues (const double &line, const double &col, std::vector< double > &values)
	Blend a pixel value using the current parameters. More...

bool	initialize (const te::rst::Raster &raster1, const std::vector< unsigned int > &raster1Bands, const te::rst::Raster &raster2, const std::vector< unsigned int > &raster2Bands, const BlendMethod &blendMethod, const te::rst::Interpolator::Method &interpMethod1, const te::rst::Interpolator::Method &interpMethod2, const double &noDataValue, const bool forceInputNoDataValue, const std::vector< double > &pixelOffsets1, const std::vector< double > &pixelScales1, const std::vector< double > &pixelOffsets2, const std::vector< double > &pixelScales2, te::gm::Polygon const const r1ValidDataDelimiterPtr, te::gm::Polygon const const r2ValidDataDelimiterPtr, const te::gm::GeometricTransformation &geomTransformation)
	Inititate the blender instance. More...

	~Blender ()

Protected Types
typedef void(Blender::*	BlendFunctPtr )(const double &line, const double &col, std::vector< double > &values)
	Type definition for the a bleding function pointer. More...

Protected Member Functions
void	clear ()
	Clear all internal allocated resources. More...

void	euclideanDistanceMethodImp (const double &line1, const double &col1, std::vector< double > &values)
	Implementation for EuclideanDistanceMethod. More...

void	initState ()
	Reset the instance to its initial default state. More...

void	noBlendMethodImp (const double &line1, const double &col1, std::vector< double > &values)
	Implementation for NoBlendMethod. More...

Protected Attributes
BlendFunctPtr	m_blendFuncPtr
	The current blend function. More...

BlendMethod	m_blendMethod
	The blend method to apply. More...

double	m_euclideanDistanceMethodImp_aux1

double	m_euclideanDistanceMethodImp_aux2

te::gm::Point	m_euclideanDistanceMethodImp_auxPoint

unsigned int	m_euclideanDistanceMethodImp_BandIdx

double	m_euclideanDistanceMethodImp_currDist

std::complex< double >	m_euclideanDistanceMethodImp_cValue1

std::complex< double >	m_euclideanDistanceMethodImp_cValue2

double	m_euclideanDistanceMethodImp_dist1

double	m_euclideanDistanceMethodImp_dist2

double	m_euclideanDistanceMethodImp_Point2Col

double	m_euclideanDistanceMethodImp_Point2Line

std::size_t	m_euclideanDistanceMethodImp_vecIdx

te::gm::GeometricTransformation *	m_geomTransformationPtr
	A transformation mapping raster 1 pixels ( te::gm::GTParameters::TiePoint::first ) to raster 2 ( te::gm::GTParameters::TiePoint::second ) (Note: all coords are indexed by lines/columns). More...

te::rst::Interpolator *	m_interp1
	Raster 1 interpolator instance pointer. More...

te::rst::Interpolator *	m_interp2
	Raster 2 interpolator instance pointer. More...

te::rst::Interpolator::Method	m_interpMethod1
	The interpolation method to use when reading raster 1 data. More...

te::rst::Interpolator::Method	m_interpMethod2
	The interpolation method to use when reading raster 2 data. More...

std::auto_ptr < te::gm::MultiPolygon >	m_intersectionPtr
	The Intersection geometry ( Multipolygon geometry - raster 1 indexed coods). More...

unsigned int	m_noBlendMethodImp_BandIdx

std::complex< double >	m_noBlendMethodImp_cValue

double	m_noBlendMethodImp_Point1XProj1
	Raster 2 no-data values (on value per band). More...

double	m_noBlendMethodImp_Point1XProj2

double	m_noBlendMethodImp_Point1YProj1

double	m_noBlendMethodImp_Point1YProj2

double	m_noBlendMethodImp_Point2Col

double	m_noBlendMethodImp_Point2Line

double	m_noBlendMethodImp_Value

double	m_outputNoDataValue
	The output raster no-data value. More...

std::vector< double >	m_pixelOffsets1
	The values offset to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band). More...

std::vector< double >	m_pixelOffsets2
	The values offset to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band). More...

std::vector< double >	m_pixelScales1
	The values scale to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band). More...

std::vector< double >	m_pixelScales2
	The values scale to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band). More...

std::vector< std::pair < te::gm::Coord2D, te::gm::Coord2D > >	m_r1IntersectionSegmentsPoints
	A sub-set of the intersection polygon wich is part of raster 1 valid data polygon ( raster 1 indexed coods). More...

std::size_t	m_r1IntersectionSegmentsPointsSize
	Size of m_r1IntersectionSegmentsPoints;. More...

std::vector< std::pair < te::gm::Coord2D, te::gm::Coord2D > >	m_r2IntersectionSegmentsPoints
	A sub-set of the intersection polygon wich is part of raster 2 valid data polygon ( raster 1 indexed coods). More...

std::size_t	m_r2IntersectionSegmentsPointsSize
	Size of m_r2IntersectionSegmentsPoints;. More...

std::vector< unsigned int >	m_raster1Bands
	Input raster 1 band indexes to use. More...

std::vector< double >	m_raster1NoDataValues

te::rst::Raster const *	m_raster1Ptr
	Input raster 1. More...

std::vector< unsigned int >	m_raster2Bands
	Input raster 2 band indexes to use. More...

std::vector< double >	m_raster2NoDataValues
	Raster 1 no-data values (on value per band). More...

te::rst::Raster const *	m_raster2Ptr
	Input raster 2. More...

Detailed Description

Blended pixel value calculation for two overlaped rasters.

The overlap between the two images is modeled by the given geometric transformation direct mapping input raster 1 indexed coords (line, column) to input raster 2 indexed coords.

Definition at line 53 of file Blender.h.

Member Typedef Documentation

typedef void(Blender::* te::rp::Blender::BlendFunctPtr)(const double &line, const double &col, std::vector< double > &values)

protected

Type definition for the a bleding function pointer.

Parameters

line	Raster 1 Line.
col	Raster 1 Column.
values	Blended values for each band.

Definition at line 133 of file Blender.h.

Member Enumeration Documentation

enum te::rp::Blender::BlendMethod

Pixel Blend methods.

Enumerator
InvalidBlendMethod	Invalid blending method.
NoBlendMethod	No blending performed.
EuclideanDistanceMethod	Euclidean distance method.

Definition at line 58 of file Blender.h.

Constructor & Destructor Documentation

te::rp::Blender::Blender ( )

Default constructor.

Definition at line 71 of file Blender.cpp.

References initState().

te::rp::Blender::~Blender ( )

Default destructor.

Definition at line 76 of file Blender.cpp.

References clear().

Member Function Documentation

void te::rp::Blender::clear ( )

protected

Clear all internal allocated resources.

Definition at line 516 of file Blender.cpp.

References initState(), m_geomTransformationPtr, m_interp1, m_interp2, m_intersectionPtr, m_pixelOffsets1, m_pixelOffsets2, m_pixelScales1, m_pixelScales2, m_r1IntersectionSegmentsPoints, m_r2IntersectionSegmentsPoints, m_raster1Bands, m_raster1NoDataValues, m_raster2Bands, and m_raster2NoDataValues.

Referenced by initialize(), and ~Blender().

void te::rp::Blender::euclideanDistanceMethodImp	(	const double &	line1,
		const double &	col1,
		std::vector< double > &	values
	)

protected

Implementation for EuclideanDistanceMethod.

Parameters

line	Raster 1 Line.
col	Raster 1 Column.
values	Blended values for each band.

Definition at line 582 of file Blender.cpp.

Referenced by initialize().

void te::rp::Blender::getBlendedValues	(	const double &	line,
		const double &	col,
		std::vector< double > &	values
	)

inline

Blend a pixel value using the current parameters.

Parameters

line	Line (raster 1 reference).
col	Column (raster 1 reference).
values	Blended values for each band.

Note: The caller of this method must be aware that the returned blended value may be outside the original input rasters valid values range.; Raster 1 values have precedence over raster 2 values (when applicable).

Definition at line 118 of file Blender.h.

References TERP_DEBUG_TRUE_OR_THROW.

Referenced by te::rp::GeoMosaic::execute(), te::rp::TiePointsMosaic::execute(), and te::rp::SequenceMosaic::execute().

bool te::rp::Blender::initialize	(	const te::rst::Raster &	raster1,
		const std::vector< unsigned int > &	raster1Bands,
		const te::rst::Raster &	raster2,
		const std::vector< unsigned int > &	raster2Bands,
		const BlendMethod &	blendMethod,
		const te::rst::Interpolator::Method &	interpMethod1,
		const te::rst::Interpolator::Method &	interpMethod2,
		const double &	noDataValue,
		const bool	forceInputNoDataValue,
		const std::vector< double > &	pixelOffsets1,
		const std::vector< double > &	pixelScales1,
		const std::vector< double > &	pixelOffsets2,
		const std::vector< double > &	pixelScales2,
		te::gm::Polygon const *const	r1ValidDataDelimiterPtr,
		te::gm::Polygon const *const	r2ValidDataDelimiterPtr,
		const te::gm::GeometricTransformation &	geomTransformation
	)

Inititate the blender instance.

Parameters

raster1	Input raster 1.
raster1Bands	Input raster 1 band indexes to use.
raster2	Input raster 2.
raster2Bands	Input raster 2 band indexes to use (this vector has the same size as raster1Bands).
blendMethod	The blend method to apply.
interpMethod1	The interpolation method to use when reading raster 1 data.
interpMethod2	The interpolation method to use when reading raster 2 data.
noDataValue	The value returned where there is no pixel data bo blend.
forceInputNoDataValue	Use noDataValue as the input rasters no-data value (The original rasters no-data values will be ignored)
pixelOffsets1	The values offset to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).
pixelScales1	The values scale to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).
pixelOffsets2	The values offset to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).
pixelScales2	The values scale to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).
r1ValidDataDelimiterPtr	A pointer to a geometry (raster 1 world/projected coords) delimiting the raster region with valid data, or null if all raster data area is valid.
r2ValidDataDelimiterPtr	A pointer to a geometry (raster 2 world/projected coords) delimiting the raster region with valid data, or null if all raster data area is valid.
geomTransformation	A transformation mapping raster 1 pixels ( te::gm::GTParameters::TiePoint::first ) to raster 2 pixels ( te::gm::GTParameters::TiePoint::second ) (Note: all coords are indexed by lines/columns).

Returns: true if ok, false on errors

Definition at line 81 of file Blender.cpp.

References clear(), te::gm::GeometricTransformation::clone(), EuclideanDistanceMethod, euclideanDistanceMethodImp(), te::rst::Grid::geoToGrid(), te::rst::Raster::getAccessPolicy(), te::rst::Raster::getBand(), te::gm::LineString::getCoordinates(), te::gm::GeometryCollection::getGeometryN(), te::rst::Raster::getGrid(), te::gm::LineString::getNPoints(), te::gm::CurvePolygon::getNPoints(), te::rst::Raster::getNumberOfBands(), te::rst::Raster::getNumberOfColumns(), te::rst::Raster::getNumberOfRows(), te::gm::GeometryCollection::getNumGeometries(), te::gm::CurvePolygon::getNumRings(), te::rst::Band::getProperty(), te::gm::CurvePolygon::getRingN(), te::gm::GeometricTransformation::inverseMap(), te::gm::GeometricTransformation::isValid(), te::gm::LineStringType, m_blendFuncPtr, m_blendMethod, m_geomTransformationPtr, m_interp1, m_interp2, m_interpMethod1, m_interpMethod2, m_intersectionPtr, te::rst::BandProperty::m_noDataValue, m_outputNoDataValue, m_pixelOffsets1, m_pixelOffsets2, m_pixelScales1, m_pixelScales2, m_r1IntersectionSegmentsPoints, m_r1IntersectionSegmentsPointsSize, m_r2IntersectionSegmentsPoints, m_r2IntersectionSegmentsPointsSize, m_raster1Bands, m_raster1NoDataValues, m_raster1Ptr, m_raster2Bands, m_raster2NoDataValues, m_raster2Ptr, te::gm::MultiLineStringType, te::gm::MultiPolygonType, NoBlendMethod, noBlendMethodImp(), te::gm::PolygonType, te::common::RAccess, te::gm::LineString::setPoint(), te::gm::LineString::size(), TERP_TRUE_OR_RETURN_FALSE, te::gm::Coord2D::x, and te::gm::Coord2D::y.

Referenced by te::rp::GeoMosaic::execute(), te::rp::TiePointsMosaic::execute(), and te::rp::SequenceMosaic::execute().

void te::rp::Blender::initState ( )

protected

Reset the instance to its initial default state.

Definition at line 500 of file Blender.cpp.

References InvalidBlendMethod, m_blendFuncPtr, m_blendMethod, m_geomTransformationPtr, m_interp1, m_interp2, m_interpMethod1, m_interpMethod2, m_outputNoDataValue, m_r1IntersectionSegmentsPointsSize, m_r2IntersectionSegmentsPointsSize, m_raster1Ptr, m_raster2Ptr, and te::rst::Interpolator::NearestNeighbor.

Referenced by Blender(), and clear().

void te::rp::Blender::noBlendMethodImp	(	const double &	line1,
		const double &	col1,
		std::vector< double > &	values
	)

protected

Implementation for NoBlendMethod.

Parameters

line	Raster 1 Line.
col	Raster 1 Column.
values	Blended values for each band.

Definition at line 536 of file Blender.cpp.

References te::gm::GeometricTransformation::directMap(), te::rst::Interpolator::getValue(), m_geomTransformationPtr, m_interp1, m_interp2, m_noBlendMethodImp_BandIdx, m_noBlendMethodImp_cValue, m_noBlendMethodImp_Point2Col, m_noBlendMethodImp_Point2Line, m_noBlendMethodImp_Value, m_outputNoDataValue, m_pixelOffsets1, m_pixelOffsets2, m_pixelScales1, m_pixelScales2, m_raster1Bands, m_raster1NoDataValues, m_raster2Bands, m_raster2NoDataValues, and TERP_DEBUG_TRUE_OR_THROW.

Referenced by euclideanDistanceMethodImp(), and initialize().

Member Data Documentation

BlendFunctPtr te::rp::Blender::m_blendFuncPtr

protected

The current blend function.

Definition at line 137 of file Blender.h.

Referenced by initialize(), and initState().

BlendMethod te::rp::Blender::m_blendMethod

protected

The blend method to apply.

Definition at line 136 of file Blender.h.

Referenced by initialize(), and initState().

double te::rp::Blender::m_euclideanDistanceMethodImp_aux1

protected

Definition at line 182 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

double te::rp::Blender::m_euclideanDistanceMethodImp_aux2

protected

Definition at line 183 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

te::gm::Point te::rp::Blender::m_euclideanDistanceMethodImp_auxPoint

protected

Definition at line 172 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

unsigned int te::rp::Blender::m_euclideanDistanceMethodImp_BandIdx

protected

Definition at line 177 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

double te::rp::Blender::m_euclideanDistanceMethodImp_currDist

protected

Definition at line 178 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

std::complex< double > te::rp::Blender::m_euclideanDistanceMethodImp_cValue1

protected

Definition at line 175 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

std::complex< double > te::rp::Blender::m_euclideanDistanceMethodImp_cValue2

protected

Definition at line 176 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

double te::rp::Blender::m_euclideanDistanceMethodImp_dist1

protected

Definition at line 179 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

double te::rp::Blender::m_euclideanDistanceMethodImp_dist2

protected

Definition at line 180 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

double te::rp::Blender::m_euclideanDistanceMethodImp_Point2Col

protected

Definition at line 174 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

double te::rp::Blender::m_euclideanDistanceMethodImp_Point2Line

protected

Definition at line 173 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

std::size_t te::rp::Blender::m_euclideanDistanceMethodImp_vecIdx

protected

Definition at line 181 of file Blender.h.

Referenced by euclideanDistanceMethodImp().

te::gm::GeometricTransformation* te::rp::Blender::m_geomTransformationPtr

protected

A transformation mapping raster 1 pixels ( te::gm::GTParameters::TiePoint::first ) to raster 2 ( te::gm::GTParameters::TiePoint::second ) (Note: all coords are indexed by lines/columns).

Definition at line 145 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), initState(), and noBlendMethodImp().

te::rst::Interpolator* te::rp::Blender::m_interp1

protected

Raster 1 interpolator instance pointer.

Definition at line 149 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), initState(), and noBlendMethodImp().

te::rst::Interpolator* te::rp::Blender::m_interp2

protected

Raster 2 interpolator instance pointer.

Definition at line 150 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), initState(), and noBlendMethodImp().

te::rst::Interpolator::Method te::rp::Blender::m_interpMethod1

protected

The interpolation method to use when reading raster 1 data.

Definition at line 146 of file Blender.h.

Referenced by initialize(), and initState().

te::rst::Interpolator::Method te::rp::Blender::m_interpMethod2

protected

The interpolation method to use when reading raster 2 data.

Definition at line 147 of file Blender.h.

Referenced by initialize(), and initState().

std::auto_ptr< te::gm::MultiPolygon > te::rp::Blender::m_intersectionPtr

protected

The Intersection geometry ( Multipolygon geometry - raster 1 indexed coods).

Definition at line 140 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), and initialize().

unsigned int te::rp::Blender::m_noBlendMethodImp_BandIdx

protected

Definition at line 169 of file Blender.h.

Referenced by noBlendMethodImp().

std::complex< double > te::rp::Blender::m_noBlendMethodImp_cValue

protected

Definition at line 167 of file Blender.h.

Referenced by noBlendMethodImp().

double te::rp::Blender::m_noBlendMethodImp_Point1XProj1

protected

Raster 2 no-data values (on value per band).

Definition at line 161 of file Blender.h.

double te::rp::Blender::m_noBlendMethodImp_Point1XProj2

protected

Definition at line 163 of file Blender.h.

double te::rp::Blender::m_noBlendMethodImp_Point1YProj1

protected

Definition at line 162 of file Blender.h.

double te::rp::Blender::m_noBlendMethodImp_Point1YProj2

protected

Definition at line 164 of file Blender.h.

double te::rp::Blender::m_noBlendMethodImp_Point2Col

protected

Definition at line 166 of file Blender.h.

Referenced by noBlendMethodImp().

double te::rp::Blender::m_noBlendMethodImp_Point2Line

protected

Definition at line 165 of file Blender.h.

Referenced by noBlendMethodImp().

double te::rp::Blender::m_noBlendMethodImp_Value

protected

Definition at line 168 of file Blender.h.

Referenced by noBlendMethodImp().

double te::rp::Blender::m_outputNoDataValue

protected

The output raster no-data value.

Definition at line 148 of file Blender.h.

Referenced by euclideanDistanceMethodImp(), initialize(), initState(), and noBlendMethodImp().

std::vector< double > te::rp::Blender::m_pixelOffsets1

protected

The values offset to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).

Definition at line 153 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), and noBlendMethodImp().

std::vector< double > te::rp::Blender::m_pixelOffsets2

protected

The values offset to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).

Definition at line 155 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), and noBlendMethodImp().

std::vector< double > te::rp::Blender::m_pixelScales1

protected

The values scale to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).

Definition at line 154 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), and noBlendMethodImp().

std::vector< double > te::rp::Blender::m_pixelScales2

protected

The values scale to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).

Definition at line 156 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), and noBlendMethodImp().

std::vector< std::pair< te::gm::Coord2D, te::gm::Coord2D > > te::rp::Blender::m_r1IntersectionSegmentsPoints

protected

A sub-set of the intersection polygon wich is part of raster 1 valid data polygon ( raster 1 indexed coods).

Definition at line 141 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), and initialize().

std::size_t te::rp::Blender::m_r1IntersectionSegmentsPointsSize

protected

Size of m_r1IntersectionSegmentsPoints;.

Definition at line 142 of file Blender.h.

Referenced by euclideanDistanceMethodImp(), initialize(), and initState().

std::vector< std::pair< te::gm::Coord2D, te::gm::Coord2D > > te::rp::Blender::m_r2IntersectionSegmentsPoints

protected

A sub-set of the intersection polygon wich is part of raster 2 valid data polygon ( raster 1 indexed coods).

Definition at line 143 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), and initialize().

std::size_t te::rp::Blender::m_r2IntersectionSegmentsPointsSize

protected

Size of m_r2IntersectionSegmentsPoints;.

Definition at line 144 of file Blender.h.

Referenced by euclideanDistanceMethodImp(), initialize(), and initState().

std::vector< unsigned int > te::rp::Blender::m_raster1Bands

protected

Input raster 1 band indexes to use.

Definition at line 151 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), and noBlendMethodImp().

std::vector< double > te::rp::Blender::m_raster1NoDataValues

protected

Definition at line 157 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), and noBlendMethodImp().

te::rst::Raster const* te::rp::Blender::m_raster1Ptr

protected

Input raster 1.

Definition at line 138 of file Blender.h.

Referenced by initialize(), and initState().

std::vector< unsigned int > te::rp::Blender::m_raster2Bands

protected

Input raster 2 band indexes to use.

Definition at line 152 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), and noBlendMethodImp().

std::vector< double > te::rp::Blender::m_raster2NoDataValues

protected

Raster 1 no-data values (on value per band).

Definition at line 158 of file Blender.h.

Referenced by clear(), euclideanDistanceMethodImp(), initialize(), and noBlendMethodImp().

te::rst::Raster const* te::rp::Blender::m_raster2Ptr

protected

Input raster 2.

Definition at line 139 of file Blender.h.

Referenced by initialize(), and initState().

The documentation for this class was generated from the following files:

/home/castejon/castejon_files/develop/terralib5/git/src/terralib/rp/Blender.h
/home/castejon/castejon_files/develop/terralib5/git/src/terralib/rp/Blender.cpp

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation