# orx-image-fit

Draws an image ensuring it fits or covers the specified `Rectangle`.

Similar to CSS object-fit (https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit)

`orx-image-fit` provides the `Drawer.imageFit` extension function.

## Usage

```kotlin
drawer.imageFit(
  img: ColorBuffer, 
  x: Double, y: Double, w: Double, h: Double, 
  horizontalPosition: Double, 
  verticalPosition: Double,
  fitMethod: FitMethod)
```

or 

```kotlin
drawer.imageFit(
  img: ColorBuffer, 
  bounds: Rectangle, 
  horizontalPosition: Double, 
  verticalPosition: Double,
  fitMethod: FitMethod)
```

- `img`: the image to draw 
- `x`, `y`, `w`, `h` or `bounds`: the target area where to draw the image
- `fitMethod`: 
  - `FitMethod.Contain`: fits `img` in the target area. If the aspect ratio of `img` and `bounds` differ it leaves blank horizontal or vertical margins to avoid deforming the image.
  - `FitMethod.Cover`: covers the target area. . If the aspect ratio of `img` and `bounds` differ part of the image will be cropped away.
  - `FitMethod.Fill`: deforms the image to exactly match the target area.
  - `FitMethod.None`: draws the image on the target area without scaling it.
- `horizontalPosition` and `verticalPosition`: controls which part of the image is visible (`Cover`, `None`) or the alignment of the image (`Contain`). 
  - `horizontalPosition`: `-1.0` = left, `0.0` = center, `1.0` = right.
  - `verticalPosition`: `-1.0` = top, `0.0` = center, `1.0` = bottom.

## Examples
 
A quick example that fits an image to the window rectangle with a 10 pixel margin. By default
`imageFit` uses the cover mode, which fills the target rectangle with an image.
  
```kotlin
fun main() = application {
    program {
        val image = loadImage("data/images/pm5544.png")
        extend {
            drawer.imageFit(image, 10.0, 10.0, width - 20.0, height - 20.0)
        }
    }
}
``` 

or

```kotlin
fun main() = application {
    program {
        val image = loadImage("data/images/pm5544.png")
        extend {
            drawer.imageFit(image, drawer.bounds.offsetEdges(-10.0))
        }
    }
}
```

<!-- __demos__ -->
## Demos
### DemoImageFit01

This program uses `drawer.imageFit()` to draw images using nested grid layout.
The main grid features 4 columns for the `Cover`, `Contain`, `Fill` and `None` fit methods,
and two rows for portrait and landscape images.
Each of those 8 cells feature a 3x3 grid, with cells combining `left`, `center` and `right` alignment
with `top`, `center` and `bottom` alignment.

The image drawn in each cell is a simple image with a white background and two touching circles:
a pink one and a gray one. In some of the cells part of this image is cropped out (due to the fit method used).
In other cells the image does not fully cover the available area, revealing a dark gray background.

![DemoImageFit01Kt](https://raw.githubusercontent.com/openrndr/orx/media/orx-image-fit/images/DemoImageFit01Kt.png)

[source code](src/jvmDemo/kotlin/DemoImageFit01.kt)

### DemoImageFitSub01

Demonstrates the `imageFitSub()` method, which allows specifying not only a target `Rectangle`,
but also a source `Rectangle`, which is used to set the area of the original image we want to fit
into the target.

The program also demonstrates the `Rectangle.uniformSub` method, which returns a random sub-rectangle
taking into consideration the minimum and maximum width and height arguments.

Notice the trick used to generate unique random results changing only once per second by using
the current seconds as an integer seed.

![DemoImageFitSub01Kt](https://raw.githubusercontent.com/openrndr/orx/media/orx-image-fit/images/DemoImageFitSub01Kt.png)

[source code](src/jvmDemo/kotlin/DemoImageFitSub01.kt)