Median Filter

Apply median filter to reduce image noise while preserving edges. The median filter is particularly effective at removing salt-and-pepper noise, scanner artifacts, and compression noise without blurring edges like traditional blur filters.

Installation

To install the Image plugin:

Terminal
$ npm install -g @mediaproc/image

Usage

Terminal
$ mediaproc image median <input> [options]

Basic Usage

# Apply default median filter (size 3)
mediaproc image median photo.jpg

# Custom filter size
mediaproc image median noisy-image.png -s 5

# Specify output location
mediaproc image median scan.jpg -s 7 -o cleaned-scan.jpg

# Preview without executing
mediaproc image median photo.jpg --dry-run

Options

OptionAliasTypeDefaultDescription
--size <size>-snumber3Filter size (1-50) - higher values = more smoothing
--output <path>-ostring<input>-median.<ext>Output file path
--quality <quality>-qnumber90Output quality (1-100) for lossy formats
--dry-runbooleanfalseShow what would be done without executing
--verbose-vbooleanfalseShow detailed processing information
--helpbooleanfalseDisplay help information

How Median Filter Works

The median filter replaces each pixel with the median value of neighboring pixels within a defined window:

  1. Window Selection: For each pixel, a square window of size N×N is selected
  2. Sort Values: All pixel values within the window are sorted
  3. Median Calculation: The middle (median) value is selected
  4. Replacement: The center pixel is replaced with this median value

This process effectively removes outlier pixels (noise) while preserving edges better than averaging filters.

Filter Size Guide

  • Size 1: Minimal smoothing, preserves maximum detail
  • Size 3: Default - balanced noise reduction with edge preservation
  • Size 5-7: Strong noise reduction, suitable for heavily noisy images
  • Size 10+: Heavy smoothing, may blur fine details

Examples

1. Basic Noise Reduction

Remove typical digital noise from a photo:

mediaproc image median photo.jpg

Result: Applies size-3 filter, outputs photo-median.jpg with reduced noise while maintaining sharpness.

2. Strong Noise Reduction

For heavily noisy images (low-light photography, old scans):

mediaproc image median noisy-scan.png -s 7

Effect: Larger filter window removes more noise but may slightly soften details.

3. Scanner Artifact Removal

Remove dots, specks, and artifacts from scanned documents:

mediaproc image median scanned-document.jpg -s 5 -o clean-document.jpg

Benefit: Eliminates scanner dust and artifacts without affecting text clarity.

4. Compression Noise Removal

Reduce JPEG compression artifacts:

mediaproc image median compressed-photo.jpg -s 3

Result: Smooths block artifacts while preserving image structure.

5. Batch Processing

Process multiple noisy images:

mediaproc image median "photos/*.jpg" -s 5

Output: Creates *-median.jpg for each input file with consistent noise reduction.

6. Custom Quality Output

Apply filter with specific output quality:

mediaproc image median photo.jpg -s 5 -q 95

Quality: Higher quality (95) preserves more detail in output JPEG.

7. Minimal Smoothing

Preserve maximum detail while reducing only obvious noise:

mediaproc image median detailed-photo.png -s 1

Use Case: When image quality is good but minor noise reduction is needed.

8. Old Photo Restoration

Restore scanned old photographs:

mediaproc image median old-photo-scan.jpg -s 7 --verbose

Result: Removes dust, scratches, and grain from aging photos.

9. Low-Light Camera Noise

Clean up high-ISO camera noise:

mediaproc image median night-photo.jpg -s 5

Application: Reduces color noise and grain from night photography.

10. Medical Image Processing

Clean up medical imaging scans:

mediaproc image median x-ray-scan.png -s 3

Purpose: Remove sensor noise while preserving diagnostic details.

11. Preview Changes

Check effect before processing:

mediaproc image median noisy-image.jpg -s 7 --dry-run

Output: Shows planned operation without creating output file.

12. Document Enhancement

Improve scanned document readability:

mediaproc image median text-scan.png -s 3 -q 100

Benefit: Removes background noise from text without blurring characters.

13. Artistic Photography

Create smooth, painterly effects:

mediaproc image median landscape.jpg -s 15

Effect: Heavy smoothing creates stylized appearance while preserving edges.

14. Video Frame Cleaning

Process individual video frames:

mediaproc image median "frames/*.png" -s 5

Use Case: Clean up extracted video frames before further processing.

15. Product Photography

Remove camera sensor noise from product photos:

mediaproc image median product-shot.jpg -s 3 -o clean-product.jpg -q 95

Quality: Professional output with minimal noise and maximum detail.

Filter Size Selection

Choosing the Right Size

# Minimal noise, maximum detail
mediaproc image median photo.jpg -s 1

# Balanced (default - recommended starting point)
mediaproc image median photo.jpg -s 3

# Moderate noise reduction
mediaproc image median photo.jpg -s 5

# Strong noise reduction
mediaproc image median photo.jpg -s 7

# Heavy smoothing
mediaproc image median photo.jpg -s 10

Size Impact

  • Small (1-3): Fast processing, minimal smoothing, best detail preservation
  • Medium (5-7): Balanced, good for most noisy images
  • Large (10+): Slower processing, heavy smoothing, may blur fine details

Use Cases

1. Salt-and-Pepper Noise Removal

Random white and black pixels scattered across image:

mediaproc image median noisy-photo.jpg -s 3

Why Median: Median filter excels at removing outlier pixels without affecting surrounding areas.

2. Scanner Artifacts

Dust, specks, and scanning errors:

mediaproc image median scan.jpg -s 5

Advantage: Removes artifacts while preserving document/photo content.

3. JPEG Compression Noise

Block artifacts and color banding:

mediaproc image median compressed.jpg -s 3

Result: Smooths compression artifacts with minimal quality loss.

4. Old Photo Restoration

Grain, dust, and age-related damage:

mediaproc image median vintage-photo.jpg -s 7

Restoration: Cleans up damage while maintaining authentic photo appearance.

5. Low-Light Camera Noise

High-ISO noise from night photography:

mediaproc image median night-shot.jpg -s 5

Effect: Reduces color noise and grain while preserving night scene details.

6. Medical Imaging

Sensor noise in X-rays, MRI, CT scans:

mediaproc image median medical-scan.png -s 3

Critical: Edge preservation maintains diagnostic information.

7. Astronomical Photography

Star field noise and sensor artifacts:

mediaproc image median star-field.jpg -s 5

Benefit: Removes noise while preserving star positions and brightness.

8. Document Processing

Scanned documents with background noise:

mediaproc image median document.png -s 3 -q 100

OCR Ready: Improves text recognition by removing background interference.

Median vs Blur Comparison

Edge Preservation

# Median - preserves edges
mediaproc image median photo.jpg -s 5

# Blur - softens edges
mediaproc image blur photo.jpg -s 5

Median Advantage: Sharp edges remain clear while noise is removed.

Noise Types

  • Median Best For:

    • Salt-and-pepper noise
    • Outlier pixels
    • Random speckles
    • Scanner artifacts

  • Blur Best For:

    • Overall softening
    • Bokeh effects
    • Aesthetic smoothing
    • Gradient creation

Processing Characteristics

Median Filter:

  • Non-linear filter
  • Preserves edges and sharp transitions
  • Removes outliers effectively
  • Better for noise with good edges

Gaussian Blur:

  • Linear filter
  • Smooths everything equally
  • Creates gradual transitions
  • Better for aesthetic effects

Combining with Other Commands

Median + Sharpen

Clean noise then enhance details:

# Step 1: Remove noise
mediaproc image median noisy-photo.jpg -s 5 -o clean.jpg

# Step 2: Sharpen details
mediaproc image sharpen clean.jpg

Benefit: Noise removal allows more aggressive sharpening without amplifying artifacts.

Median + Auto-Enhance

Noise reduction followed by automatic adjustments:

mediaproc image median photo.jpg -s 3 -o clean.jpg
mediaproc image auto-enhance clean.jpg

Result: Clean base allows better automatic enhancements.

Median + Contrast

Remove noise, then adjust contrast:

mediaproc image median low-contrast.jpg -s 5 -o clean.jpg
mediaproc image linear clean.jpg -a 1.2

Workflow: Clean image first for better contrast adjustments.

Batch Processing Pipeline

Process multiple images with consistent settings:

# Remove noise from all images
mediaproc image median "raw/*.jpg" -s 5

# Then apply auto-enhance
mediaproc image auto-enhance "raw/*-median.jpg"

Production: Consistent processing across image sets.

Performance Considerations

Processing Time

  • Size 1-3: Fast (~100-200ms per megapixel)
  • Size 5-7: Moderate (~300-500ms per megapixel)
  • Size 10+: Slower (~500ms+ per megapixel)

Memory Usage

Median filter requires temporary buffers for sorting:

  • Small images (less than 2MP): Negligible impact
  • Medium images (2-8MP): ~100-200MB
  • Large images (greater than 8MP): ~200-500MB

Batch Processing

# Process multiple files efficiently
mediaproc image median "photos/*.jpg" -s 5

Optimization: Processes files sequentially with automatic memory management.

Technical Details

Algorithm

The median filter uses a sliding window approach:

  1. For each pixel at position (x, y)
  2. Extract N×N window centered on pixel
  3. Sort all pixel values in window
  4. Select median (middle) value
  5. Replace center pixel with median

Edge Handling

At image borders, the window is clipped to available pixels, ensuring consistent processing across the entire image.

Color Processing

For RGB images:

  • Each channel (R, G, B) is processed independently
  • Median calculated separately for each color component
  • Maintains color relationships while removing noise

Alpha Channel

Transparency is preserved:

  • Alpha channel processed separately
  • Median filter not applied to alpha
  • Transparent areas remain transparent

Troubleshooting

Issue: Too Much Smoothing

Problem: Details are blurred or lost

Solution: Reduce filter size:

# Instead of
mediaproc image median photo.jpg -s 10

# Use smaller size
mediaproc image median photo.jpg -s 3

Issue: Insufficient Noise Reduction

Problem: Noise still visible after processing

Solution: Increase filter size:

# Instead of
mediaproc image median noisy-photo.jpg -s 3

# Use larger size
mediaproc image median noisy-photo.jpg -s 7

Issue: Slow Processing

Problem: Large filter sizes take too long

Solution: Reduce size or resize image first:

# Resize before filtering
mediaproc image resize large-photo.jpg -w 2000 -o resized.jpg
mediaproc image median resized.jpg -s 5

Issue: Still Seeing Noise

Problem: Fine noise remains after filtering

Solution: Apply filter twice with small size:

# First pass
mediaproc image median photo.jpg -s 3 -o pass1.jpg

# Second pass
mediaproc image median pass1.jpg -s 3 -o final.jpg

Issue: Color Shifts

Problem: Colors look different after processing

Solution: Use minimal size and high quality:

mediaproc image median photo.jpg -s 1 -q 100

Issue: Edges Look Artificial

Problem: Hard edges appear unnatural

Solution: Use smaller filter size:

# More natural edge preservation
mediaproc image median photo.jpg -s 3

Best Practices

1. Start Small

Always begin with the default size-3 filter:

mediaproc image median photo.jpg -s 3 --dry-run

Test and increase only if needed.

2. Use Dry Run

Preview effects before processing:

mediaproc image median photo.jpg -s 5 --dry-run

Check output path and settings.

3. Combine with Sharpening

Follow noise reduction with selective sharpening:

mediaproc image median noisy.jpg -s 5 -o clean.jpg
mediaproc image sharpen clean.jpg -a 1.5

4. Preserve Quality

Use high quality for important images:

mediaproc image median photo.jpg -s 5 -q 95

5. Test on Samples

Test settings on representative images first:

# Test on single image
mediaproc image median sample.jpg -s 5

# Then batch process
mediaproc image median "all-photos/*.jpg" -s 5

6. Document Settings

Record successful settings for future use:

# Good for portraits
mediaproc image median portraits/*.jpg -s 3 -q 95

# Good for landscapes
mediaproc image median landscapes/*.jpg -s 5 -q 90

7. Consider Source

Adjust based on noise type:

  • Digital camera noise: Size 3-5
  • Scanner artifacts: Size 5-7
  • Compression noise: Size 3
  • Old photos: Size 7-10
  • blur - Gaussian blur for smooth softening
  • sharpen - Enhance details after noise reduction
  • auto-enhance - Automatic adjustments after cleaning
  • grayscale - Convert to grayscale (reduces color noise visibility)
  • normalize - Adjust brightness after noise reduction

Further Reading

Found an issue? Help us improve this page.

Edit on GitHub →