kontent-ai / kontent-ai/java-packages

Add support for image optimization

Open
#61 3 comments 0 reactions 0 assignees View on GitHub
groomed hacktoberfest help wanted up-for-grabs
Dominant language
Java
Stars
17
Forks
27
PR merge metrics
No merged PRs in 30d

Description

Kentico Cloud now supports image optimization. It gives developers the option of transforming images using URL parameters. The goal of this task is to implement a helper class that will make generation of image URLs easy for the developers.

The reference code can be observed in the [.NET SDK](https://github.com/Kentico/delivery-sdk-net/pull/113).

The full specification follows:

## Example
*Scale*
[image.jpg?mode=scale&width=300](http://res.cloudinary.com/dnbkywmu4/image/upload/c_scale,w_300/v1510122179/cafe04_r8ef4x.jpg)
[image.jpg?mode=scale&height=150](http://res.cloudinary.com/dnbkywmu4/image/upload/c_scale,h_150/v1510122179/cafe04_r8ef4x.jpg)
[image.jpg?mode=fit&height=150&width=300](http://res.cloudinary.com/dnbkywmu4/image/upload/c_fit,h_150,w_300/v1510122179/cafe04_r8ef4x.jpg)

*DPR*
[image.jpg?mode=scale&width=300&dpr=2.0](http://res.cloudinary.com/dnbkywmu4/image/upload/c_scale,w_300,dpr_2.0/v1510122179/cafe04_r8ef4x.jpg)

# Specification

If a developer provides a parameter with invalid value or omits a parameter that is required for desired optimization, the Asset API will either ignore this parameter, or return the original asset without any optimizations.

Also, to keep our sanity, we will transform each image optimization parameter independently from others. Yes, this approach might sometimes produce surprising results. However, both Fastly and imgix are designed to handle a set of parameters that do not make sense and we are not making the situation worse.

Regarding requests to the Asset API, the idea is to go through all parameters, transform the supported ones and get rid of everything else.

To get a grasp of the image optimization You can experiment with two identical images:

- https://kentico.imgix.net/src/image.jpg
- https://www.fastly.io/image.jpg

## rect=x,y,w,h (incompatible with crop)

|-|-|
|-|-|
| x is not float | Nothing |
| x < 0.0 | Nothing |
| y is not float | Nothing |
| y < 0.0 | Nothing |
| w is not float | Nothing |
| w <= 0.0 | Nothing |
| h is not float | Nothing |
| h <= 0.0 | Nothing |
| h <= 0.0 | Nothing |
| otherwise | crop=\{w\},\{h\},x\{x\},y\{y\} |

If the `rect` parameter is malformed, just ignore it.

## fit=crop&crop=focalpoint&fp-x=x&fp-y=y&fp-z=z (incompatible with rect)

|-|-|
|-|-|
| x is not float | set x as 0.5 |
| y is not float | set y as 0.5 |
| z is not float | Nothing |
| z <= 1.0 | Nothing |
| 1 / z < 1.0 | Nothing |
| otherwise | crop=\{1 / z\},\{1 / z\},offset-x\{(x * z - 0.5) / (z - 1)\},offset-y\{(y * z - 0.5) / (z - 1) * 100\} |

Both offset-x and offset-y must be clamped into range from 0 to 100.

imgix supports crop by both rectangle and focal point. Unfortunately, it is not so easy to calculate Fastly parameters. Therefore, let's declare the `rect` parameter more important. So, if both crop by rectangle and focal point are specified, choose the first.

## fm=x

|-|-|
|-|-|
| x = gif | format=gif |
| x = png | format=png |
| x = png8 | format=png8 |
| x = jpg | format=jpg |
| x = pjpg | format=pjpg |
| x = webp | format=webp |
| otherwise | Nothing |

## fm=webp&lossless=x

|-|-|
|-|-|
| x = 1 | format=webpll |
| x = true | format=webpll |
| x = 0 | format=webply |
| x = false | format=webply |
| otherwise | format=webp |

## q=x

|-|-|
|-|-|
| x is not float | Nothing |
| otherwise | quality=\{x}\ |

## auto=x

|-|-|
|-|-|
| x = format | auto=webp |
| otherwise | Nothing |

[Local variables](https://docs.fastly.com/guides/vcl/local-variables-in-vcl) and [related functions](https://docs.fastly.com/guides/vcl/miscellaneous-VCL-extensions#functions) will be required to transform parameters.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the Java SDK structure and the linked .NET SDK pull request for the corresponding image-optimization helper. Use the parameter specification in this issue as the behavior checklist, and add coverage for each supported transformation and invalid-input case before confirming generated URLs match the expected results.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.