​

Image Cropping Transformations

​

Crop Modes

Control how your image is cropped using the c_{mode} parameter. Each mode handles dimensions differently:

​

crop - Exact Dimensions

Crops the image to exactly match the specified dimensions, removing excess pixels.

tr-w_500,h_300,c_crop

• Best for: Fixed-size containers where exact dimensions are required
• Behavior: May remove parts of the image to achieve exact size
• Example use: Profile pictures, thumbnails
• Supports smart cropping with gravity controls

​

fill - Smart Resize and Crop

Resizes the image to fill the specified dimensions while maintaining aspect ratio, then crops excess pixels.

tr-w_800,h_600,c_fill

• Best for: Hero images, featured content
• Behavior: Ensures entire space is filled without distortion
• Example use: Blog post headers, product featured images
• Supports smart cropping with gravity controls

​

fit - Preserve Content

Resizes image to fit within specified dimensions while maintaining aspect ratio, with no cropping.

tr-w_400,h_300,c_fit

• Best for: Product images, artwork
• Behavior: May leave empty space on sides or top/bottom
• Example use: Product galleries, image collections

​

scale - Simple Resize

Basic resize that may change aspect ratio to match exact dimensions.

tr-w_500,h_300,c_scale

• Best for: When aspect ratio isn’t critical
• Behavior: May stretch or compress image
• Example use: Background patterns, non-critical images

​

limit - Downscale Only

Only scales down images that are larger than specified dimensions.

tr-w_800,h_600,c_limit

• Best for: User-uploaded content
• Behavior: Never enlarges small images
• Example use: Forum attachments, user galleries

​

pad - Add Padding

Resizes within dimensions and adds padding to reach exact size.

tr-w_400,h_400,c_pad,b_ffffff

• Best for: Consistent layouts requiring exact dimensions
• Behavior: Adds padding to maintain aspect ratio
• Example use: Product grids, image galleries

​

Gravity Control

Use g_{position} to control the focal point during cropping. Only works with crop and fill modes:

​

Standard Positions

tr-c_crop,g_center        # Default
tr-c_crop,g_north        # Top center
tr-c_crop,g_south        # Bottom center
tr-c_crop,g_east         # Right center
tr-c_crop,g_west         # Left center
tr-c_crop,g_north_east   # Top right
tr-c_crop,g_north_west   # Top left
tr-c_crop,g_south_east   # Bottom right
tr-c_crop,g_south_west   # Bottom left

​

Smart Gravity

Available for crop and fill modes:

tr-c_crop,g_face         # Focus on detected face
tr-c_crop,g_faces        # Focus on multiple faces
tr-c_crop,g_object:car   # Focus on detected object

​

Supported objects

We currently support the following objects:

• airplane
• apple
• backpack
• banana
• baseball bat
• baseball glove
• bed
• bench
• bicycle
• bird
• boat
• book
• bottle
• bowl
• broccoli
• bus
• cake
• car
• carrot
• cat
• cell phone
• chair
• clock
• couch
• cow
• cup
• dining table
• dog
• donut
• elephant
• fire hydrant
• fork
• frisbee
• giraffe
• hair drier
• handbag
• horse
• hot dog
• keyboard
• kite
• knife
• laptop
• microwave
• motorcycle
• mouse
• orange
• oven
• parking meter
• person
• pizza
• potted plant
• refrigerator
• remote
• sandwich
• scissors
• sheep
• sink
• skateboard
• skis
• snowboard
• spoon
• sports ball
• stop sign
• suitcase
• surfboard
• teddy bear
• tennis racket
• tie
• toaster
• toilet
• toothbrush
• traffic light
• train
• truck
• tv
• umbrella
• vase
• wine glass
• zebra