SIPL Core

How To Use The SIPL Core Library

First of all make sure the header files and cpp files were added to project directory or dragged to the solution explorer if using visual studio.

Start with including the following header files: #include "Image_Header.h" And #include "Color_Catalog.h"

Here is a main files that shows an example how working with images is done in SIPL

 int main(void) {
Image Test; //creating an Image object
Color_Palette palette; //creating a color palette for color usage

Test.Load_Image("Image1.jpg"); //loading Image1.jpg from project directory to object memory 

Test.Image_Transpose(1); //transposing image pixels


Test.Write_Image("AfterMark"); // writing image data from object to drive (project directory)
system("AfterMark.jpg"); //opening newly saved image from project directory 
return(1);}`

Basic Operations:

The most basic and first thing you want to do when working with SIPL is to create an Image object.

Example: Image MyImage();

After having an image object you are ready to load an image to the object memory ,after loading an image you can treat the object as it were the image it self, if you want to work with 10 images you can create an array of Image's and load 10 different images .

Loading image data to the object is accomplished by using the Load_Image method . Example: MyImage.Load_Image("testimage.jpg");

Now your object is ready for manipulation .

Basic Methods:

   void init_pixel_matrix();
int getWidth() const;
int getHeight()const;
void getPixelCopy(int Height, int Width, pixel &save_pixel);
void Set_Pixel_By_Inedx(int index, uint8_t value);
void Load_Blank_Canvas();
void Load_Blank_Canvas(int width, int height, char set_color);
void Load_Blank_Canvas(int width, int height, pixel const &background_color);
void Get_Center(int &center_x, int &center_y)const;

void printImdata();
void printImdata(char color);
void Manual_Draw();
void Load_Image();
void Load_Image(const char *f_name);
void Write_Image();
void Write_Image(const char *f_name);
void Color_Spec(int w, int h, char color);
void Color_Spec(int index, char color);
void Color_Spec(int index,pixel const &color);

void operator+(Image const &a);
void operator-(Image const &b);
void operator/(Image const &b);
void operator=(Image const &b);
bool operator==(Image const &b);
bool operator!=(Image const &b);` 

Braking Up Each Basic Method,Explanation

Initiate Pixel Matrix Use: MyImage.init_pixel_matrix(); By Default SIPL loads your image data as uint8_t data into an unsigned char 1d array,if you desire to work or manipulate your image using matrix operations/products you would want to convert all the image data into a matrix, thus the init_pixel_matrix method comes to play. Note: Many methods construct the pixel matrix as part of there algorithm so you do not need to worry about initiating it manually if you are working with built in functionality .

Information Retrieval Use: int image_A_Width = MyImage.getWidth();

`int image_A_Height = MyImage.getHeight();`

`MyImage.getPixelCopy(H, W, tempPixel);`

`MyImage.Get_Center(Cx,Cy);`

The methods above are quit self explanatory ,GetWidth() returns current object width, GetHeight() returns current object image height , getPixelCopy() ,takes as argument a coordinate,or and y,x if you will and a pixel object , it passes by reference all the pixel data from the coordinate passed ,or in other words it takes the pixel in the argument and copies all the data from the pixel in the coordinate position to the passed pixel. Get_Center(),takes as argument two ints the will be modified by reference to the center x and y of the image.

Loading Blank Canvas

Instead of loading an image data from drive you can always create a blank canvas. Use: MyImage.Load_Blank_Canvas(500, 500, palette.Yellow); The above call will load an image to you object which will be a 500x500 yellow background canvas.

Printing Pixel Data To Console(NOT RECOMMENDED ON LARGE IMAGES)

Use; MyImage.printImdata();

The above method will print to console a matrix of char ,r is means it is a red pixel, b means its a blue pixel, g means green , B means black ,W means white ,and M means not rgbBW color, when working with small images it is easy to debug and check colors at each position of the images.

User Prompt Drawing

Use: MyImage.Manual_Draw();

calling this method prompts the user to use the arrow keys inorder to draw on loaded image\canvas it is not recomended for large images or canvas sizes as for the interface is being displayed on the consle window and large images will cause the console to shift values as for lack of space.

Useage: arrow key to navigate accross pixels; press 'e' when the selector '[]', is on the disierd pixel.

Insure that the selctor changed into "input mode" , after hiting 'e', the selctor should go from '[]',to '_'.

choose the new color by pressing one of the registred color keys (r,g,b,G,B,W,Y) after pressing one of the color keys the selector should display that the edit was executed successfully and change from '_' to,'["Color_Pressed"]', example : []- press e, _ - press g, [g] <- color changed to green in the selected pixel.

Image Loading And Writing

Loading Use:

`MyImage.Load_Image();`

Or

`MyImage.Load_Image(const char *f_name);`

Using Load_Image without passing a file name as argument will prompt the user to input a file name. Load_Image() will load image binary data into Image object as well as images height width and channels.

Writing Use:

`MyImage.Write_Image();`

Or

`MyImage.Write_Image(const char *f_name);`

Similarly to Load_Image not passing a filename will prompt the user to input a save name for the file. Write_Images() save your current Image object data in .jpg format.

Pixel Manipulation You can change the color of any pixel easily after the pixel matrix is loaded by using:

`MyImage.Color_Spec(Pixel_Matrix[5][100].index_range,palette.Azure);`

The Pixel Object It is important to remember that the basis of our image are pixels,and similarly our Image object's Pixel_Matrix member uses a struct data type defined as "pixel". each pixel data type contains the following members:

• r - the level of red
• g - the level of green
• b - the level of blue
• index_range - the starting position of the color triplet in the unsigned char array
• analysis - an empty flag socket for algorithm markings

r,g,b are uint8_t type as they can only carry a value between 0 and 255 index_range and analysis are ints.

Image Operators

Each of the operators preforms the arithmetic equivalent between pixel of current and passed image.

`void operator+(Image const &a);
void operator-(Image const &b);
void operator/(Image const &b);
void operator=(Image const &b);
bool operator==(Image const &b);
bool operator!=(Image const &b);`

Drawing Functionality

SIPL offers shape and line plotting using the following methods:

Drawing Squares

The Square Drawing Methods takes as argument a center x and y also the square width and height and a color. Draw_Square method will draw the square around the center x and center y coordinate ,so keep in if the coordinate is close to image edges and the width or the height of the square surpass the image borders the drawing will be aborted and a message will show in console telling about the error . The Square Drawing method has multiple mod's which will be detailed shortly ,the one mod to keep in mind is the "Corners" mod which will draw a square between 2 given corners , an upleft corner x and y and a downright corner x and y. in which case when calling the Draw_Square() method when specifying "Corners" in the mode section keep in mind the center_x and center_y refer to the upleft corner of the square x and y ,and the s_width and s_height refer to the downright x and y of the square.

Usage Examples:

Drawing of a regular square 10x10 around the coordinates 250,350 line colored:

MyImage.Draw_Square(250,350, 10, 10, palette.Lime);

The Draw_Square() method can be also called by passing one of 3 mods:

• "Fill" - Normally the square is drawn hollow , when specifying "Fill" the square will be drawn full
• "Checkered" - the method will draw a checkered square (also you can pass another argument after the mod ,it will be the spaces between checkerboard squares inside the main square.
• "Corners " - as explained above this mod will draw a square not around a center position but between two corners.

Usage Example with mod specification:

MyImage.Draw_Square(250,250,35,35,palette.NavyBlue,"Fill");

Drawing Circles

The Draw_Circle() method takes as argument a center_x and center_y coordinate around which the circle will be drawn the radius of the circle and the circle color , this will result in a hollow circle , if you wish to draw a filled circle just specify "Fill" as argument after the color.

Usage Examples:

MyImage.Draw_Circle(512,512, 15,palette.Brown);

the above will result in a hollow circle brown circle sized by radius 15 where the center of the circle is 512x512.

MyImage.Draw_Circle(512,512, 15,palette.Brown,"Fill");

The above will the draw the same circle but this time it will be filled ,not hollow.

Drawing Lines

The Draw_Line() method takes as argument a start x and y coordinates and a target x and y coordinates and a color, the method will draw a line between the two coordinates in the specified color you can also pass the line width as an argument after the color .

Usage Example:

MyImage.Draw_Line(10,10, 50,10,palette.Green);

the above call will draw a lined from (10,10) to (50,10) colored green but similarly if needed you can use:

MyImage.Draw_Line(10,10, 50,10,palette.Green,2);

This will draw the same line but the line width is 2 now .

Text Drawing

Aside Shape Drawing SIPL also offer text and symbol drawing. the method Draw_Text() takes as argument x and y positions which will be the center of where the text will be printed, in other words if the center x and y are (500,500) and the text length is 8 ,4 of the characters will be drawn up to (500,500) and the second 4 will be drawn from (500,500) till the end of the passed string . that way it insures the text will always be centered around the passed coordinate.

Usage Example:

`MyImage.Draw_Text(250,250,"Test Text");`

The above will draw the passed string around the coordinate with default color black.

`MyImage.Draw_Text(250,250, "Test Text", palette.RoyalBlue);

the above will do the same but the color of the text will be of your choice.

Higher Functionality And Image Analysis

SIPL Supports multiple image manipulation and analysis methods ,many of which can provide data for higher algorithmic calculations data set increasing for your machine learning project . many of the methods allow you to do small to big changes on images in order to give your machine more learning experience without needing to find new images for you data set.

Higher Level Methods:

void Convert_Grayscale();

void Compress();

void Mark_Identical_Pixels(pixel const &Target);

void Mark_Identical_Pixels(Image &Source);

void Mark_Identical_Pixels(Image &Source, const char *mode);

void Write_Pixel_Difference(Image &Source);

void Write_Pixel_Difference(Image &Source, const char *mode, int min_diff);

void Mark_Different_Pixels(Image &Source);

void Mark_Different_Pixels(Image &Source, const char *mode);

void Mark_Different_Pixels(Image &Source, int const &Color_Treshold, int const &Distnace_Treshold, pixel const &frame_color);

void Write_ChannelGraph();

void Write_Channel(const char color);

void Shutdown_Channel(const char color);

void Flip180();

void Detect_Faces();

void Tresholding(const char *mode, int const &value, int const &alter);

void Edge_Detection();

void Edge_Detection(const int max_color_gap);

void Mark_Contour(const char color, const int max_color_gap);

void Feature_Matching(const int source_x, const int source_y);

void Pixel_Matrix_Multiplication(Image &b);

void Quarantine_Pixel(pixel const &sample, const float max_difference, const char *mode, const int Alter);

void Kronecker_product(Image &b, const char *mode, const int Alter);

void Image_Transpose(const int Alter);

void Draw_Text(const int center_y, const int center_x, const char *text);

void Draw_Text(const int center_y, const int center_x, const char *text, const char color);

void Draw_Text(const int center_y, const int center_x, const char *text, pixel const &color);

void Figure_Detection(int const &blob_distance_treshold, int const &color_distance_treshold);`

Braking Up The Methods, Examples and Instructions

Convert Image Into Grayscale

Usage:

MyImage.Convert_Grayscale();

The method will convert and alter the image data loaded to object into the equivalent grayscale image.

Example:

Image Compression

Usage:

`MyImage.Compress();`

Method performs a check if and in what level the image pixel could be compressed then the method prompts the user to select a level of compression and saves the compressed image to project diractory as well as modifying image data inside the carrying object itself. image is saved in diractory as "Compressed.jpg"

example: before:

after:

Pixel Compare

SIPL offer multiple comparison methods between two images.

• Marking all identical pixels in comparison with an pixel object Note: lets say you used GetPixelCopy() and sampled a pixel form image B into a pixel object named temp, you can now compare that pixel with multiple images by calling this method. Usage: MyImage.Mark_Identical_Pixels(tempPixel);

This will compare all the pixels between the loaded image and the sample pixel and draw a small square around each pixel which is identical to the sample pixel.

• Marking all identical pixels in comparison between the image and another image

Usage: MyImage.Mark_Identical_Pixels(SeconedImage);

This will compare all the pixels between the two images and draw a small square around each pixel which is identical in the two images.

Pixel Difference

The Write_Pixel_Difference() Method takes as argument an image to compare with ,preferably the same image but with some changes ,the "Copy" command as a const string and a min value of difference needed in order for 2 pixels count as different,the method will write a new black image with red spots ,the red spots are the exact location of the differences in the two images .

Usage: MyImage.Write_Pixel_Difference(SecondImage,"Copy", 15);

leaving the method call with just another image will result in an image inside the project directory which will only color red the Area and shape of the different pixels; image will be saved as Pixel_Diffrence.jpg inside project diractory.

example:

Here are two images with some differences between them.

Image1:

Image2:

After Running the difference writing algorithm:

Difference Marking

Similar To Difference Writing this methods will mark the differences on the image itself modifying it.

Usage Example:

`MyImage.Mark_Different_Pixels(SecondImage);`

The above is similar to Write_Difference() but instead of creating a new image of the difference it marks it on the calling object's image data.

there is another overload of this function which will also take as argument a color_threshold which will be the maximum difference allowed before the pixels are called different and a distance threshold which specify how far the pixels need to be to count as different objects in the image ,the function will group different pixels and draw a square around each group ,again the grouping size is decided by the distance threshold. and lastly a color for the squares the will be around the difference area.

`MyImage.Mark_Different_Pixels(SecondImage, 15, 50, palette.Blue);`

Image Channel Analysis

SIPL offers the user either to write an image of 3 graphs ,to project directory ,the 3 graphs in the image represent the average r,g,b level in each line of the image,the x axis of the graph is the line number and the y axis is the average value of the corresponding color in the image

Usage:

`MyImage.Write_ChannelGraph();`

• You Can also wright to project directory only one of the image channels by calling the Write_Channel() method and passing as argument the selected channel as a char ,'r','g' or 'b'.

Usage:

`MyImage.Write_Channel(const char color);`

• Lastly you can shutdown one of the channels in your image if needed thus making sure your image has a value of 0 in the selected channel.

Usage: MyImage.Shutdown_Channel(const char color);

Image Augmentation

The Flip180() method is quit self explanatory ,calling this method will flip the image 180 degrees

Usage: MyImage.Flip180();

SIPL offers two mods of Threshold

• "Trunc" - which will compare each pixel to the passed value argument and if one of the channels in grater then the value that pixels will be truncated meaning it will become black , any pixel smaller in value will become white.

• "EdgeTriggred" - this mod will compare every 2 adjacent pixels and if the distances between them is higher then passed value argument that pixel will be colored white ,if the distances is equal or smaller then the value passed the pixel will be black , that way the threshold process is sensitive to edges in picture and result in an edge triggered threshold

Lastly the alter argument as in any of the methods who require it ,if equal to 1 the method will not only change the Pixel_Matrix values of the object but also the image data itself .

Usage:

`MyImage.Tresholding("Trunc",25,0);`

Matrix Operations

SIPL offers the user multiple matrix arithmetic operations on the Pixel_Matrix in each image

• Kronecker's Product

Usage: MyImage.Kronecker_product(Image &b, const char *mode, const int Alter);

Method converts both images to matrices and preforms Kronecker multiplication between all pixel creating a new image loaded to the matrix part of object. if alter arguemnt will be passed as one the pixel data of the image itself holded in object will be alterd as well as the height and width.

please keep in mind Kronecker product takes Image A an m × n Image and B is a p × q Image , Kronecker product will create a new image A ⊗ B that will be: the mp × nq of oiginal A and B, meaning if you use to images 100x100 pixels , the new image created will be 10,000x10,000 pixel and the weight of the image will be corresponding. also please keep in mind there is a maximum an jpg can carry , the maximum is 65,535×65,535 pixels. processing time may vary from 1 to 6 minutes depending on both image sizes.

the method contains 4 mode;

1. "Mul" - method will preform a simple ,classic Kronecker multiplication
2. "Size" - method will create a Kronecker Product where the biggest pixels is selected each iteration
3. "Build_From" - method will construct calling objects images using passed by argument image (as shown in example)
4. "Mix" - method will mix between the pixel of both images creating the Kroneckers Product of the pixel mixture ;

example: Image A:

Image B:

"Build From" Result:

• Matrix Cartesian Product

Keep in mind the calling object will be altered with the result of the multiplication ,the height and the width as well as the image data will be modified

Usage: MyImage.Pixel_Matrix_Multiplication(Image &b);

• Matrix Transpose Calling The Image_Transpose() method will flip rows and the columns of the matrix turning the image diagonally

Usage: MyImage.Image_Transpose(const int Alter);

Image Analysis

• Face Detection(Alpha Version)

Usage:

`MyImage.Detect_Faces();`

Method scans image pixels and tries to detect and mark faces with a red square if #define FaceDebug is defined then it will also mark and print in console all the verification steps taken when the algorithm tries to recognize if it is looking at a face or not. the algorithm uses real time data without comparing to eigenface or templates from memory nor any kind of AI.

Examples :

*Image Segmentation

Usage: MyImage.Image_Segmentation(3, 200, 1);

The method takes as arguments 3 integer values,int const &k, int const &iterations, int const &alter, the first one is the amount of segments the algorithm will divide the image into , the number of iterations the machine learning algorithm will iterate before deciding the segments , the higher the number the longer it will take to compute but the more accurate the result will be,and lastly an alter value that is no different then any other method ,if passed 1 as alter argument the image data will be modified ,any other number wont change the method functionality and only the pixel matrix of the Image object will be edited.

Examples:

Original Image:

Segmentation Using K = {2,3,4,5,8,16} -

• Getting Average Color Palette

Useage:

MyImage.Write_Average_Color_Palette(8);

The method takes an integer as argument ,depending on the value the method will use machine learning in order to find the passed value amount of dominant colors in the image , the method will output a .jpg image representing the average color palette of the image loaded on objects memory.

Examples:

Original Image:

Palettes of images 4,8 and 16 average colors:

4: 8: 16:

• Edge Detection

Usage:

`MyImage.Edge_Detection();`

method runs trough image data and modifying the loaded data in object in a way where only the edges of the image remain colored in white. the passed argument is the maximum color gap allowed between pixels. the higher the number the more loose the algorithm will treat pixel difference.

example:

after method is called:

• to mark the Contour of an images without blacking the rest of the pixels .

Use:

`MyImage.Mark_Contour(const char color, const int max_color_gap);`

Example:

• Feature_Matching

Usage:

`MyImage.Feature_Matching(const int source_x, const int source_y);`

method takes a sample from the pixel located at passed by argument coordinates , runs trough images data in order to find the same pixel in side the image. its not enough for a pixel to have the same color it also needs to have the same surrounding,meaning it will only mark the pixel that is identical to the one selected (if there is one such) in the example i copied a the same image with some small differences . you can see the algorithms marks in blue_red circles the matching pixels(the ones located in the position passed by argument). the algorithm connects the identical pixels with a blue line.

example:

• Pixel Quarantine

the Quarantine_Pixel() method takes a pixel as a sample , a maximum allowed difference between 2 pixels and one of 2 mods

• "Keep_Self" - All the similar pixels will be kept and all the different ones will be blacked
• "Drop_Self" - all the similar pixels will be blacked ;

NOTE: as with every function that takes an int argument "alter" if 1 is passed the image data itself will be modified if anything but 1 is passed only the pixel matrix will be modified

Usage:

`MyImage.Quarantine_Pixel(pixel const &sample, const float max_difference, const char *mode, const int Alter);`

Example: in the examples below the selected pixel to quarantine is a red pixel.

Original Image:

Keep_Self Example:

Drop_Self Example:

• Figure_Detection(Alpha Version)

This Method takes as argument a distance threshold value ,a color threshold value , and the hardness of the thresholding method explained above , the color distance indicates how different pixels needs to be to count as different ,and the distance threshold value is the distances that if 2 similar pixel share they are group as one object .

Usage:

`MyImage.Figure_Detection(int const &blob_distance_treshold, int const &color_distance_treshold,int const &Thresholding_level);`

Examples: