​
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