---
title: "Focal Crop"
canonical: "https://docs.pbs.org/space/ITS/4423716/Focal%20Crop"
format: markdown
---
## Overview
Focal crop transform returns an image that is cropped from a user-specified focal point. Focal crop differs from [regular crop](https://pbs-docs.atlassian.net/wiki/spaces/ITS/pages/4423710) in that crop resizes from the center of the image while focal crop allows you to set the point from which cropping is focused so you aren't losing the most important of the image when cropping.
[Click here to learn how to resize without cropping](https://pbs-docs.atlassian.net/wiki/spaces/ITS/pages/4423729)
> ⚠️ **We recommend cropping to smaller dimensions. Requesting a larger size than the original results in compromised image quality.***** ***** **
## Parameters
| **Parameter** | **Description** |
| --- | --- |
| focalcrop | ITS will dynamically adjust an image to be cropped from a user-specified focal point.
Width and height of the bounding box and two focal point variables are required to use this feature. |
| no-scale-up | Prevents the image from upscaling beyond its original aspect ratio. Upscaling can increase encoding and load time, and also distort the image.
Note: If the `avif` format transformation is also applied, upscaling is automatically prevented, as this can lead to encoding time-outs. |
## How to use focal crop transform
ITS changes images by appending a [decorator](https://docs.pbs.org/space/ITS/4423734/Glossary#decorator) to the end of your original url string:
#### **Resize decorator format**
```
https://image.pbs.org/path/to/file.jpg?focalcrop=WWxHHxXXxYY
```
Where:
- focalcrop -- indicates that ITS should perform a crop
- WW -- a numerical pixel value representing the desired width of the output image
- HH -- a numerical pixel value representing the desired height of the output image
- XX -- the x axis of the focal point, represented as a percentage value of the width of the original picture
- YY -- the y axis of the focal point, represented as a percentage value of the height of the original picture
## How does ITS determine where to crop my image?
When using focalcrop, you must assign four values to the URL (in red below):
1. The final width and height you want the image to be (*http://image-staging.pbs.org/video-assets/mezzanine_960.jpg.focalcrop.**500x400**.50.100.jpeg*)
2. The point from which you want the image cropped (*http://image-staging.pbs.org/video-assets/mezzanine_960.jpg.focalcrop.**500x400**.**50.100**.jpeg*)
The point from where you want the image cropped is determined by the start point which is located in the very upper left corner of your image (Figure 1).
Figure 1
As an example:
- I want to resize my original image, which is 1920x1080, to 500x400 while keeping the focus on the two subjects in the photo. So I will put the new image dimensions in my URL (indicated in red): [https://image.pbs.org/video-assets/pbs/masterpiece/178811/images/mezzanine_960.jpg.focalcrop.](https://image.pbs.org/video-assets/pbs/masterpiece/178811/images/mezzanine_960.jpg.focalcrop.500x400.50.100.jpeg)[500x400](https://image.pbs.org/video-assets/pbs/masterpiece/178811/images/mezzanine_960.jpg.focalcrop.500x400.50.100.jpeg)[.50.100.jpeg](https://image.pbs.org/video-assets/pbs/masterpiece/178811/images/mezzanine_960.jpg.focalcrop.500x400.50.100.jpeg)
- I want to keep the subjects in the photo so I will make the focal point to 50% from the left side of the image [https://image.pbs.org/video-assets/pbs/masterpiece/178811/images/mezzanine_960.jpg.focalcrop.500x400.50.0.jpeg](https://image.pbs.org/video-assets/pbs/masterpiece/178811/images/mezzanine_960.jpg.focalcrop.500x400.50.0.jpeg) (Figure 2).
> ⚠️ **Width and height of the bounding box and two focal point variables are required to use this feature.**
Figure 2
## Live examples
#### Original image: [https://image.pbs.org/test/GmtpBa4-asset-mezzanine-16x9-Uu2CpNc.png](https://image.pbs.org/test/GmtpBa4-asset-mezzanine-16x9-Uu2CpNc.png)
| **Resize by:** | **Example URL** | **Dimensions returned** | **Image result** |
| --- | --- | --- | --- |
| 1000 x 400 | https://image.pbs.org/test/GmtpBa4-asset-mezzanine-16x9-Uu2CpNc.png?focalcrop=500x400x90x10 | 500x400x90x10 |  |
| 1000 x 400 | https://image.pbs.org/test/GmtpBa4-asset-mezzanine-16x9-Uu2CpNc.png?focalcrop=900x500x100x10[ ](http://image.pbs.org/demo/demo1.jpg.resize.200x.jpg) | 900x500x100x10 | ![image]() |
## How to Prevent Upscaling
The `no-scale-up` option can be included with a focalcrop transformation that will prevent the image from upscaling beyond its original aspect ratio. Upscaling can increase encoding and load time, and also distort the image.
Note: If the `avif` format transformation is also applied, upscaling is automatically prevented, as this can lead to encoding time-outs.
Examples of how an image URL can be constructed with the `no-scale-up` option:
- https://image.pbs.org/contentchannels/.png?focalcrop=2630x1500x50x10,no-scale-up
- https://image.pbs.org/contentchannels/.png?focalcrop=2630x1500x50x10,no-scale-up&format=jpg