# ImageScaleToFit

## Syntax

```
ImageScaleToFit( name, size [, interpolation] )
ImageScaleToFit( name, width, height [, interpolation] )
```

Or as a member:

```
someImage.scaleToFit( size [, interpolation] )
someImage.scaleToFit( width, height [, interpolation] )
```

## Arguments

| Name          | Type   | Required | Default  | Description                                                                       |
| ------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------- |
| name          | any    | Yes      |          | The image to scale. Can be a `BoxImage` object or image name.                     |
| size          | any    | Yes\*    |          | Single dimension to fit. Scales to fit this width while maintaining aspect ratio. |
| width         | any    | Yes\*    |          | Maximum width. Image fits within these dimensions maintaining aspect ratio.       |
| height        | any    | Yes\*    |          | Maximum height. Image fits within these dimensions maintaining aspect ratio.      |
| interpolation | String | No       | bilinear | The interpolation method: "bilinear" (default), "nearest", "bicubic".             |

\* Either provide a single `size` parameter OR both `width` and `height` parameters.

## Returns

`BoxImage` — The scaled image object.

## Description

Scales an image to fit within specified dimensions while maintaining the aspect ratio. This function is intelligent about sizing:

* **Single parameter**: Fits the image to the specified width, maintaining aspect ratio
* **Two parameters (width, height)**: Fits the image within a rectangular boundary, maintaining aspect ratio (the image will be as large as possible without exceeding either dimension)

The image is never stretched or distorted - aspect ratio is always preserved.

## Example

```boxlang
// Scale image to fit width 400 (height adjusts automatically)
result = ImageScaleToFit( myImage, 400 );

// Scale image to fit within 800x600 bounds
result = ImageScaleToFit( myImage, 800, 600 );

// Scale with custom interpolation
result = ImageScaleToFit( myImage, 400, "bicubic" );

// As a member function (recommended)
myImage.scaleToFit( 600 );
myImage.scaleToFit( 800, 600, "bilinear" );
```

## Interpolation Methods

* `bilinear` - Good balance of speed and quality (default)
* `nearest` - Fastest, lowest quality (pixelated)
* `bicubic` - Highest quality, slowest

## Related BIFs

* ImageResize
* ImageCrop
* ImageRotate

## Notes

* The `name` argument can be a `BoxImage` object or the name of an image variable in the current context.
* The aspect ratio is always preserved - the image is never stretched or distorted.
* For a 500x300 image calling `scaleToFit(400, 600)`: result is 400x240 (width constrained)
* For a 300x500 image calling `scaleToFit(400, 600)`: result is 360x600 (height constrained)
* The operation modifies the image in place when used as a member function.
* Returns the modified image object for chaining or further processing.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/modularity/image-manipulation/reference/built-in-functions/imagescaletofit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.