Skip to main content

DPI Quality Alert

The cv-dpi-alert component warns users when an image element doesn't meet the minimum DPI (dots per inch) required for quality printing. When AI upscaling is enabled, it also offers a one-click Upscale with AI button to fix the issue.

How It Works​

  1. The user selects an image element on the canvas.
  2. ChamevoJS calculates the element's effective DPI based on its natural pixel dimensions and physical print size.
  3. If the DPI falls below customImageParameters.minDPI, a warning alert appears anchored to the element on the canvas.
  4. If aiService.superRes is enabled, an Upscale with AI button appears in the alert.
  5. Clicking the button calls chamevo.upscaleImage() to increase the image resolution.
  6. The alert disappears once the DPI meets the minimum threshold.

Quick Start​

1. Set Minimum DPI​

Configure minDPI in customImageParameters:

const customizer = createCustomizer('#container', {
    customImageParameters: {
        minDPI: 150,
    },
});

This sets the threshold globally for all uploaded/custom images. The alert appears automatically when any image's effective DPI drops below this value.

2. Enable AI Upscale (Optional)​

To show the Upscale with AI button in the alert, configure the AI service:

const customizer = createCustomizer('#container', {
    customImageParameters: {
        minDPI: 150,
    },
    aiService: {
        serverURL: '/php/ai-service.php',
        superRes: true,
    },
});

Without aiService configuration, the alert still displays the DPI warning — it just won't offer the upscale action.

How DPI Is Calculated​

DPI is computed from the image's natural pixel width and its physical print width in millimeters:

DPI = ceil((naturalWidth × 25.4) / physicalWidthMM)
VariableSource
naturalWidthThe image file's original pixel width (before any canvas scaling).
physicalWidthMMThe element's rendered width converted to millimeters using the print area's unit scale.

The DPI updates dynamically as the user resizes the image — scaling an image up decreases its DPI, scaling it down increases it.

DPI in the Size Tooltip​

When sizeTooltip is enabled, selected image elements show their physical dimensions and current DPI above the element:

120 × 80 mm — DPI: 245

This gives users a real-time readout of print quality as they resize images.

Configuration​

customImageParameters.minDPI​

PropertyTypeDefaultDescription
minDPInumber—Minimum DPI threshold. The alert appears when an image's effective DPI is below this value. Set to 0 or omit to disable.

aiService (for upscale button)​

PropertyTypeDefaultDescription
serverURLstring | nullnullURL to the AI service endpoint.
superResbooleanfalseSet to true to enable the upscale button in the DPI alert.

Per-Element Override​

You can set minDPI per element in the product data instead of globally:

{
    type: 'image',
    source: 'https://example.com/photo.jpg',
    parameters: {
        minDPI: 200,  // Higher threshold for this element
    },
}

Alert Behavior​

  • Canvas-anchored — The alert follows the selected element's position on the canvas.
  • Scale-aware — The alert adjusts its position when the canvas is zoomed or resized.
  • Non-blocking — Users can continue editing while the alert is visible.
  • Auto-dismiss — The alert disappears when the element's DPI meets the threshold, or when the element is deselected.

i18n​

Customize alert labels:

customizer.options = {
    labels: {
        'misc.dpi_warning': 'The image requires a minimum DPI of {minDPI}. Upload a larger image or scale down for better print results.',
        'misc.ai_upscale_btn': 'Upscale with AI',
        'misc.ai_upscale_success': 'Image Upscaled',
    },
};

The {minDPI} placeholder is replaced with the configured minimum DPI value.

See i18n for full translation setup.

Next Steps​