Commit bafd9bac authored by Mo Zhou's avatar Mo Zhou

Imported Upstream version 0~20160730-g797fcb1

parents
language: c
compiler:
- gcc
- clang
cache:
directories:
- $HOME/OpenBlasInstall
sudo: false
env:
- TORCH_LUA_VERSION=LUAJIT21
- TORCH_LUA_VERSION=LUA51
- TORCH_LUA_VERSION=LUA52
addons:
apt:
packages:
- cmake
- gfortran
- gcc-multilib
- gfortran-multilib
- liblapack-dev
- build-essential
- gcc
- g++
- curl
- cmake
- libreadline-dev
- git-core
- libqt4-core
- libqt4-gui
- libqt4-dev
- libjpeg-dev
- libpng-dev
- ncurses-dev
- imagemagick
- libzmq3-dev
- gfortran
- unzip
- gnuplot
- gnuplot-x11
- libgraphicsmagick1-dev
- imagemagick
before_script:
- export ROOT_TRAVIS_DIR=$(pwd)
- export INSTALL_PREFIX=~/torch/install
- ls $HOME/OpenBlasInstall/lib || (cd /tmp/ && git clone https://github.com/xianyi/OpenBLAS.git -b master && cd OpenBLAS && (make NO_AFFINITY=1 -j$(getconf _NPROCESSORS_ONLN) 2>/dev/null >/dev/null) && make PREFIX=$HOME/OpenBlasInstall install)
- git clone https://github.com/torch/distro.git ~/torch --recursive
- cd ~/torch && git submodule update --init --recursive
- mkdir build && cd build
- export CMAKE_LIBRARY_PATH=$HOME/OpenBlasInstall/include:$HOME/OpenBlasInstall/lib:$CMAKE_LIBRARY_PATH
- cmake .. -DCMAKE_INSTALL_PREFIX="${INSTALL_PREFIX}" -DCMAKE_BUILD_TYPE=Release -DWITH_${TORCH_LUA_VERSION}=ON
- make && make install
- cd $ROOT_TRAVIS_DIR
- export LD_LIBRARY_PATH=${INSTALL_PREFIX}/lib:$LD_LIBRARY_PATH
script:
- ${INSTALL_PREFIX}/bin/luarocks make
- export PATH=${INSTALL_PREFIX}/bin:$PATH
- export TESTLUA=$(which luajit lua | head -n 1)
- ${TESTLUA} -limage -e "print('image loaded succesfully')"
- cd test
- ${INSTALL_PREFIX}/bin/luarocks install graphicsmagick
- ${TESTLUA} ./test_rotate.lua
- ${TESTLUA} -limage -e "t=image.test(); if t.errors[1] then os.exit(1) end"
CMAKE_MINIMUM_REQUIRED(VERSION 2.6 FATAL_ERROR)
CMAKE_POLICY(VERSION 2.6)
FIND_PACKAGE(Torch REQUIRED)
FIND_PACKAGE(JPEG)
FIND_PACKAGE(PNG)
# OpenMP support?
SET(WITH_OPENMP ON CACHE BOOL "OpenMP support if available?")
IF (APPLE AND CMAKE_COMPILER_IS_GNUCC)
EXEC_PROGRAM (uname ARGS -v OUTPUT_VARIABLE DARWIN_VERSION)
STRING (REGEX MATCH "[0-9]+" DARWIN_VERSION ${DARWIN_VERSION})
MESSAGE (STATUS "MAC OS Darwin Version: ${DARWIN_VERSION}")
IF (DARWIN_VERSION GREATER 9)
SET(APPLE_OPENMP_SUCKS 1)
ENDIF (DARWIN_VERSION GREATER 9)
EXECUTE_PROCESS (COMMAND ${CMAKE_C_COMPILER} -dumpversion
OUTPUT_VARIABLE GCC_VERSION)
IF (APPLE_OPENMP_SUCKS AND GCC_VERSION VERSION_LESS 4.6.2)
MESSAGE(STATUS "Warning: Disabling OpenMP (unstable with this version of GCC)")
MESSAGE(STATUS " Install GCC >= 4.6.2 or change your OS to enable OpenMP")
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-unknown-pragmas")
SET(WITH_OPENMP OFF CACHE BOOL "OpenMP support if available?" FORCE)
ENDIF ()
ENDIF ()
IF (WITH_OPENMP)
FIND_PACKAGE(OpenMP)
IF(OPENMP_FOUND)
MESSAGE(STATUS "Compiling with OpenMP support")
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${OpenMP_C_FLAGS}")
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS}")
SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${OpenMP_EXE_LINKER_FLAGS}")
ENDIF(OPENMP_FOUND)
ENDIF (WITH_OPENMP)
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -std=c99")
SET(src ppm.c)
ADD_TORCH_PACKAGE(ppm "${src}" "${luasrc}" "Image Processing")
TARGET_LINK_LIBRARIES(ppm luaT TH)
IF(LUALIB)
TARGET_LINK_LIBRARIES(ppm ${LUALIB})
ENDIF()
if (JPEG_FOUND)
SET(src jpeg.c)
include_directories (${JPEG_INCLUDE_DIR})
SET(CMAKE_REQUIRED_INCLUDES "${JPEG_INCLUDE_DIR}")
SET(CMAKE_REQUIRED_LIBRARIES "${JPEG_LIBRARY}")
INCLUDE(CheckSymbolExists)
CHECK_SYMBOL_EXISTS(jpeg_mem_src "stddef.h;stdio.h;jpeglib.h" HAVE_JPEG_MEM_SRC)
IF (HAVE_JPEG_MEM_SRC)
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DHAVE_JPEG_MEM_SRC")
ENDIF (HAVE_JPEG_MEM_SRC)
CHECK_SYMBOL_EXISTS(jpeg_mem_dest "stddef.h;stdio.h;jpeglib.h" HAVE_JPEG_MEM_DEST)
IF (HAVE_JPEG_MEM_DEST)
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DHAVE_JPEG_MEM_DEST")
ENDIF (HAVE_JPEG_MEM_DEST)
ADD_TORCH_PACKAGE(jpeg "${src}" "${luasrc}" "Image Processing")
TARGET_LINK_LIBRARIES(jpeg luaT TH ${JPEG_LIBRARIES})
IF(LUALIB)
TARGET_LINK_LIBRARIES(jpeg ${LUALIB})
ENDIF()
else (JPEG_FOUND)
message ("WARNING: Could not find JPEG libraries, JPEG wrapper will not be installed")
endif (JPEG_FOUND)
if (PNG_FOUND)
SET(src png.c)
include_directories (${PNG_INCLUDE_DIR})
ADD_TORCH_PACKAGE(png "${src}" "${luasrc}" "Image Processing")
TARGET_LINK_LIBRARIES(png luaT TH ${PNG_LIBRARIES})
IF(LUALIB)
TARGET_LINK_LIBRARIES(png ${LUALIB})
ENDIF()
else (PNG_FOUND)
message ("WARNING: Could not find PNG libraries, PNG wrapper will not be installed")
endif (PNG_FOUND)
SET(src image.c)
SET(luasrc init.lua win.ui test/test.lua)
ADD_TORCH_PACKAGE(image "${src}" "${luasrc}" "Image Processing")
TARGET_LINK_LIBRARIES(image luaT TH)
IF(LUALIB)
TARGET_LINK_LIBRARIES(image ${LUALIB})
ENDIF()
INSTALL(DIRECTORY "assets" DESTINATION "${Torch_INSTALL_LUA_PATH_SUBDIR}/image")
INSTALL(FILES "README.md" DESTINATION "${Torch_INSTALL_LUA_PATH_SUBDIR}/image")
Copyright (c) 2011-2014 Idiap Research Institute (Ronan Collobert)
Copyright (c) 2012-2014 Deepmind Technologies (Koray Kavukcuoglu)
Copyright (c) 2011-2012 NEC Laboratories America (Koray Kavukcuoglu)
Copyright (c) 2011-2013 NYU (Clement Farabet)
Copyright (c) 2006-2010 NEC Laboratories America (Ronan Collobert, Leon Bottou, Iain Melvin, Jason Weston)
Copyright (c) 2006 Idiap Research Institute (Samy Bengio)
Copyright (c) 2001-2004 Idiap Research Institute (Ronan Collobert, Samy Bengio, Johnny Mariethoz)
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the names of Deepmind Technologies, NYU, NEC Laboratories America
and IDIAP Research Institute nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
# image Package Reference Manual #
[![Build Status](https://travis-ci.org/torch/image.svg)](https://travis-ci.org/torch/image)
__image__ is the [Torch7 distribution](http://torch.ch/) package for processing
images. It contains a wide variety of functions divided into the following categories:
* [Saving and loading](doc/saveload.md) images as JPEG, PNG, PPM and PGM;
* [Simple transformations](doc/simpletransform.md) like translation, scaling and rotation;
* [Parameterized transformations](doc/paramtransform.md) like convolutions and warping;
* [Simple Drawing Routines](doc/drawing.md) like drawing text or a rectangle on an image;
* [Graphical user interfaces](doc/gui.md) like display and window;
* [Color Space Conversions](doc/colorspace.md) from and to RGB, YUV, Lab, and HSL;
* [Tensor Constructors](doc/tensorconstruct.md) for creating Lenna, Fabio and Gaussian and Laplacian kernels;
Note that unless speficied otherwise, this package deals with images of size
`nChannel x height x width`.
## Install
The easiest way to install this package it by following the [intructions](http://torch.ch/docs/getting-started.html)
to install [Torch7](http://www.torch.ch), which includes __image__.
Otherwise, to update or manually re-install it:
```bash
$ luarocks install image
```
You can test your install with:
```bash
$ luajit -limage -e "image.test()"
```
## Usage
```lua
> require 'image'
> l = image.lena()
> image.display(l)
> f = image.fabio()
> image.display(f)
```
P2
# feep.ascii.pgm
24 7
15
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 3 3 3 3 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 15 15 15 0
0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 15 0
0 3 3 3 0 0 0 7 7 7 0 0 0 11 11 11 0 0 0 15 15 15 15 0
0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 0 0
0 3 0 0 0 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
\ No newline at end of file
P4
1 1
\ No newline at end of file
P5
100 1
255
666666666666666P5
100 1
255
666666666666666
\ No newline at end of file
File added
<a name="image.colorspace"></a>
## Color Space Conversions ##
This section includes functions for performing conversions between
different color spaces.
<a name="image.rgb2lab"></a>
### [res] image.rgb2lab([dst,] src) ###
Converts a `src` RGB image to [Lab](https://en.wikipedia.org/wiki/Lab_color_space).
If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.lab2rgb"></a>
### [res] image.lab2rgb([dst,] src) ###
Converts a `src` [Lab](https://en.wikipedia.org/wiki/Lab_color_space) image to RGB.
If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.rgb2yuv"></a>
### [res] image.rgb2yuv([dst,] src) ###
Converts a RGB image to YUV. If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.yuv2rgb"></a>
### [res] image.yuv2rgb([dst,] src) ###
Converts a YUV image to RGB. If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.rgb2y"></a>
### [res] image.rgb2y([dst,] src) ###
Converts a RGB image to Y (discard U and V).
If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.rgb2hsl"></a>
### [res] image.rgb2hsl([dst,] src) ###
Converts a RGB image to [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV).
If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.hsl2rgb"></a>
### [res] image.hsl2rgb([dst,] src) ###
Converts a HSL image to RGB.
If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.rgb2hsv"></a>
### [res] image.rgb2hsv([dst,] src) ###
Converts a RGB image to [HSV](https://en.wikipedia.org/wiki/HSL_and_HSV).
If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.hsv2rgb"></a>
### [res] image.hsv2rgb([dst,] src) ###
Converts a HSV image to RGB.
If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.rgb2nrgb"></a>
### [res] image.rgb2nrgb([dst,] src) ###
Converts an RGB image to normalized-RGB.
<a name="image.y2jet"></a>
### [res] image.y2jet([dst,] src) ###
Converts a L-levels (1 to L) greyscale image into a L-levels jet heat-map.
If `dst` is provided, it is used to store the output image. Otherwise, returns a new `res` Tensor.
This is particulary helpful for understanding the magnitude of the values of a matrix, or easily spot peaks in scalar field (like probability densities over a 2D area).
For example, you can run it as
```lua
image.display{image=image.y2jet(torch.linspace(1,10,10)), zoom=50}
```
<a name="image.drawing"></a>
## Simple Drawing Routines ##
This section includes simple routines to draw on images.
<a name="image.drawText"></a>
### [res] image.drawText(src, text, x, y, [options]) ###
Draws text onto a 3-channel Tensor (C x H x W) at the x-offset `x` and y-offset `y`.
The `options` table can be passed in to set color, background color, in-place etc.
Options:
* `color` - [table] The text color. A table of 3 numbers `{R, G, B}`, each number scaled between 0 and 255. For example, `red` is `{255, 0, 0}`
* bg - [table] The background color where text is drawn. Same format as color.
* size - [number] Size of the text to be drawn. `Default value = 1`.
* wrap - [boolean] If the text goes out of bounds, wrap it with a newline automatically. `default value = true`
* inplace - [boolean] If true, draws directly on the input tensor and returns it. `default value = false`
Example:
```lua
image.drawText(image.lena(), "hello\nworld", 10, 10)
image.drawText(image.lena(), "hello\nworld", 10, 20,{color = {0, 255, 0}, size = 5})
image.drawText(image.lena(), "hello\nworld", 10, 20,{color = {0, 255, 0}, bg = {255, 0, 0}, size = 5})
```
<a name="image.drawRect"></a>
### [res] image.drawRect(src, x1, y1, x2, y2, [options]) ###
Draws a rectangle onto a 3-channel Tensor (C x H x W). The top-left corner of
the rectangle is `x1, y1`, and the bottom-right corner is `x2, y2`.
The `options` table can be passed in to set color, in-place etc.
Options:
* `color` - [table] The rectangle color. A table of 3 numbers `{R, G, B}`, each
number scaled between 0 and 255. For example, `red` is `{255, 0, 0}`
* `lineWidth` - [number] The width of the rectangle line, in pixels
* `inplace` - [boolean] If true, draws directly on the input tensor and returns
it. `default value = false`
Example:
```lua
image.drawRect(image.lena(), 200, 200, 370, 400, {lineWidth = 5, color = {0, 255, 0}})
```
<a name="image.grapicalinter"></a>
## Graphical User Interfaces ##
The following functions, except for [image.toDisplayTensor](#image.toDisplayTensor),
require package [qtlua](https://github.com/torch/qtlua) and can only be
accessed via the `qlua` Lua interpreter (as opposed to the
[th](https://github.com/torch/trepl) or luajit interpreter).
<a name="image.toDisplayTensor"></a>
### [res] image.toDisplayTensor(input, [...]) ###
Optional arguments `[...]` expand to `padding`, `nrow`, `scaleeach`, `min`, `max`, `symmetric`, `saturate`.
Returns a single `res` Tensor that contains a grid of all in the images in `input`.
The latter can either be a table of image Tensors of size `height x width` (greyscale) or
`nChannel x height x width` (color),
or a single Tensor of size `batchSize x nChannel x height x width` or `nChannel x height x width`
where `nChannel=[3,1]`, `batchSize x height x width` or `height x width`.
When `scaleeach=false` (the default), all detected images
are compressed with successive calls to [image.minmax](simpletransform.md#image.minmax):
```lua
image.minmax{tensor=input[i], min=min, max=max, symm=symmetric, saturate=saturate}
```
`padding` specifies the number of padding pixels between images. The default is 0.
`nrow` specifies the number of images per row. The default is 6.
Note that arguments can also be specified as key-value arguments (in a table).
<a name="image.display"></a>
### [res] image.display(input, [...]) ###
Optional arguments `[...]` expand to `zoom`, `min`, `max`, `legend`, `win`,
`x`, `y`, `scaleeach`, `gui`, `offscreen`, `padding`, `symm`, `nrow`.
Displays `input` image(s) with optional saturation and zooming.
The `input`, which is either a Tensor of size `HxW`, `KxHxW` or `Kx3xHxW`, or list,
is first prepared for display by passing it through [image.toDisplayTensor](#image.toDisplayTensor):
```lua
input = image.toDisplayTensor{
input=input, padding=padding, nrow=nrow, saturate=saturate,
scaleeach=scaleeach, min=min, max=max, symmetric=symm
}
```
The resulting `input` will be displayed using [qtlua](https://github.com/torch/qtlua).
The displayed image will be zoomed by a factor of `zoom`. The default is 1.
If `gui=true` (the default), the graphical user inteface (GUI)
is an interactive window that provides the user with the ability to zoom in or out.
This can be turned off for a faster display. `legend` is a legend to be displayed,
which has a default value of `image.display`. `win` is an optional qt window descriptor.
If `x` and `y` are given, they are used to offset the image. Both default to 0.
When `offscreen=true`, rendering (to generate images) is performed offscreen.
<a name="image.window"></a>
### [window, painter] image.window([...]) ###
Creates a window context for images.
Optional arguments `[...]` expand to `hook_resize`, `hook_mousepress`, `hook_mousedoublepress`.
These have a default value of `nil`, but may correspond to commensurate qt objects.
# image Package Reference Manual #
__image__ is the [Torch7 distribution](http://torch.ch/) package for processing
images. It contains a wide variety of functions divided into the following categories:
* [Saving and loading](saveload.md) images as JPEG, PNG, PPM and PGM;
* [Simple transformations](simpletransform.md) like translation, scaling and rotation;
* [Parameterized transformations](paramtransform.md) like convolutions and warping;
* [Simple Drawing Routines](doc/drawing.md) like drawing text or a rectangle on an image;
* [Graphical user interfaces](gui.md) like display and window;
* [Color Space Conversions](colorspace.md) from and to RGB, YUV, Lab, and HSL;
* [Tensor Constructors](tensorconstruct.md) for creating Lenna, Fabio and Gaussian and Laplacian kernels;
Note that unless speficied otherwise, this package deals with images of size
`nChannel x height x width`.
## Install
The easiest way to install this package it by following the [intructions](http://torch.ch/docs/getting-started.html)
to install [Torch7](www.torch.ch), which includes __image__.
Otherwise, to update or manually re-install it:
```bash
$ luarocks install image
```
## Usage
```lua
> require 'image'
> l = image.lena()
> image.display(l)
> f = image.fabio()
> image.display(f)
```
<a name="image.paramtrans"></a>
## Parameterized transformations ##
This section includes functions for performing transformations on
images requiring parameter Tensors like a warp `field` or a convolution
`kernel`.
<a name="image.warp"></a>
### [res] image.warp([dst,]src,field,[mode,offset,clamp_mode,pad_val]) ###
Warps image `src` (of size`KxHxW`)
according to flow field `field`. The latter has size `2xHxW` where the
first dimension is for the `(y,x)` flow field. String `mode` can
take on values [lanczos](https://en.wikipedia.org/wiki/Lanczos_resampling),
[bicubic](https://en.wikipedia.org/wiki/Bicubic_interpolation),
[bilinear](https://en.wikipedia.org/wiki/Bilinear_interpolation) (the default),
or *simple*. When `offset` is true (the default), `(x,y)` is added to the flow field.
The `clamp_mode` variable specifies how to handle the interpolation of samples off the input image.
Permitted values are strings *clamp* (the default) or *pad*.
When `clamp_mode` equals `pad`, the user can specify the padding value with `pad_val` (default = 0). Note: setting this value when `clamp_mode` equals `clamp` will result in an error.
If `dst` is specified, it is used to store the result of the warp.
Otherwise, returns a new `res` Tensor.
<a name="image.convolve"></a>
### [res] image.convolve([dst,] src, kernel, [mode]) ###
Convolves Tensor `kernel` over image `src`. Valid string values for argument
`mode` are :
* *full* : the `src` image is effectively zero-padded such that the `res` of the convolution has the same size as `src`;
* *valid* (the default) : the `res` image will have `math.ceil(kernel/2)` less columns and rows on each side;
* *same* : performs a *full* convolution, but crops out the portion fitting the output size of *valid*;
Note that this function internally uses
[torch.conv2](https://github.com/torch/torch7/blob/master/doc/maths.md#torch.conv.dok).
If `dst` is provided, it is used to store the output image.
Otherwise, returns a new `res` Tensor.
<a name="image.lcn"></a>
### [res] image.lcn(src, [kernel]) ###
Local contrast normalization (LCN) on a given `src` image using kernel `kernel`.
If `kernel` is not given, then a default `9x9` Gaussian is used
(see [image.gaussian](tensorconstruct.md#image.gaussian)).
To prevent border effects, the image is first global contrast normalized
(GCN) by substracting the global mean and dividing by the global
standard deviation.
Then the image is locally contrast normalized using the following equation:
```lua
res = (src - lm(src)) / sqrt( lm(src) - lm(src*src) )
```
where `lm(x)` is the local mean of each pixel in the image (i.e.
`image.convolve(x,kernel)`) and `sqrt(x)` is the element-wise
square root of `x`. In other words, LCN performs
local substractive and divisive normalization.
Note that this implementation is different than the LCN Layer defined on page 3 of
[What is the Best Multi-Stage Architecture for Object Recognition?](http://yann.lecun.com/exdb/publis/pdf/jarrett-iccv-09.pdf).
<a name="image.erode"></a>
### [res] image.erode(src, [kernel, pad]) ###
Performs a [morphological erosion](https://en.wikipedia.org/wiki/Erosion_(morphology))
on binary (zeros and ones) image `src` using odd
dimensioned morphological binary kernel `kernel`.
The default is a kernel consisting of ones of size `3x3`. Number
`pad` is the value to assume outside the image boundary when performing
the convolution. The default is 1.
<a name="image.dilate"></a>
### [res] image.dilate(src, [kernel, pad]) ###
Performs a [morphological dilation](https://en.wikipedia.org/wiki/Dilation_(morphology))
on binary (zeros and ones) image `src` using odd
dimensioned morphological binary kernel `kernel`.
The default is a kernel consisting of ones of size `3x3`. Number
`pad` is the value to assume outside the image boundary when performing
the convolution. The default is 0.
<a name="image.saveload"></a>
## Saving and Loading ##
This sections includes functions for saving and loading different types
of images to and from disk.
<a name="image.load"></a>
### [res] image.load(filename, [depth, tensortype]) ###
Loads an image located at path `filename` having `depth` channels (1 or 3)
into a [Tensor](https://github.com/torch/torch7/blob/master/doc/tensor.md#tensor)
of type `tensortype` (*float*, *double* or *byte*). The last two arguments
are optional.
The image format is determined from the `filename`'s
extension suffix. Supported formats are
[JPEG](https://en.wikipedia.org/wiki/JPEG),
[PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics),
[PPM and PGM](https://en.wikipedia.org/wiki/Netpbm_format).
The returned `res` Tensor has size `nChannel x height x width` where `nChannel` is
1 (greyscale) or 3 (usually [RGB](https://en.wikipedia.org/wiki/RGB_color_model)
or [YUV](https://en.wikipedia.org/wiki/YUV).
Usage:
```lua
--To load as byte tensor for rgb imagefile
local img = image.load(imagefile,3,'byte')
--To load as byte tensor for gray imagefile
local img = image.load(imagefile,1,'byte')
```
<a name="image.save"></a>
### image.save(filename, tensor) ###
Saves Tensor `tensor` to disk at path `filename`. The format to which
the image is saved is extrapolated from the `filename`'s extension suffix.
The `tensor` should be of size `nChannel x height x width`.
To save with a minimal loss, the tensor values should lie in the range [0, 1] since the tensor is clamped between 0 and 1 before being saved to the disk.
<a name="image.decompressJPG"></a>
### [res] image.decompressJPG(tensor, [depth, tensortype]) ###
Decompresses an image from a ByteTensor in memory having `depth` channels (1 or 3)
into a [Tensor](https://github.com/torch/torch7/blob/master/doc/tensor.md#tensor)
of type `tensortype` (*float*, *double* or *byte*). The last two arguments
are optional.
Usage:
```lua
local fin = torch.DiskFile(imfile, 'r')
fin:binary()
fin:seekEnd()
local file_size_bytes = fin:position() - 1
fin:seek(1)
local img_binary = torch.ByteTensor(file_size_bytes)
fin:readByte(img_binary:storage())
fin:close()
-- Then when you're ready to decompress the ByteTensor:
im = image.decompressJPG(img_binary)
```
<a name="image.compressJPG"></a>
### [res] image.compressJPG(tensor, [quality]) ###
Compresses an image to a ByteTensor in memory. Optional quality is between 1 and 100 and adjusts compression quality.
<a name="image.simpletrans"></a>
## Simple Transformations ##
This section includes simple but very common image transformations
like cropping, translation, scaling and rotation.
<a name="image.crop"></a>
### [res] image.crop([dst,] src, x1, y1, [x2, y2]) ###
Crops image `src` at coordinate `(x1, y1)` up to coordinate
`(x2, y2)`. The coordinate indexing is zero-based and `(x2, y2)` is non-inclusive.
If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
```lua
-- The indexing starts with 0 and 2 is non-inclusive coordinate.
> require('image')
> image.crop(torch.Tensor(3, 2, 2), 0, 0 , 2, 2) -- crop is a correct crop and the result is 3x2x2 tensor.
(1,.,.) =
0 0
0 0
(2,.,.) =
0 0
0 0
(3,.,.) =
0 0
0 0
[torch.DoubleTensor of size 3x2x2]
```
### [res] image.crop([dst,] src, format, width, height) ###
Crops a `width x height` section of source image `src`. The argument
`format` is a string specifying where to crop: it can be "c", "tl", "tr",
"bl" or "br" for center, top left, top right, bottom left and bottom right,
respectively. If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.translate"></a>
### [res] image.translate([dst,] src, x, y) ###
Translates image `src` by `x` pixels horizontally and `y` pixels
vertically. If `dst` is provided, it is used to store the output
image. Otherwise, returns a new `res` Tensor.
<a name="image.scale"></a>
### [res] image.scale(src, width, height, [mode]) ###
Rescale the height and width of image `src` to have
width `width` and height `height`. Variable `mode` specifies
type of interpolation to be used. Valid values include
[bilinear](https://en.wikipedia.org/wiki/Bilinear_interpolation)
(the default), [bicubic](https://en.wikipedia.org/wiki/Bicubic_interpolation),
or *simple* interpolation. Returns a new `res` Tensor.
### [res] image.scale(src, size, [mode]) ###
Rescale the height and width of image `src`. Variable `size` is a number
or a string specifying the size of the result image. When `size` is a
number, it specifies the maximum height or width of the output. When it is
a string like `WxH` or `MAX` or `^MIN`, `*SC` or `*SCn/SCd` it specifies
the `height x width`, maximum height or width of the output, minimum height
or width of the output, scaling factor (number), or fractional scaling
factor (int/int), respectively.
### [res] image.scale(dst, src, [mode]) ###
Rescale the height and width of image `src` to fit the dimensions of
Tensor `dst`.
<a name="image.rotate"></a>
### [res] image.rotate([dst,], src, theta, [mode]) ###
Rotates image `src` by `theta` radians.
If `dst` is specified it is used to store the results of the rotation.
Variable `mode` specifies type of interpolation to be used. Valid values include
*simple* (the default) or *bilinear* interpolation.
<a name="image.polar"></a>
### [res] image.polar([dst,], src, [interpolation], [mode]) ###
Converts image `src` to polar coordinates. In the polar image, angular information is in the vertical direction and radius information in the horizontal direction.
If `dst` is specified it is used to store the polar image. If `dst` is not specified, its size is automatically determined. Variable `interpolation` specifies type of interpolation to be used. Valid values include *simple* (the default) or *bilinear* interpolation. Variable `mode` determines whether the *full* image is converted to the polar space (implying empty regions in the polar image), or whether only the *valid* central part of the polar transform is returned (the default).
<a name="image.logpolar"></a>
### [res] image.logpolar([dst,], src, [interpolation], [mode]) ###
Converts image `src` to log-polar coordinates. In the log-polar image, angular information is in the vertical direction and log-radius information in the horizontal direction.
If `dst` is specified it is used to store the polar image. If `dst` is not specified, its size is automatically determined. Variable `interpolation` specifies type of interpolation to be used. Valid values include *simple* (the default) or *bilinear* interpolation. Variable `mode` determines whether the *full* image is converted to the log-polar space (implying empty regions in the log-polar image), or whether only the *valid* central part of the log-polar transform is returned (the default).
<a name="image.hflip"></a>
### [res] image.hflip([dst,] src) ###
Flips image `src` horizontally (left<->right). If `dst` is provided, it is used to
store the output image. Otherwise, returns a new `res` Tensor.
<a name="image.vflip"></a>
### [res] image.vflip([dst,], src) ###
Flips image `src` vertically (upsize<->down). If `dst` is provided, it is used to
store the output image. Otherwise, returns a new `res` Tensor.
<a name="image.flip"></a>
### [res] image.flip([dst,] src, flip_dim) ###
Flips image `src` along the specified dimension. If `dst` is provided, it is used to
store the output image. Otherwise, returns a new `res` Tensor.
<a name="image.minmax"></a>
### [res] image.minmax{tensor, [min, max, ...]} ###
Compresses image `tensor` between `min` and `max`.
When omitted, `min` and `max` are infered from
`tensor:min()` and `tensor:max()`, respectively.
The `tensor` is normalized using `min` and `max` by performing :
```lua
tensor:add(-min):div(max-min)
```
Other optional arguments (`...`) include `symm`, `inplace`, `saturate`, and `tensorOut`.