Added support for creating thumbnails or preview bitmaps of fixed size for PNG and TIFF output.

Documentation update for bitmap output.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@820939 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 138 insertions, 21 deletions

diff --git a/src/documentation/content/xdocs/trunk/output.xml b/src/documentation/content/xdocs/trunk/output.xml
index 0ae9d586b..972fc1f19 100644
--- a/src/documentation/content/xdocs/trunk/output.xml
+++ b/src/documentation/content/xdocs/trunk/output.xml
@@ -1033,8 +1033,13 @@ out = proc.getOutputStream();]]></source>
   <p>
     Currently, two output formats are supported: PNG and TIFF. TIFF produces
     one file with multiple pages, while PNG output produces one file per
-    page. The quality of the bitmap depends on the target resolution setting 
-    on the FOUserAgent.
+    page. Note: FOP can only produce multiple files (with PNG output) if
+    you can set a <code>java.io.File</code> indicating the primary PNG file
+    using the <code>FOUserAgent.setOutputFile(File)</code> method.
+  </p>
+  <p>
+    The quality of the bitmap depends on the target resolution setting 
+    on the FOUserAgent and on further settings described below.
   </p>
     <section id="bitmap-configuration">
       <title>Configuration</title>
@@ -1042,15 +1047,52 @@ out = proc.getOutputStream();]]></source>
         The TIFF and PNG renderer configuration currently allows the following settings:
       </p>
 <source><![CDATA[<renderer mime="image/png">
+  <color-mode>rgba</color-mode>
   <transparent-page-background>true</transparent-page-background>
+  <background-color>white</background-color>
+  <anti-aliasing>true</anti-aliasing>
+  <rendering>quality</rendering>
   <fonts><!-- described elsewhere --></fonts>
 </renderer>]]></source>
       <p>
-        The default value for the "transparent-page-background" setting is "false" which 
-        paints an opaque, white background for the whole image. If you set this to true,
+        The default value for the <code>"color-mode"</code> setting is <code>"rgba"</code> which
+        is equivalent to a 24bit RGB image with an 8bit alpha channel for transparency.
+        Valid values are:
+      </p>
+      <ul>
+        <li><code>rgba</code>: RGB with alpha channel (24bit + 8bit = 32bit)</li>
+        <li><code>rgb</code>: RGB (24bit)</li>
+        <li><code>gray</code>: gray (8bit)</li>
+        <li><code>bi-level</code> (or <code>binary</code>): bi-level (1bit)</li>
+      </ul>
+      <p>
+        Please note that there is currently no dithering or error diffusion available for bi-level
+        bitmap output.
+      </p>
+      <p>
+        The default value for the <code>"transparent-page-background"</code> setting is
+        <code>"false"</code> which paints an opaque, white background for the whole image.
+        If you set this to <code>"true"</code>,
         no such background will be painted and you will get a transparent image if
         an alpha channel is available in the output format.
       </p>
+      <p>
+        The default value for the <code>"background-color"</code> setting is <code>"white"</code>.
+        The color specifies in which color the page background is painted. It will only be
+        painted if <code>"transparent-page-background"</code> is not set to <code>"true"</code>.
+        All XSL-FO colors (including color functions) can be used.
+      </p>
+      <p>
+        The default value for the <code>"anti-aliasing"</code> setting is <code>"true"</code>.
+        You can set this value to <code>"false"</code> to disable anti-aliasing and
+        thus improve rendering speeds a bit at the loss of some image quality.
+      </p>
+      <p>
+        The default value for the <code>"rendering"</code> setting is <code>"true"</code>.
+        You can set this value to <code>"false"</code> to improve rendering speeds a bit
+        at the loss of some image quality. If this setting has an actual effect depends
+        on the JVM's Java2D backend.
+      </p>
     </section>
     <section id="tiff-configuration">
       <title>TIFF-specific Configuration</title>
@@ -1071,17 +1113,22 @@ out = proc.getOutputStream();]]></source>
         actual codecs being available. Here is a list of possible values:
       </p>
       <ul>
-        <li>NONE (no compression)</li>
-        <li>PackBits (RLE, run-length encoding)</li>
-        <li>JPEG</li>
-        <li>Deflate</li>
-        <li>LZW</li>
-        <li>ZLib</li>
-        <li>CCITT T.4 (Fax Group 3)</li>
-        <li>CCITT T.6 (Fax Group 4)</li>
+        <li><code>NONE</code> (no compression)</li>
+        <li><code>PackBits</code> (RLE, run-length encoding)</li>
+        <li><code>JPEG</code></li>
+        <li><code>Deflate</code></li>
+        <li><code>LZW</code></li>
+        <li><code>ZLib</code></li>
+        <li><code>CCITT T.4</code> (Fax Group 3)</li>
+        <li><code>CCITT T.6</code> (Fax Group 4)</li>
       </ul>
+      <p>
+        This setting may override any setting made using the <code>"color-mode"</code>. For example, if
+        <code>"CCITT T.6"</code> is selected, the color mode is automatically forced to <code>"bi-level"</code> because
+        this compression format only supports bi-level images.
+      </p>
       <note>
-        If you want to use CCITT compression, please make sure you've got a J2SE 1.4 or later and
+        If you want to use CCITT compression, please make sure you've got
         <a href="http://java.sun.com/products/java-media/jai/current.html">
           Java Advanced Imaging Image I/O Tools
         </a>
@@ -1090,6 +1137,17 @@ out = proc.getOutputStream();]]></source>
         Deflate and JPEG compression for writing.
       </note>
     </section>
+    <section id="bitmap-rendering-options">
+      <title>Runtime Rendering Options</title>
+      <p>
+        The IF-based bitmap output implementations support a rendering option with the key
+        "target-bitmap-size" (value: java.awt.Dimension) that allows to force the pages to
+        be proportionally fit into a bitmap of a given size. This can be used to produce
+        thumbnails or little preview images of the individual pages. An example:
+      </p>
+      <source><![CDATA[userAgent.getRenderingOptions().put(
+    "target-bitmap-size", new Dimension(320, 200));]]></source>
+    </section>
 </section>
 <section id="txt">
   <title>TXT</title>
diff --git a/src/java/org/apache/fop/render/bitmap/AbstractBitmapDocumentHandler.java b/src/java/org/apache/fop/render/bitmap/AbstractBitmapDocumentHandler.java
index 3449ffe7e..e4606858b 100644
--- a/src/java/org/apache/fop/render/bitmap/AbstractBitmapDocumentHandler.java
+++ b/src/java/org/apache/fop/render/bitmap/AbstractBitmapDocumentHandler.java
@@ -22,9 +22,11 @@ package org.apache.fop.render.bitmap;
 import java.awt.Dimension;
 import java.awt.Graphics2D;
 import java.awt.RenderingHints;
+import java.awt.geom.Point2D;
 import java.awt.image.BufferedImage;
 import java.io.IOException;
 import java.io.OutputStream;
+import java.util.Map;
 
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.logging.Log;
@@ -53,6 +55,13 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin
     /** logging instance */
     private static Log log = LogFactory.getLog(AbstractBitmapDocumentHandler.class);
 
+    /**
+     * Rendering Options key for the controlling the required bitmap size to create.
+     * This is used to create thumbnails, for example. If used, the target resolution is ignored.
+     * Value type: java.awt.Dimension (size in pixels)
+     */
+    public static final String TARGET_BITMAP_SIZE = "target-bitmap-size";
+
     private ImageWriter imageWriter;
     private MultiImageWriter multiImageWriter;
 
@@ -66,6 +75,7 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin
     private BitmapRenderingSettings bitmapSettings = new BitmapRenderingSettings();
 
     private double scaleFactor = 1.0;
+    private Dimension targetBitmapSize;
 
     /**
      * Default constructor.
@@ -94,6 +104,9 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin
         //Set target resolution
         int dpi = Math.round(context.getUserAgent().getTargetResolution());
         getSettings().getWriterParams().setResolution(dpi);
+
+        Map renderingOptions = getUserAgent().getRendererOptions();
+        setTargetBitmapSize((Dimension)renderingOptions.get(TARGET_BITMAP_SIZE));
     }
 
     /** {@inheritDoc} */
@@ -113,6 +126,17 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin
         setFontInfo(fi);
     }
 
+    /**
+     * Sets the target bitmap size (in pixels) of the bitmap that should be produced. Normally,
+     * the bitmap size is calculated automatically based on the page size and the target
+     * resolution. But for example, if you want to create thumbnails or small preview bitmaps
+     * from pages it is more practical (and efficient) to set the required bitmap size.
+     * @param size the target bitmap size (in pixels)
+     */
+    public void setTargetBitmapSize(Dimension size) {
+        this.targetBitmapSize = size;
+    }
+
     //----------------------------------------------------------------------------------------------
 
     /** {@inheritDoc} */
@@ -176,13 +200,43 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin
 
     /** {@inheritDoc} */
     public IFPainter startPageContent() throws IFException {
-        double scale = scaleFactor
-            * (25.4f / FopFactoryConfigurator.DEFAULT_TARGET_RESOLUTION)
-                / getUserAgent().getTargetPixelUnitToMillimeter();
-        int bitmapWidth = (int) ((this.currentPageDimensions.width * scale / 1000f) + 0.5f);
-        int bitmapHeight = (int) ((this.currentPageDimensions.height * scale / 1000f) + 0.5f);
+        int bitmapWidth;
+        int bitmapHeight;
+        double scale;
+        Point2D offset = null;
+        if (targetBitmapSize != null) {
+            //Fit the generated page proportionally into the given rectangle (in pixels)
+            double scale2w = 1000 * targetBitmapSize.width
+                / this.currentPageDimensions.getWidth();
+            double scale2h = 1000 * targetBitmapSize.height
+                / this.currentPageDimensions.getHeight();
+            bitmapWidth = targetBitmapSize.width;
+            bitmapHeight = targetBitmapSize.height;
+
+            //Centering the page in the given bitmap
+            offset = new Point2D.Double();
+            if (scale2w < scale2h) {
+                scale = scale2w;
+                double h = this.currentPageDimensions.height * scale / 1000;
+                offset.setLocation(0, (bitmapHeight - h) / 2.0);
+            } else {
+                scale = scale2h;
+                double w = this.currentPageDimensions.width * scale / 1000;
+                offset.setLocation((bitmapWidth - w) / 2.0, 0);
+            }
+        } else {
+            //Normal case: just scale according to the target resolution
+            scale = scaleFactor
+                * getUserAgent().getTargetResolution()
+                / FopFactoryConfigurator.DEFAULT_TARGET_RESOLUTION;
+            bitmapWidth = (int) ((this.currentPageDimensions.width * scale / 1000f) + 0.5f);
+            bitmapHeight = (int) ((this.currentPageDimensions.height * scale / 1000f) + 0.5f);
+        }
+
+        //Set up bitmap to paint on
         this.currentImage = createBufferedImage(bitmapWidth, bitmapHeight);
         Graphics2D graphics2D = this.currentImage.createGraphics();
+
         // draw page background
         if (!getSettings().hasTransparentPageBackground()) {
             graphics2D.setBackground(getSettings().getPageBackgroundColor());
@@ -190,6 +244,7 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin
             graphics2D.fillRect(0, 0, bitmapWidth, bitmapHeight);
         }
 
+        //Set rendering hints
         graphics2D.setRenderingHint(RenderingHints.KEY_FRACTIONALMETRICS,
                 RenderingHints.VALUE_FRACTIONALMETRICS_ON);
         if (getSettings().isAntiAliasingEnabled()
@@ -213,6 +268,11 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin
         }
         graphics2D.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL,
                 RenderingHints.VALUE_STROKE_PURE);
+
+        //Set up initial coordinate system for the page
+        if (offset != null) {
+            graphics2D.translate(offset.getX(), offset.getY());
+        }
         graphics2D.scale(scale / 1000f, scale / 1000f);
 
         return new Java2DPainter(graphics2D, getContext(), getFontInfo());
diff --git a/src/java/org/apache/fop/render/bitmap/BitmapRendererConfigurator.java b/src/java/org/apache/fop/render/bitmap/BitmapRendererConfigurator.java
index 5237dbe35..1b6c43700 100644
--- a/src/java/org/apache/fop/render/bitmap/BitmapRendererConfigurator.java
+++ b/src/java/org/apache/fop/render/bitmap/BitmapRendererConfigurator.java
@@ -19,7 +19,6 @@
 
 package org.apache.fop.render.bitmap;
 
-import java.awt.Color;
 import java.awt.Graphics2D;
 import java.awt.image.BufferedImage;
 import java.util.List;
@@ -80,8 +79,6 @@ public class BitmapRendererConfigurator extends Java2DRendererConfigurator
                 if (background != null) {
                     settings.setPageBackgroundColor(
                             ColorUtil.parseColorString(this.userAgent, background));
-                } else {
-                    settings.setPageBackgroundColor(Color.WHITE);
                 }
             }
 
@@ -106,6 +103,8 @@ public class BitmapRendererConfigurator extends Java2DRendererConfigurator
                     settings.setBufferedImageType(BufferedImage.TYPE_BYTE_GRAY);
                 } else if ("binary".equalsIgnoreCase(color)) {
                     settings.setBufferedImageType(BufferedImage.TYPE_BYTE_BINARY);
+                } else if ("bi-level".equalsIgnoreCase(color)) {
+                    settings.setBufferedImageType(BufferedImage.TYPE_BYTE_BINARY);
                 } else {
                     throw new FOPException("Invalid value for color-mode: " + color);
                 }