Image Processing API

An API for processing images implemented as part of the Advanced Web Development Track offered by egFWD Initiative through Udacity.

This project was structured from scratch, with ZERO starter files.

Table of contents

• Image Processing API
• Table of contents
• Installation
• Development
  • Architecture
  • API Endpoints
    • 1. /api/resize?{queryParameters}
    • 2. /api/grayscale?{queryParameters}
    • 3. /api/threshold?{queryParameters}
    • 4. /api/negative?{queryParameters}
  • API Functionality
  • Installed NPM Packages
    • Production Packages
    • Development Packages
• Useful Resources

Installation

(Back to top)

To use this project, you need to follow the commands below:

1. Clone the repository into your local machine:

   git clone https://github.com/ibrahimelmokhtar/ts-image-processing-api.git

2. Redirect inside the cloned repository:

   cd ts-image-processing-api/

3. Install the required packages:

   npm install

4. For applying configured styling, run the following commands:

   • Prettier styling:

     npm run prettier

   • ESLint styling:

     npm run lint

5. For working on the development phase, run the following commands:

   • Live debugging while development:

     npm run server

   • Jasmine Testing:

     npm run test

6. For working with the production phase, run the following commands:

   • Build the project:

     npm run build

     Then, Run the compiled server:

     node build/server.js

   • OR simply, Start the server with one command:

     npm run start

7. Open the local website on http://127.0.0.1:5000/api/{processType}?{queryParameters}, more information about {processType} and {queryParameters} will be explained in API Endpoints

Development

(Back to top) This section will explain how the code works and how everything is put together.

Architecture

(Back to top)

This project has the structure shown below:

├─── images/
    ├─── encenadaport.jpg
    ├─── fjord.jpg
    ├─── icelandwaterfall.jpg
    ├─── palmtunnel.jpg
    ├─── santamonica.jpg
├─── spec/
    ├─── support/
        ├─── jasmine.json
├─── src/
    ├─── middlewares/
        ├─── validator.middleware.ts
    ├─── modules/
        ├─── dir-exists.ts
        ├─── img-collect-names.ts
        ├─── img-create-name.ts
        ├─── img-exists.ts
        ├─── process-grayscale.ts
        ├─── process-negative.ts
        ├─── process-resize.ts
        ├─── process-threshold.ts
    ├─── routes/
        ├─── api/
            ├─── grayscale.route.ts
            ├─── negative.route.ts
            ├─── resize.route.ts
            ├─── threshold.route.ts
        ├─── index.ts
    ├─── schemas/
        ├─── grayscale.schema.ts
        ├─── negative.schema.ts
        ├─── resize.schema.ts
        ├─── threshold.schema.ts
    ├─── server/
        ├─── server.config.ts
    ├─── tests/
        ├─── helpers/
            ├─── reporter.ts
        ├─── dir-exists.spec.ts
        ├─── img-collect-names.spec.ts
        ├─── img-create-name.spec.ts
        ├─── img-exists.spec.ts
        ├─── server.spec.ts
    ├─── server.ts
├─── .eslintrc
├─── .gitignore
├─── .prettierrc
├─── package.json
├─── README.md
├─── tsconfig.json

API Endpoints

(Back to top)

This API has FOUR endpoints using the GET method as explained below:

1. /api/resize?{queryParameters}

/api/resize?filename={value}&width={value}&height={value}

The user can pass a specific image name, desired width and desired height. After query validation, this API will use these parameters to apply resize operation on this image. queryParameters explained:

1. filename: specific image to be processed, with some specifications:
   • pass filename only, without any file extension.
   • the image MUST be in the images/ directory.
2. width: desired width of the processed image, with some specifications:
   • pass a number between 100 and 1000
3. height: desired height of the processed image, with some specifications:
   • pass a number between 100 and 1000

For example:

http://127.0.0.1:5000/api/resize?filename=encenadaport&width=500&height=800

This request will return an image encenadaport_resize_w500_h800 with .jpg as the file extension.

2. /api/grayscale?{queryParameters}

(Back to top)

/api/grayscale?filename={value}

The user can pass a specific image name. After query validation, this API will use this parameter to apply grayscale operation on this image. queryParameters explained:

1. filename: specific image to be processed. with some specifications:
   • pass filename only, without any file extension.
   • the image MUST be in the images/ directory.

For example:

http://127.0.0.1:5000/api/grayscale?filename=fjord

This request will return an image fjord_grayscale with .jpg as the file extension.

3. /api/threshold?{queryParameters}

(Back to top)

/api/threshold?filename={value}&threshold={value}

The user can pass a specific image name and desired threshold level. After query validation, this API will use these parameters to apply threshold operation on this image. queryParameters explained:

1. filename: specific image to be processed, with some specifications:
   • pass filename only, without any file extension.
   • the image MUST be in the images/ directory.
2. threshold: desired threshold level of the processed image, with some specifications:
   • pass a number between 0 and 255

For example:

http://127.0.0.1:5000/api/threshold?filename=palmtunnel&threshold=200

This request will return an image palmtunnel_threshold_th200 with .jpg as the file extension.

4. /api/negative?{queryParameters}

(Back to top)

/api/negative?filename={value}

The user can pass a specific image name. After query validation, this API will use this parameter to apply negative operation on this image. queryParameters explained:

1. filename: specific image to be processed. with some specifications:
   • pass filename only, without any file extension.
   • the image MUST be in the images/ directory.

For example:

http://127.0.0.1:5000/api/negative?filename=santamonica

This request will return an image santamonica_negative with .jpg as the file extension.

API Functionality

(Back to top)

1. Place images to be processed inside images/ directory with .jpg format.

   • NOTE:
     • The server will figure out the available images automatically.
     • Currently available images: encenadaport, fjord, icelandwaterfall, palmtunnel, and santamonica.

2. Call one of the available API endpoints with its query parameters.

3. Apply query validation rules on the called request.

   • If validation failed:
     • Send specific error back based on the failure type.

4. Construct processed image filename depending on the applied process.

5. Check out/ directory existence.

   • If not found:
     • Create an empty out/ directory.

6. Check the existence of a previously processed image with the same query parameters.

   • if found:
     • no additional processing will be applied.
   • if not found:
     • apply the desired processing operation on the original image.
     • Store processed image at out/ directory.

7. Send the processed image back as a response to the called request.

Installed NPM Packages

(Back to top)

These packages are required to run this project smoothly without any errors.

Production Packages

These packages can be found in the "dependencies" object inside the package.json file.

• express - Fast, unopinionated, minimalist web framework.
• express-validator - Express middleware for the validator module.
• sharp - High-performance Node.js image processing.

Development Packages

These packages can be found in the "devDependencies" object inside the package.json file.

• typescript - TypeScript is a language for application scale JavaScript development.
• ts-node - TypeScript execution environment and REPL for node.js, with source map support.
• nodemon - Simple monitor script for use during the development of a node.js app.
• prettier - Prettier is an opinionated code formatter.
• eslint - An AST-based pattern checker for JavaScript.
• eslint-config-prettier - Turns off all rules that are unnecessary or might conflict with Prettier.
• eslint-plugin-prettier - Runs prettier as an eslint rule.
• jasmine - CLI for Jasmine, a simple JavaScript testing framework for browsers and Node.
• jasmine-spec-reporter - Spec reporter for jasmine behavior-driven development framework.
• supertest - SuperAgent driven library for testing HTTP servers.

Useful Resources

(Back to top)

• Documentation: Prettier Options
• Documentation: ESLint Configuring Rules
• Documentation: Jasmine Module
• Documentation: Express-Validator Module
• Documentation: Sharp Module
• Youtube Video: Use Express-Validator Module with NodeJs
• Youtube Video: Use Sharp Module with NodeJs
• Article: How to use Code Blocks within Markdown Files