n8n-nodes-image-aspect-ratio-cropper

An n8n community node for cropping images to exact aspect ratios using center-cover mode. Mathematically precise algorithm ensures pixel-perfect output.

Features

• 🎯 Pixel-Perfect Cropping — Integer-based algorithm guarantees exact aspect ratio output
• 📐 Flexible Ratios — Supports any custom ratio (e.g., 16:9, 1:1, 4:3, 7:5)
• 🖼️ Multiple Formats — JPEG, PNG, WebP, GIF, TIFF, SVG support
• ⚡ Smart Detection — Automatically skips cropping if image already matches target ratio
• 🔄 Batch Processing — Process multiple images in a single execution
• 📊 Rich Metadata — Returns detailed crop information for downstream nodes
• 💡 Expression Support — Dynamic aspect ratio via n8n expressions

Installation

n8n Community Nodes (Recommended)

1. Go to Settings → Community Nodes
2. Select Install
3. Enter n8n-nodes-image-aspect-ratio-cropper
4. Agree to the risks and select Install

Self-hosted n8n

cd ~/.n8n/custom
npm install n8n-nodes-image-aspect-ratio-cropper

Restart n8n after installation.

Operations

This node provides a single operation: crop images to a specified aspect ratio using center-cover mode.

Parameters

Aspect Ratio

The aspect ratio parameter accepts any valid W:H format and supports n8n expressions:

// Static values
16:9
1:1
4:3

// Dynamic from previous node
{{ $json.aspectRatio }}

// Conditional expression
{{ $json.platform === 'instagram' ? '4:5' : '16:9' }}

Common Ratios:

Supported Formats

Output

Binary Data

The cropped image is returned in the specified binary property with an auto-generated filename:

original_16x9.jpg

JSON Metadata

{
  "aspectRatio": "16:9",
  "cropped": true,
  "originalWidth": 1920,
  "originalHeight": 1440,
  "croppedWidth": 1920,
  "croppedHeight": 1080,
  "positionX": 0,
  "positionY": 180,
  "scale": 120,
  "message": "Image successfully cropped to 16:9 aspect ratio."
}

How It Works

Center-Cover Algorithm

The node uses a mathematically precise integer-based algorithm:

1. Ratio Comparison — Uses cross-multiplication to avoid floating-point errors:

   width × ratioH === height × ratioW
   

2. Scale Calculation — Finds the largest integer scale that fits within the original dimensions

3. Center Positioning — Calculates exact pixel positions to center the crop area

4. Guaranteed Precision — Output dimensions are always exact multiples of the target ratio

Example

Cropping a 1920×1440 image to 16:9:

Original: 1920 × 1440
Target: 16:9

Is wider? 1920 × 9 > 1440 × 16 → 17280 > 23040 → No (taller)

Scale = floor(1920 / 16) = 120
CropWidth = 120 × 16 = 1920
CropHeight = 120 × 9 = 1080

PositionX = (1920 - 1920) / 2 = 0
PositionY = (1440 - 1080) / 2 = 180

Result: 1920×1080 cropped from position (0, 180) ✓

Example Workflows

Basic Usage

[HTTP Request] → [Image Aspect Ratio Cropper] → [Write Binary File]
                        ↓
              aspectRatio: "16:9"
              outputFormat: "jpeg"
              jpegQuality: 85

Dynamic Ratio from Data

[Webhook] → [Image Aspect Ratio Cropper] → [S3 Upload]
                    ↓
          aspectRatio: {{ $json.ratio }}

Multi-Platform Export

                    ┌→ [Cropper: 1:1] → [Instagram]
[Read Binary Files] ├→ [Cropper: 16:9] → [YouTube]
                    └→ [Cropper: 9:16] → [TikTok]

Use Cases

• AI Image Generation — Pre-process images for AI models requiring specific aspect ratios
• Social Media Automation — Batch crop images for different platforms
• E-commerce — Standardize product images to consistent dimensions
• Video Production — Generate thumbnails and cover images
• Photography Workflows — Crop photos for print sizes

Compatibility

Platforms: Linux, macOS, Windows

Development

# Clone repository
git clone https://github.com/LinkAIBrain/n8n-nodes-image-aspect-ratio-cropper.git
cd n8n-nodes-image-aspect-ratio-cropper

# Install dependencies
npm install

# Build
npm run build

# Lint
npm run lint

# Local testing
npm link
cd ~/.n8n/custom
npm link n8n-nodes-image-aspect-ratio-cropper
# Restart n8n

Dependencies

License

MIT

Resources

• n8n Community Nodes Documentation
• sharp Documentation