Skip to content

Masks and Shape Effects

Apply masking effects to create shaped images, rounded corners, and creative cropping.

Parameters

mask

Apply predefined mask shapes to images.

Type: string
Values: ellipse, corners
Default: None (no masking)

corner_radius

Specify corner radius for rounded corner masking.

Type: float
Range: 0+ pixels
Default: 0 (no rounding)
Required when: mask=corners

mask_bg

Background color for areas outside the mask.

Type: string (color value)
Default: transparent

Usage

Ellipse Masking

image.jpg?mask=ellipse
Create circular/elliptical crop.

image.jpg?w=200&h=200&fit=crop&mask=ellipse
Perfect circle crop for profile pictures.

Rounded Corners

image.jpg?mask=corners&corner_radius=20
Add 20px rounded corners.

image.jpg?mask=corners&corner_radius=50&mask_bg=white
Heavy rounding with white background.

Combined with Sizing

image.jpg?w=300&h=300&fit=fill&mask=ellipse&mask_bg=#F0F0F0
Square-to-circle conversion with gray background.

Masking Guide

Ellipse Masking

Creates circular or oval crops: - Square images: Perfect circles - Rectangular images: Elliptical crops - Common use: Profile pictures, avatars, medallion effects - Background: Transparent by default

Corner Radius Masking

Rounds the corners of rectangular images: - Small radius (5-15px): Subtle modern look - Medium radius (15-30px): Noticeable rounding - Large radius (30px+): Heavily rounded, pill-shaped - 50% of smallest dimension: Creates ellipse effect

Background Considerations

  • Transparent: Best for overlaying on other content
  • White: Clean, professional appearance
  • Colored: Match your design scheme
  • Consider final usage context

Use Cases

Profile Pictures

avatar.jpg?w=150&h=150&fit=crop&crop=faces&mask=ellipse
Perfect circular avatar with face detection.

Product Showcase

product.jpg?w=400&h=400&fit=fill&mask=corners&corner_radius=25&mask_bg=white
Rounded product display with clean background.

UI Elements

thumbnail.jpg?w=80&h=80&fit=crop&mask=corners&corner_radius=12
Modern thumbnail with subtle rounding.

Social Media

story.jpg?w=400&h=600&mask=corners&corner_radius=30&brightness=10
Instagram story format with rounded edges.

Badge/Medal Effects

award.jpg?w=200&h=200&fit=fill&mask=ellipse&border=5&border_color=gold
Circular badge with gold border.

Creative Applications

Vignette Effect

portrait.jpg?mask=ellipse&mask_bg=black&brightness=-10&contrast=20
Classic portrait vignette.

Modern Card Design

card.jpg?w=300&h=200&mask=corners&corner_radius=20&pad=15&bg=white&border=1&border_color=#E0E0E0
Card-style presentation with multiple effects.

Icon Preparation

icon.jpg?w=128&h=128&fit=fill&mask=corners&corner_radius=28&bg=transparent
iOS-style app icon preparation.

Floating Elements

element.jpg?mask=ellipse&pad=20&bg=rgba(255,255,255,0.9)&rot=5
Floating circular element with soft background.

Processing Order

Masking is applied after other transformations: 1. Resize/crop operations 2. Color/effect adjustments
3. Geometric transformations 4. Mask application 5. Background fill (if specified)

Advanced Techniques

Profile Picture Pipeline

profile.jpg?w=200&h=200&fit=crop&crop=faces&brightness=5&contrast=15&mask=ellipse&border=3&border_color=white

Product Card Design

product.jpg?w=250&h=250&fit=fill&pad=20&bg=white&mask=corners&corner_radius=15&border=1&border_color=#DDD

Social Media Branding

brand.jpg?w=400&h=400&mask=corners&corner_radius=40&wm_url=/logo.png&wm_pos=southeast&wm_opacity=0.7

gallery.jpg?w=150&h=150&fit=crop&mask=corners&corner_radius=8&brightness=5&saturation=10

Best Practices

Profile Pictures

  • Use square dimensions with ellipse mask for perfect circles
  • Combine with face detection cropping for optimal results
  • Consider border effects for definition
  • Transparent backgrounds work best for flexibility

UI Integration

  • Match corner radius to your design system
  • Use consistent masking across similar elements
  • Consider hover/focus states in your implementation
  • Test across different background colors

Performance

  • Masking operations are GPU-accelerated
  • Results are cached globally
  • Complex masks may slightly increase processing time
  • Transparent backgrounds may increase file size

Accessibility

  • Ensure sufficient contrast between masked content and background
  • Consider how masking affects important visual information
  • Test with screen readers if images convey important information

Examples by Application

E-commerce

product.jpg?w=300&h=300&fit=fill&mask=corners&corner_radius=12&bg=white&pad=15

Team Pages

team.jpg?w=200&h=200&fit=crop&crop=faces&mask=ellipse&brightness=8&contrast=12

Portfolio Galleries

portfolio.jpg?w=250&h=200&fit=crop&mask=corners&corner_radius=15&saturation=15

App Screenshots

screenshot.jpg?w=300&h=600&mask=corners&corner_radius=35&pad=20&bg=#F8F8F8

Logo Preparation

logo.jpg?w=150&h=150&fit=fill&mask=corners&corner_radius=20&bg=transparent

Troubleshooting

Rough Edges

  • Ensure source image has sufficient resolution
  • Check that corner radius isn't too large for image dimensions
  • Consider anti-aliasing in your display context

Background Issues

  • Verify color format (hex, named, rgb)
  • Use 'transparent' keyword for alpha channel
  • Test final appearance against intended background

Size Considerations

  • Very small images may show pixelated curves
  • Large corner radius values may create unexpected shapes
  • Test mask effects at intended display sizes