view release on metacpan or  search on metacpan

lib/Image/Leptonica/Func/psio2.pm  view on Meta::CPAN

=head2 convertFlateToPS

l_int32 convertFlateToPS ( const char *filein, const char *fileout, const char *operation, l_int32 x, l_int32 y, l_int32 res, l_float32 scale, l_int32 pageno, l_int32 endpage )

  convertFlateToPS()

      Input:  filein (input file -- any format)
              fileout (output ps file)
              operation ("w" for write; "a" for append)
              x, y (location of LL corner of image, in pixels, relative
                    to the PostScript origin (0,0) at the LL corner
                    of the page)
              res (resolution of the input image, in ppi; use 0 for default)
              scale (scaling by printer; use 0.0 or 1.0 for no scaling)
              pageno (page number; must start with 1; you can use 0
                      if there is only one page.)
              endpage (boolean: use TRUE if this is the last image to be
                       added to the page; FALSE otherwise)
      Return: 0 if OK, 1 on error

  Notes:
      (1) This outputs level 3 PS as flate compressed (overlaid
          with ascii85 encoding).
      (2) An output file can contain multiple pages, each with
          multiple images.  The arguments to convertFlateToPS()
          allow you to control placement of png images on multiple
          pages within a PostScript file.
      (3) For the first image written to a file, use "w", which
          opens for write and clears the file.  For all subsequent
          images written to that file, use "a".
      (4) The (x, y) parameters give the LL corner of the image
          relative to the LL corner of the page.  They are in
          units of pixels if scale = 1.0.  If you use (e.g.)
          scale = 2.0, the image is placed at (2x, 2y) on the page,
          and the image dimensions are also doubled.
      (5) Display vs printed resolution:
           * If your display is 75 ppi and your image was created
             at a resolution of 300 ppi, you can get the image
             to print at the same size as it appears on your display
             by either setting scale = 4.0 or by setting  res = 75.
             Both tell the printer to make a 4x enlarged image.
           * If your image is generated at 150 ppi and you use scale = 1,
             it will be rendered such that 150 pixels correspond
             to 72 pts (1 inch on the printer).  This function does
             the conversion from pixels (with or without scaling) to
             pts, which are the units that the printer uses.
           * The printer will choose its own resolution to use
             in rendering the image, which will not affect the size
             of the rendered image.  That is because the output
             PostScript file describes the geometry in terms of pts,
             which are defined to be 1/72 inch.  The printer will
             only see the size of the image in pts, through the
             scale and translate parameters and the affine
             transform (the ImageMatrix) of the image.
      (6) To render multiple images on the same page, set
          endpage = FALSE for each image until you get to the
          last, for which you set endpage = TRUE.  This causes the
          "showpage" command to be invoked.  Showpage outputs
          the entire page and clears the raster buffer for the
          next page to be added.  Without a "showpage",
          subsequent images from the next page will overlay those
          previously put down.
      (7) For multiple pages, increment the page number, starting
          with page 1.  This allows PostScript (and PDF) to build
          a page directory, which viewers use for navigation.

=head2 convertFlateToPSEmbed

l_int32 convertFlateToPSEmbed ( const char *filein, const char *fileout )

  convertFlateToPSEmbed()

      Input:  filein (input file -- any format)
              fileout (output ps file)
      Return: 0 if OK, 1 on error

  Notes:
      (1) This function takes any image file as input and generates a
          flate-compressed, ascii85 encoded PS file, with a bounding box.
      (2) The bounding box is required when a program such as TeX
          (through epsf) places and rescales the image.
      (3) The bounding box is sized for fitting the image to an
          8.5 x 11.0 inch page.

=head2 convertG4ToPS

l_int32 convertG4ToPS ( const char *filein, const char *fileout, const char *operation, l_int32 x, l_int32 y, l_int32 res, l_float32 scale, l_int32 pageno, l_int32 maskflag, l_int32 endpage )

  convertG4ToPS()

      Input:  filein (input tiff g4 file)
              fileout (output ps file)
              operation ("w" for write; "a" for append)
              x, y (location of LL corner of image, in pixels, relative
                    to the PostScript origin (0,0) at the LL corner
                    of the page)
              res (resolution of the input image, in ppi; typ. values
                   are 300 and 600; use 0 for automatic determination
                   based on image size)
              scale (scaling by printer; use 0.0 or 1.0 for no scaling)
              pageno (page number; must start with 1; you can use 0
                      if there is only one page.)
              maskflag (boolean: use TRUE if just painting through fg;
                        FALSE if painting both fg and bg.
              endpage (boolean: use TRUE if this is the last image to be
                       added to the page; FALSE otherwise)
      Return: 0 if OK, 1 on error

  Notes:
      (1) See the usage comments in convertJpegToPS(), some of
          which are repeated here.
      (2) This is a wrapper for tiff g4.  The PostScript that
          is generated is expanded by about 5/4 (due to the
          ascii85 encoding.  If you convert to pdf (ps2pdf), the
          ascii85 decoder is automatically invoked, so that the
          pdf wrapped g4 file is essentially the same size as
          the original g4 file.  It's useful to have the PS
          file ascii85 encoded, because many printers will not
          print binary PS files.
      (3) For the first image written to a file, use "w", which
          opens for write and clears the file.  For all subsequent
          images written to that file, use "a".
      (4) To render multiple images on the same page, set
          endpage = FALSE for each image until you get to the
          last, for which you set endpage = TRUE.  This causes the
          "showpage" command to be invoked.  Showpage outputs
          the entire page and clears the raster buffer for the
          next page to be added.  Without a "showpage",
          subsequent images from the next page will overlay those
          previously put down.
      (5) For multiple images to the same page, where you are writing
          both jpeg and tiff-g4, you have two options:
           (a) write the g4 first, as either image (maskflag == FALSE)
               or imagemask (maskflag == TRUE), and then write the
               jpeg over it.
           (b) write the jpeg first and as the last item, write
               the g4 as an imagemask (maskflag == TRUE), to paint
               through the foreground only.
          We have this flexibility with the tiff-g4 because it is 1 bpp.
      (6) For multiple pages, increment the page number, starting
          with page 1.  This allows PostScript (and PDF) to build
          a page directory, which viewers use for navigation.

=head2 convertG4ToPSEmbed

l_int32 convertG4ToPSEmbed ( const char *filein, const char *fileout )

  convertG4ToPSEmbed()

      Input:  filein (input tiff file)
              fileout (output ps file)
      Return: 0 if OK, 1 on error

  Notes:
      (1) This function takes a g4 compressed tif file as input and
          generates a g4 compressed, ascii85 encoded PS file, with
          a bounding box.
      (2) The bounding box is required when a program such as TeX
          (through epsf) places and rescales the image.
      (3) The bounding box is sized for fitting the image to an
          8.5 x 11.0 inch page.
      (4) We paint this through a mask, over whatever is below.

=head2 convertJpegToPS

l_int32 convertJpegToPS ( const char *filein, const char *fileout, const char *operation, l_int32 x, l_int32 y, l_int32 res, l_float32 scale, l_int32 pageno, l_int32 endpage )

  convertJpegToPS()

      Input:  filein (input jpeg file)
              fileout (output ps file)
              operation ("w" for write; "a" for append)
              x, y (location of LL corner of image, in pixels, relative
                    to the PostScript origin (0,0) at the LL corner
                    of the page)
              res (resolution of the input image, in ppi; use 0 for default)
              scale (scaling by printer; use 0.0 or 1.0 for no scaling)
              pageno (page number; must start with 1; you can use 0
                      if there is only one page)
              endpage (boolean: use TRUE if this is the last image to be
                       added to the page; FALSE otherwise)
      Return: 0 if OK, 1 on error

  Notes:
      (1) This is simpler to use than pixWriteStringPS(), and
          it outputs in level 2 PS as compressed DCT (overlaid
          with ascii85 encoding).
      (2) An output file can contain multiple pages, each with
          multiple images.  The arguments to convertJpegToPS()
          allow you to control placement of jpeg images on multiple
          pages within a PostScript file.
      (3) For the first image written to a file, use "w", which
          opens for write and clears the file.  For all subsequent
          images written to that file, use "a".
      (4) The (x, y) parameters give the LL corner of the image
          relative to the LL corner of the page.  They are in
          units of pixels if scale = 1.0.  If you use (e.g.)
          scale = 2.0, the image is placed at (2x, 2y) on the page,
          and the image dimensions are also doubled.
      (5) Display vs printed resolution:
           * If your display is 75 ppi and your image was created
             at a resolution of 300 ppi, you can get the image
             to print at the same size as it appears on your display
             by either setting scale = 4.0 or by setting  res = 75.
             Both tell the printer to make a 4x enlarged image.
           * If your image is generated at 150 ppi and you use scale = 1,
             it will be rendered such that 150 pixels correspond
             to 72 pts (1 inch on the printer).  This function does
             the conversion from pixels (with or without scaling) to
             pts, which are the units that the printer uses.
           * The printer will choose its own resolution to use
             in rendering the image, which will not affect the size
             of the rendered image.  That is because the output
             PostScript file describes the geometry in terms of pts,
             which are defined to be 1/72 inch.  The printer will
             only see the size of the image in pts, through the
             scale and translate parameters and the affine
             transform (the ImageMatrix) of the image.
      (6) To render multiple images on the same page, set
          endpage = FALSE for each image until you get to the
          last, for which you set endpage = TRUE.  This causes the
          "showpage" command to be invoked.  Showpage outputs
          the entire page and clears the raster buffer for the
          next page to be added.  Without a "showpage",
          subsequent images from the next page will overlay those
          previously put down.
      (7) For multiple pages, increment the page number, starting
          with page 1.  This allows PostScript (and PDF) to build
          a page directory, which viewers use for navigation.

=head2 convertJpegToPSEmbed

l_int32 convertJpegToPSEmbed ( const char *filein, const char *fileout )

  convertJpegToPSEmbed()

      Input:  filein (input jpeg file)
              fileout (output ps file)
      Return: 0 if OK, 1 on error

  Notes:
      (1) This function takes a jpeg file as input and generates a DCT
          compressed, ascii85 encoded PS file, with a bounding box.
      (2) The bounding box is required when a program such as TeX
          (through epsf) places and rescales the image.
      (3) The bounding box is sized for fitting the image to an
          8.5 x 11.0 inch page.

=head2 convertTiffMultipageToPS

l_int32 convertTiffMultipageToPS ( const char *filein, const char *fileout, const char *tempfile, l_float32 fillfract )

  convertTiffMultipageToPS()

      Input:  filein (input tiff multipage file)
              fileout (output ps file)
              tempfile (<optional> for temporary g4 tiffs;
                        use NULL for default)
              factor (for filling 8.5 x 11 inch page;
                      use 0.0 for DEFAULT_FILL_FRACTION)
      Return: 0 if OK, 1 on error

  Notes:
      (1) This converts a multipage tiff file of binary page images
          into a ccitt g4 compressed PS file.
      (2) If the images are generated from a standard resolution fax,
          the vertical resolution is doubled to give a normal-looking
          aspect ratio.

=head2 decodeAscii85

l_uint8 * decodeAscii85 ( char *ina, l_int32 insize, l_int32 *poutsize )

  decodeAscii85()

      Input:  inarray (ascii85 input data)
              insize (number of bytes in input array)
              &outsize (<return> number of bytes in output l_uint8 array)
      Return: outarray (binary)

  Notes:
      (1) We assume the data is properly encoded, so we do not check
          for invalid characters or the final '>' character.
      (2) We permit whitespace to be added to the encoding in an
          arbitrary way.