facade::png::Image Class Reference

A class for loading and manipulating PNG images. More...

#include <png.hpp>

Inheritance diagram for facade::png::Image:

Public Member Functions
	Image ()
	Image (const void *ptr, std::size_t size, bool validate=true)
	Image (const std::vector< std::uint8_t > &data, bool validate=true)
	Image (const std::string &filename, bool validate=true)
	Image (const Image &other)
Image &	operator= (const Image &other)
	Syntatic sugar for assigning to an image object.
Scanline &	operator[] (std::size_t index)
	Syntactic sugar for getting a scanline from the loaded image.
const Scanline &	operator[] (std::size_t index) const
	Syntactic sugar for getting a const scanline from the loaded image.
bool	has_chunk (const std::string &tag) const
	Check for the presence of a given chunk tag.
std::vector< ChunkVec >	get_chunks (const std::string &tag) const
	Get the chunk data for the corresponding tag.
void	add_chunk (const ChunkVec &chunk)
	Add a given chunk to the underlying image.
bool	has_trailing_data () const
	Return whether or not this PNG image has trailing data.
std::vector< std::uint8_t > &	get_trailing_data ()
	Get the trailing data in the image.
const std::vector< std::uint8_t > &	get_trailing_data () const
	Get the const trailing data in the image.
void	set_trailing_data (const std::vector< std::uint8_t > &data)
	Set the trailing data of the PNG image.
void	clear_trailing_data ()
	Clear the trailing data in the PNG image.
void	parse (const void *ptr, std::size_t size, bool validate=true)
	Parse a given data buffer into its individual chunks for further processing.
void	parse (const std::vector< std::uint8_t > &data, bool validate=true)
	Parse a given data vector for a PNG image.
void	parse (const std::string &filename, bool validate=true)
	Read a file and parse it as a PNG file.
void	load ()
	Load the image data from the IDAT chunks.
Scanline &	scanline (std::size_t index)
	Get the scanline at the given y index.
const Scanline &	scanline (std::size_t index) const
	Get the const scanline at the given y index.
bool	has_header () const
	Check if this PNG image has a header present.
Header &	header ()
	Get the header present in the PNG image.
const Header &	header () const
	Get the const header present in the PNG image.
Header &	new_header ()
	Create and return a new blank header in the PNG image.
std::size_t	width () const
	Get the width, in pixels, of this image.
std::size_t	height () const
	Get the height, in pixels, of this image.
bool	has_image_data () const
	Return if the image has any IDAT chunks present.
bool	is_loaded () const
	Check if the image data has been extracted from the IDAT chunks.
void	decompress ()
	Decompress the IDAT chunks in the image.
void	compress (std::optional< std::size_t > chunk_size=8192, int level=-1)
	Compress the image data into IDAT chunks.
void	reconstruct ()
	Reconstruct the filtered image data into their raw, unfiltered form.
void	filter ()
	Filter the image data to prepare it for compression.
std::vector< std::uint8_t >	to_file () const
	Convert this object into an image buffer fit for saving to a .png file.
void	save (const std::string &filename) const
	Call facade::png::Image::to_file and save that file to disk.
bool	has_text () const
	Return whether or not the image contains a tEXt chunk.
Text &	add_text (const std::string &keyword, const std::string &text)
	Add a text chunk to the PNG image.
void	remove_text (const Text &text)
	Remove the given tEXt section from the image.
void	remove_text (const std::string &keyword, const std::string &text)
	Remove a tEXt section by keyword and text.
std::vector< Text >	get_text (const std::string &keyword) const
	Get the tEXt sections with the following keyword.
bool	has_ztext () const
	Return whether or not the image contains a zTXt chunk.
ZText &	add_ztext (const std::string &keyword, const std::string &text)
	Add a zTXt chunk to the PNG image.
void	remove_ztext (const ZText &ztext)
	Remove the given zTXt section from the image.
void	remove_ztext (const std::string &keyword, const std::string &text)
	Remove a zTXt section by keyword and text.
std::vector< ZText >	get_ztext (const std::string &keyword) const
	Get the zTXt sections with the following keyword.

Static Public Attributes
static const std::uint8_t	Signature [8] = { 0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n' }
	The header signature of a valid PNG file.

Protected Attributes
std::map< std::string, std::vector< ChunkVec > >	chunk_map
	A map of chunk tags to their corresponding facade::png::ChunkVec types.
std::optional< std::vector< std::uint8_t > >	trailing_data
	A container for trailing data, if present when parsing or when writing afterward.
std::optional< std::vector< Scanline > >	image_data
	The loaded image data from the compressed IDAT chunks.

Detailed Description

A class for loading and manipulating PNG images.

Here is an example of how to use this class object in particular:

#include <facade.hpp>
 
using namespace facade;
 
int main(int argc, char *argv[])
{
   png::Image image;
 
   // first, parse the image.
   image.parse("../test/art.png");
 
   // we could also just call image.load(), which does the same steps.
   image.decompress();
   image.reconstruct();
 
   // get the header of the image.
   png::Header &header = image.header();
 
   // let's black out all the pixels in the image.
   for (std::uint32_t y=0; y<header.height(); ++y)
   {
      for (std::uint32_t x=0; x<header.width(); ++x)
      {
         // get the pixel variant that holds our pixel type.
         png::Pixel pixel_var = image[y][x];
 
         // we already know the image we're dealing with is an AlphaTrueColor image,
         // so get that pixel type.
         png::AlphaTrueColorPixel8Bit &pixel = std::get<png::AlphaTrueColorPixel8Bit>(pixel_var);
 
         // invert the pixels
         pixel.red().set_value(0xFF - *pixel.red());
         pixel.green().set_value(0xFF - *pixel.green());
         pixel.blue().set_value(0xFF - *pixel.blue());
 
         // reassign the pixel
         image[y].set_pixel(pixel, x);
      }
   }
 
   // filter the new image
   image.filter();
 
   // compress the new image
   image.compress();
 
   // save the new image
   image.save("art.inverted.png");
 
   return 0;
}

Constructor & Destructor Documentation

Image() [1/5]

facade::png::Image::Image ( )

inline

Image() [2/5]

facade::png::Image::Image ( const void *  ptr, std::size_t  size, bool  validate = true  )

inline

Image() [3/5]

facade::png::Image::Image ( const std::vector< std::uint8_t > &  data, bool  validate = true  )

inline

Image() [4/5]

facade::png::Image::Image ( const std::string &  filename, bool  validate = true  )

inline

Image() [5/5]

facade::png::Image::Image ( const Image &  other )

inline

Member Function Documentation

add_chunk()

void Image::add_chunk

(

const ChunkVec &

chunk

)

Add a given chunk to the underlying image.

add_text()

Text & Image::add_text	(	const std::string &	keyword,
		const std::string &	text
	)

Add a text chunk to the PNG image.

Parameters

keyword	The keyword to give the tEXt chunk.
text	The text to give the tEXt chunk.

Returns

A facade::png::Text chunk reference of the newly added tEXt section.

See also

facade::png::Text

add_ztext()

ZText & Image::add_ztext	(	const std::string &	keyword,
		const std::string &	text
	)

Add a zTXt chunk to the PNG image.

Parameters

keyword	The keyword to give the zTXt chunk.
text	The text to give the zTXt chunk.

Returns

A facade::png::ZText chunk reference of the newly added zTXt section.

See also

facade::png::ZText

clear_trailing_data()

void Image::clear_trailing_data

(

)

Clear the trailing data in the PNG image.

compress()

void Image::compress	(	std::optional< std::size_t >	chunk_size = 8192,
		int	level = -1
	)

Compress the image data into IDAT chunks.

Parameters

chunk_size	The optional chunk size of the fully compressed image data. If present, it splits the image data into as many data chunks as necessary at the given boundary. If set to std::nullopt, the compressed data will be present in one single chunk. The default value is 8192.
level	The level of compression to employ. Default is -1.

Exceptions

facade::exception::ZLibError
facade::exception::NoImageData

See also

facade::compress

decompress()

void Image::decompress

(

)

Decompress the IDAT chunks in the image.

Exceptions

facade::exception::ZLibError

filter()

void Image::filter

(

)

Filter the image data to prepare it for compression.

Exceptions

facade::exception::NoImageData

See also

facade::png::ScanlineBase::filter

get_chunks()

std::vector< ChunkVec > Image::get_chunks

(

const std::string &

tag

)

const

Get the chunk data for the corresponding tag.

Returns

A vector of one or more chunks corresponding to the given chunk tag.

Exceptions

facade::exception::ChunkNotFound

get_text()

std::vector< Text > Image::get_text

(

const std::string &

keyword

)

const

Get the tEXt sections with the following keyword.

Returns

A vector of returned results. An empty vector means the keyword wasn't found.

get_trailing_data() [1/2]

std::vector< std::uint8_t > & Image::get_trailing_data

(

)

Get the trailing data in the image.

Returns

The trailing data in the image.

Exceptions

facade::exception::NoTrailingData

get_trailing_data() [2/2]

const std::vector< std::uint8_t > & Image::get_trailing_data

(

)

const

Get the const trailing data in the image.

Returns

The trailing data in the image.

Exceptions

facade::exception::NoTrailingData

get_ztext()

std::vector< ZText > Image::get_ztext

(

const std::string &

keyword

)

const

Get the zTXt sections with the following keyword.

Returns

A vector of returned results. An empty vector means the keyword wasn't found.

has_chunk()

bool Image::has_chunk

(

const std::string &

tag

)

const

Check for the presence of a given chunk tag.

Returns

True if one or more chunks with that chunk tag were found, false otherwise.

has_header()

bool Image::has_header

(

)

const

Check if this PNG image has a header present.

has_image_data()

bool Image::has_image_data

(

)

const

Return if the image has any IDAT chunks present.

has_text()

bool Image::has_text

(

)

const

Return whether or not the image contains a tEXt chunk.

has_trailing_data()

bool Image::has_trailing_data

(

)

const

Return whether or not this PNG image has trailing data.

has_ztext()

bool Image::has_ztext

(

)

const

Return whether or not the image contains a zTXt chunk.

header() [1/2]

Header & Image::header

(

)

Get the header present in the PNG image.

Returns

A facade::png::Header reference to the data.

Exceptions

facade::exception::NoHeaderChunk

header() [2/2]

const Header & Image::header

(

)

const

Get the const header present in the PNG image.

Returns

A const facade::png::Header reference to the data.

Exceptions

facade::exception::NoHeaderChunk

height()

std::size_t Image::height

(

)

const

Get the height, in pixels, of this image.

Exceptions

facade::exception::NoHeaderChunk

is_loaded()

bool Image::is_loaded

(

)

const

Check if the image data has been extracted from the IDAT chunks.

Note this does not check if the image has been reconstructed.

load()

void Image::load

(

)

Load the image data from the IDAT chunks.

This decompresses and reconstructs the image data in the parsed file or stream.

See also

facade::png::Image::decompress

facade::png::Image::reconstruct

new_header()

Header & Image::new_header

(

)

Create and return a new blank header in the PNG image.

operator=()

Image & Image::operator=

(

const Image &

other

)

Syntatic sugar for assigning to an image object.

operator[]() [1/2]

Scanline & Image::operator[]

(

std::size_t

index

)

Syntactic sugar for getting a scanline from the loaded image.

See also

facade::png::Image::scanline

operator[]() [2/2]

const Scanline & Image::operator[]

(

std::size_t

index

)

const

Syntactic sugar for getting a const scanline from the loaded image.

See also

facade::png::Image::scanline

parse() [1/3]

void Image::parse	(	const std::string &	filename,
		bool	validate = true
	)

Read a file and parse it as a PNG file.

Exceptions

facade::exception::OpenFileFailure

See also

facade::png::Image::parse(const void *, std::size_t, bool)

facade::read_file

parse() [2/3]

void Image::parse	(	const std::vector< std::uint8_t > &	data,
		bool	validate = true
	)

Parse a given data vector for a PNG image.

See also

facade::png::Image::parse(const void *, std::size_t, bool)

parse() [3/3]

void Image::parse	(	const void *	ptr,
		std::size_t	size,
		bool	validate = true
	)

Parse a given data buffer into its individual chunks for further processing.

Parameters

ptr	The data pointer to parse.
size	The size, in bytes, of the data pointer.
validate	If true, validate the checksums in the PNG chunks. Default is true.

Exceptions

facade::exception::InsufficientSize
facade::exception::BadPNGSignature
facade::exception::BadCRC

reconstruct()

void Image::reconstruct

(

)

Reconstruct the filtered image data into their raw, unfiltered form.

Exceptions

facade::exception::NoImageData

See also

facade::png::ScanlineBase::reconstruct

remove_text() [1/2]

void Image::remove_text	(	const std::string &	keyword,
		const std::string &	text
	)

Remove a tEXt section by keyword and text.

Exceptions

facade::exception::TextNotFound

remove_text() [2/2]

void Image::remove_text

(

const Text &

text

)

Remove the given tEXt section from the image.

Exceptions

facade::exception::TextNotFound

remove_ztext() [1/2]

void Image::remove_ztext	(	const std::string &	keyword,
		const std::string &	text
	)

Remove a zTXt section by keyword and text.

Exceptions

facade::exception::TextNotFound

remove_ztext() [2/2]

void Image::remove_ztext

(

const ZText &

ztext

)

Remove the given zTXt section from the image.

Exceptions

facade::exception::TextNotFound

save()

void Image::save

(

const std::string &

filename

)

const

Call facade::png::Image::to_file and save that file to disk.

See also

facade::png::Image::to_file

facade::write_file

scanline() [1/2]

Scanline & Image::scanline

(

std::size_t

index

)

Get the scanline at the given y index.

Returns

The scanline at the given Y index.

Exceptions

facade::exception::NoImageData
facade::exception::OutOfBounds

scanline() [2/2]

const Scanline & Image::scanline

(

std::size_t

index

)

const

Get the const scanline at the given y index.

Returns

The scanline at the given Y index.

Exceptions

facade::exception::NoImageData
facade::exception::OutOfBounds

set_trailing_data()

void Image::set_trailing_data

(

const std::vector< std::uint8_t > &

data

)

Set the trailing data of the PNG image.

to_file()

std::vector< std::uint8_t > Image::to_file

(

)

const

Convert this object into an image buffer fit for saving to a .png file.

This essentially reconstructs all the chunks and their various types (including custom chunks) into an appropriate order, tacks on an IEND chunk if not present, the trailing data if present, then returns the vector data.

width()

std::size_t Image::width

(

)

const

Get the width, in pixels, of this image.

Exceptions

facade::exception::NoHeaderChunk

Member Data Documentation

chunk_map

std::map<std::string, std::vector<ChunkVec> > facade::png::Image::chunk_map

protected

A map of chunk tags to their corresponding facade::png::ChunkVec types.

image_data

std::optional<std::vector<Scanline> > facade::png::Image::image_data

protected

The loaded image data from the compressed IDAT chunks.

Signature

const std::uint8_t Image::Signature = { 0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n' }

static

The header signature of a valid PNG file.

trailing_data

std::optional<std::vector<std::uint8_t> > facade::png::Image::trailing_data

protected

A container for trailing data, if present when parsing or when writing afterward.

---

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

• include/facade/png.hpp
• src/png.cpp