Generalities

Smil is a software library intended to handle... images. So, Image is the basic and most important data type under Smil. Near all classes and functions in the library handle an Image data type.

An Image is the data type used by Smil to represent and handle an image in memory.

What you must know about Smil Images

Very important : the origin of coordinates is at the Top left corner of the image and height coordinates grows downside;
From the programming point of view, a Smil Image is a class with data and methods;
Inside the Smil Python environnment, image pixels are coded in one of three data types : UINT8, UINT16 or UINT32;
Smil can't directly handle floating point coded images. It's a design choice :
- Mathematical Morphology is based more on order relation between values then on their difference;
- from an algorithmic point of view, the set of possible values is finite with limited cardinality;
- it's allways possible to scale and convert a floating point coded image into an positive integer coded image, handle it under Smil and go back at the end.
Smil images can be converted to and from Numpy format. See fromNumArray() and getNumArray() or examples at page : Smil <-> NumPy interface.
Very Important - all functions having an image as output parameter expect receive these parameters as already instantiated images. As an example, take the erode() function call :
```
     # create an output image instance before calling erode function
     imOut = sp.Image()
     r = sp.erode(imIn, imOut, sp.CrossSE())
```
No matter the past history of imOut, it just need to be already instantiated before function call. The Smil function will adjust everything shall be adjusted.

Declare or create Smil Images

There are several ways to create an instance of an Image :

create an empty image and, if you want, synthesize its content :

     # create an empty image
     im = sp.Image(32, 32)
     # draw a rectangle on it
     for i in range(8, 24):
       for j = range(8, 24):
         im.setPixel(i, j, 255)

Note :

default values for image dimensions are : 256, 256, 1
default data type is UINT8

read an image from some local file :
```
     im = sp.Image('barbara.png')
```

read an image from internet :

     im = sp.Image('https://example.com/images/barbara.png')
     # or
     r = sp.getHttpFile('https://example.com/images/lena.png', 'lena.png')
     im = sp.Image('lena.png')

create an empty image with the same characteristics (size and data type) of another image :
```
     im2 = sp.Image(im1)
```
create an empty image with the same size but different data type type of another image :
```
     im2 = sp.Image(im1, 'UINT16')
```

clone another image

     im2 = sp.Image()
     r = sp.clone(im1, im2)

another way to create an image from a local file

     im = sp.Image()
     r = sp.read('barbara.png', im)

create a 3D image from a stack of 2D images

     im = sp.Image
     fNames = [ 'slice-{:03d}.png'.format(x) for x in range(0,256) ]
     r = sp.read(fNames, im)

read a RAW image

     type   = 'UINT16'
     width  = 256
     height = 384
     depth  = 512
     img    = sp.Image(type)
     r = sp.readRAW(fname, width, height, depth, img)

create or import an image from Python (Numpy or Scikit-Image). See examples at section Smil <-> NumPy interface.

Note

Smil can read and identify (by their file extension) different image file formats : png, jpg, tiff, bmp and pbm for 2D images. RAW format can be used to read both 2D and 3D images.
RAW format means a format without metadata, i.e. just a stream of data and not the RAW format from camera makers (NEF, RAF, CR2, ...). See readRAW().
About 3D images : from the most common image file types - (png, jpeg, tiff, ...) - tiff is the only file type able to store 3D images and even floating pointing coded images. But Smil doesn't read directly these images.

Image function reference

Creating mpty images
- Image(shape=(256,256,1), type=UINT8) : Create an empty image.
- Image() : Create an empty 2D image with size 256x256
- Image(szx, szy=1, szz=1], type=UINT8) : Alternative syntax of previous functions (for compatibility)
Creating from an existing image
- Image(im, clone=False, type=None) : Create an image with the same characteristics than im. Copy the content if clone is True. Change the data type if type is different of None.
- Image(ndarray) : Create a Smil image from a Numpy array. ndarray type shall be a valid Smil type (UINT8, UINT16 or UINT32)
Creating from file(s)
- Image(path, raw=False, shape=(256,256,1) , type=UINT8) : create a Smil image from a file. If raw is False, input file type shall be one of valid image file types : .png, .jpg, .tif or .bmp. shape and type are taken into account only for raw file types.
- Image([path, path, ...], raw=False, shape=(256,256,1), type=UINT8) : create a 3D image from a stack (Python list) of 2D raw images having the same size.
Creating from internet
- Image(url) : create a Smil image from an image file from internet.

Save Smil Images

To save Smil images you have, basically, two functions : write() and writeRAW().

use write() to save a 2D image as a single file or a 3D image as a stack of files.

     # 2D image
     r = sp.write(im2D, 'file.png')

     # 3D image
     fNames = [ 'image-{:03d}.png'.format(x) for x in range(0, im3D.getDepth()) ]
     r = sp.write(im3D, fNames)

use writeRAW() to save an image (2D or 3D) as a stream of values.
```
     r = sp.writeRAW(im, 'image.raw')
```

Table of Contents

Generalities

What you must know about Smil Images

Declare or create Smil Images

Image function reference

Save Smil Images