diff --git a/doc/guide/formats.hpp b/doc/guide/formats.hpp index 1fb2d7debb1..acf8a00c20d 100644 --- a/doc/guide/formats.hpp +++ b/doc/guide/formats.hpp @@ -2,11 +2,36 @@ @section formatintro Introduction -mlpack supports a wide variety of data and model formats for use in both its +mlpack supports a wide variety of data (including images) and model formats for use in both its command-line programs and in C++ programs using mlpack via the mlpack::data::Load() function. This tutorial discusses the formats that are supported and how to use them. +@section toc_tut Table of Contents + +This tutorial is split into the following sections: + + - \ref formatintro + - \ref toc_tut + - Data + - Data Formats + - \ref formatsimple + - \ref formattypes + - \ref formatcpp + - \ref sparseload + - \ref formatcat + - \ref formatcatcpp + - Image Support + - \ref intro_imagetut + - \ref model_api_imagetut + - \ref imageinfo_api_imagetut + - \ref load_api_imagetut + - \ref save_api_imagetut + - Models + - \ref formatmodels + - \ref formatmodelscpp + - \ref formatfinal + @section formatsimple Simple examples to load data in C++ The example code snippets below load data from different formats into an @@ -295,6 +320,125 @@ mlpack::data::Save("dataset-new.tsv", dataset, info); There is more functionality to the DatasetInfo class; for more information, see the mlpack::data::DatasetInfo documentation. +@section intro_imagetut Loading and Saving Images + +Image datasets are becoming increasingly popular in deep learning. + +mlpack's image saving/loading functionality is based on [stb/](https://github.com/nothings/stb). + +@section model_api_imagetut Image Utilities API + +Image utilities supports loading and saving of images. + +It supports filetypes "jpg", "png", "tga","bmp", "psd", "gif", "hdr", "pic", "pnm" for loading and "jpg", "png", "tga", "bmp", "hdr" for saving. + +The datatype associated is unsigned char to support RGB values in the range 1-255. To feed data into the network typecast of `arma::Mat` may be required. Images are stored in matrix as (width * height * channels, NumberOfImages). Therefore imageMatrix.col(0) would be the first image if images are loaded in imageMatrix. + +@section imageinfo_api_imagetut Accessing Metadata of Images: ImageInfo + +ImageInfo class contains the metadata of the images. +@code +ImageInfo(const size_t width, + const size_t height, + const size_t channels); +@endcode +Other public memebers include: + - flipVertical Flip the image vertical upon loading. + - quality Compression of the image if saved as jpg (0-100). + +@section load_api_imagetut Loading Images in C++ + + +Standalone loading of images. +@code + template + bool Load(const std::string& filename, + arma::Mat& matrix, + ImageInfo& info, + const bool fatal, + const bool transpose); +@endcode + +Loading a test image. It also fills up the ImageInfo class object. +@code +data::ImageInfo info; +data::Load("test_image.png", matrix, info, false, true); +@endcode + +ImageInfo requires height, width, number of channels of the image. + +@code +size_t height = 64, width = 64, channels = 1; +data::ImageInfo info(width, height, channels); +@endcode + +More than one image can be loaded into the same matrix. + +Loading multiple images: + +@code + template + bool Load(const std::vector& files, + arma::Mat& matrix, + ImageInfo& info, + const bool fatal, + const bool transpose); +@endcode + +@code + data::ImageInfo info; + std::vector> files{"test_image1.bmp","test_image2.bmp"}; + data::load(files, matrix, info, false, true); +@endcode + +@section save_api_imagetut Saving Images in C++ + +Save images expects a matrix of type unsigned char in the form (width * height * channels, NumberOfImages). +Just like load it can be used to save one image or multiple images. Besides image data it also expects the shape of the image as input (width, height, channels). + +Saving one image: + +@code + template + bool Save(const std::string& filename, + arma::Mat& matrix, + ImageInfo& info, + const bool fatal, + const bool transpose); +@endcode + +@code + data::ImageInfo info; + info.width = info.height = 25; + info.channels = 3; + info.quality = 90; + data::Save("test_image.bmp", matrix, info, false, true); +@endcode + +If the matrix contains more than one image, only the first one is saved. + +Saving multiple images: + +@code + template + bool Save(const std::vector& files, + arma::Mat& matrix, + ImageInfo& info, + const bool fatal, + const bool transpose); +@endcode + +@code + data::ImageInfo info; + info.width = info.height = 25; + info.channels = 3; + info.quality = 90; + std::vector> files{"test_image1.bmp", "test_image2.bmp"}; + data::Save(files, matrix, info, false, true); +@endcode + +Multiple images are saved according to the vector of filenames specified. + @section formatmodels Loading and saving models Using \c boost::serialization, mlpack is able to load and save machine learning diff --git a/doc/tutorials/image/image.txt b/doc/tutorials/image/image.txt deleted file mode 100644 index 8a635bf260a..00000000000 --- a/doc/tutorials/image/image.txt +++ /dev/null @@ -1,185 +0,0 @@ -/*! -@file image.txt -@author Mehul Kumar Nirala -@brief Tutorial for how to load and save images in mlpack. - -@page imagetutorial Image Utilities tutorial - -@section intro_imagetut Introduction - -Image datasets are becoming increasingly popular in deep learning. - -mlpack's image saving/loading functionality is based on [stb/](https://github.com/nothings/stb). - -@section toc_imagetut Table of Contents - -This tutorial is split into the following sections: - - - \ref intro_imagetut - - \ref toc_imagetut - - \ref model_api_imagetut - - \ref imageinfo_api_imagetut - - \ref load_api_imagetut - - \ref save_api_imagetut - -@section model_api_imagetut Model API - -Image utilities supports loading and saving of images. - -It supports filetypes "jpg", "png", "tga","bmp", "psd", "gif", "hdr", "pic", "pnm" for loading and "jpg", "png", "tga", "bmp", "hdr" for saving. - -The datatype associated is unsigned char to support RGB values in the range 1-255. To feed data into the network typecast of `arma::Mat` may be required. Images are stored in matrix as (width * height * channels, NumberOfImages). Therefore imageMatrix.col(0) would be the first image if images are loaded in imageMatrix. - -@section imageinfo_api_imagetut ImageInfo - -ImageInfo class contains the metadata of the images. -@code - /** - * Instantiate the ImageInfo object with the image width, height, channels. - * - * @param width Image width. - * @param height Image height. - * @param channels number of channels in the image. - */ - ImageInfo(const size_t width, - const size_t height, - const size_t channels); -@endcode -Other public memebers include: - - flipVertical Flip the image vertical upon loading. - - quality Compression of the image if saved as jpg (0-100). - -@section load_api_imagetut Load - - -Standalone loading of images. -@code - /** - * Load the image file into the given matrix. - * - * @param filename Name of the image file. - * @param matrix Matrix to load the image into. - * @param info An object of ImageInfo class. - * @param fatal If an error should be reported as fatal (default false). - * @param transpose If true, transpose the matrix after loading. - * @return Boolean value indicating success or failure of load. - */ - template - bool Load(const std::string& filename, - arma::Mat& matrix, - ImageInfo& info, - const bool fatal, - const bool transpose); -@endcode - -Loading a test image. It also fills up the ImageInfo class object. -@code -data::ImageInfo info; -data::Load("test_image.png", matrix, info, false, true); -@endcode - -ImageInfo requires height, width, number of channels of the image. - -@code -size_t height = 64, width = 64, channels = 1; -data::ImageInfo info(width, height, channels); -@endcode - -More than one image can be loaded into the same matrix. - -Loading multiple images: - -@code - /** - * Load the image file into the given matrix. - * - * @param files A vector consisting of filenames. - * @param matrix Matrix to save the image from. - * @param info An object of ImageInfo class. - * @param fatal If an error should be reported as fatal (default false). - * @param transpose If true, transpose the matrix after loading. - * @return Boolean value indicating success or failure of load. - */ - template - bool Load(const std::vector& files, - arma::Mat& matrix, - ImageInfo& info, - const bool fatal, - const bool transpose); -@endcode - -@code - data::ImageInfo info; - std::vector> files{"test_image1.bmp","test_image2.bmp"}; - data::load(files, matrix, info, false, true); -@endcode - -@section save_api_imagetut Save - -Save images expects a matrix of type unsigned char in the form (width * height * channels, NumberOfImages). -Just like load it can be used to save one image or multiple images. Besides image data it also expects the shape of the image as input (width, height, channels). - -Saving one image: - -@code - /** - * Save the image file from the given matrix. - * - * @param filename Name of the image file. - * @param matrix Matrix to save the image from. - * @param info An object of ImageInfo class. - * @param fatal If an error should be reported as fatal (default false). - * @param transpose If true, transpose the matrix after loading. - * @return Boolean value indicating success or failure of load. - */ - template - bool Save(const std::string& filename, - arma::Mat& matrix, - ImageInfo& info, - const bool fatal, - const bool transpose); -@endcode - -@code - data::ImageInfo info; - info.width = info.height = 25; - info.channels = 3; - info.quality = 90; - data::Save("test_image.bmp", matrix, info, false, true); -@endcode - -If the matrix contains more than one image, only the first one is saved. - -Saving multiple images: - -@code - /** - * Save the image file from the given matrix. - * - * @param files A vector consisting of filenames. - * @param matrix Matrix to save the image from. - * @param info An object of ImageInfo class. - * @param fatal If an error should be reported as fatal (default false). - * @param transpose If true, transpose the matrix after loading. - * @return Boolean value indicating success or failure of load. - */ - template - bool Save(const std::vector& files, - arma::Mat& matrix, - ImageInfo& info, - const bool fatal, - const bool transpose); -@endcode - -@code - data::ImageInfo info; - info.width = info.height = 25; - info.channels = 3; - info.quality = 90; - std::vector> files{"test_image1.bmp", "test_image2.bmp"}; - data::Save(files, matrix, info, false, true); -@endcode - -Multiple images are saved according to the vector of filenames specified. - -*/