Enhanced Image Format Selection

[kadykov]

Description

Introduction

Quarto is a versatile tool for creating documents in various formats, including HTML, DOCX, and PDF. Currently, users can specify a default-image-extension field for each output format. However, this approach restricts users to a single image format per output format, which may not be optimal for all scenarios. This proposal suggests enhancing Quarto's image format selection mechanism to allow for greater flexibility and optimization.

The problem

Suppose you're creating a Quarto document with vector images, lossy and lossless bitmap images. You want to render this document to HTML, PDF and DOCX formats with the optimal image quality and file size for different types of images.

HTML Output

• For bitmap images, you prefer AVIF due to its superior compression and quality.
• SVG is the preferred format for vector graphics because it scales without loss of quality.
• Additionally, for lossless bitmap images, WebP provides better compression than AVIF or PNG.

Therefore, you'd like to specify AVIF for lossy bitmap images, SVG for vector images, and WebP for lossless bitmap images in the HTML output.

PDF Output

• PDF does not support SVG image format natively, and embedding SVG graphics is done by converting it to PNG with rsvg-convert. Therefore, you might want to use PDF figures instead of SVG graphics.
• Since PDF does not support AVIF and WebP images, you opt for JPG for bitmap images and PNG for lossless bitmap images.

Therefore, in PDF output, you would prefer PDF for vector graphics, JPG for bitmap images, and PNG for lossless bitmap images.

DOCX Output

• To ensure compatibility, you might prefer to use commonly supported image formats such as JPG and PNG.

Therefore, in DOCX output, you would choose JPG for bitmap images and PNG for both vector graphics and lossless bitmap images, ensuring seamless integration with Microsoft Word.

Proposal:

Introduction of image-extensions Field

• Introduce a new field called image-extensions under the format configuration section in Quarto documents.
• This field will accept a list of image extensions to be used as fallback options if the primary image format specified by default-image-extension is not available.

By allowing users to specify a list of image extensions for each output format, the proposed enhancement empowers them to tailor image format selection according to the specific requirements and constraints of different output formats, ensuring optimal quality, compatibility, and efficiency in document rendering.

Compatibility Considerations:

• This proposal aims to maintain backward compatibility with existing projects.
• Users who do not specify the image-extensions field will continue to use the default behavior, where only the default-image-extension is considered.

Example Usage

---
title: "Optimal image formats"
  
format:
  html:
    default-image-extension: avif
    image-extensions:
      - avif # bitmap images
      - svg # vector images
      - webp # lossless bitmap images
  pdf:
    default-image-extension: jpg 
    image-extensions:
    - jpg # bitmap images
    - pdf # vector images
    - png # lossless bitmap images
  docx:
    default-image-extension: jpg
    image-extensions:
    - jpg # bitmap images
    - png # vector and lossless bitmap images
---

![Vector image](images/vector-image)

![Bitmap image](images/photo)

![Lossless bitmap image](images/bitmap-image)

Implementation Details

• Extend the quarto-cli to support the image-extensions field.
• When rendering documents, check for the availability of images with extensions specified in both default-image-extension and image-extensions.
• If an image with the primary extension is not found, fallback to the extensions listed in image-extensions.

Benefits

• Provides users with greater flexibility in selecting optimal image formats for different output formats.
• Enables better optimization of image quality and file size based on the requirements of each output format.
• Improves the overall user experience by allowing finer control over image rendering in Quarto documents.

Conclusion

The proposed enhancement to Quarto's image format selection mechanism offers users more flexibility and control in choosing the most suitable image formats for their documents. By introducing the image-extensions field, Quarto becomes more versatile and adaptable to a wider range of use cases and requirements.

[CocoCodeAcademy]

Very much looking forward for this function!