view release on metacpan or  search on metacpan

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

              PIX     *pixRotate()
              PIX     *pixEmbedForRotation()

     General rotation by sampling
              PIX     *pixRotateBySampling()

     Nice (slow) rotation of 1 bpp image
              PIX     *pixRotateBinaryNice()

     Rotation including alpha (blend) component
              PIX     *pixRotateWithAlpha()

     Rotations are measured in radians; clockwise is positive.

     The general rotation pixRotate() does the best job for
     rotating about the image center.  For 1 bpp, it uses shear;
     for others, it uses either shear or area mapping.
     If requested, it expands the output image so that no pixels are lost
     in the rotation, and this can be done on multiple successive shears
     without expanding beyond the maximum necessary size.

=head1 FUNCTIONS

=head2 pixEmbedForRotation

PIX * pixEmbedForRotation ( PIX *pixs, l_float32 angle, l_int32 incolor, l_int32 width, l_int32 height )

  pixEmbedForRotation()

      Input:  pixs (1, 2, 4, 8, 32 bpp rgb)
              angle (radians; clockwise is positive)
              incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK)
              width (original width; use 0 to avoid embedding)
              height (original height; use 0 to avoid embedding)
      Return: pixd, or null on error

  Notes:
      (1) For very small rotations, just return a clone.
      (2) Generate larger image to embed pixs if necessary, and
          place the center of the input image in the center.
      (3) Rotation brings either white or black pixels in
          from outside the image.  For colormapped images where
          there is no white or black, a new color is added if
          possible for these pixels; otherwise, either the
          lightest or darkest color is used.  In most cases,
          the colormap will be removed prior to rotation.
      (4) The dest is to be expanded so that no image pixels
          are lost after rotation.  Input of the original width
          and height allows the expansion to stop at the maximum
          required size, which is a square with side equal to
          sqrt(w*w + h*h).
      (5) For an arbitrary angle, the expansion can be found by
          considering the UL and UR corners.  As the image is
          rotated, these move in an arc centered at the center of
          the image.  Normalize to a unit circle by dividing by half
          the image diagonal.  After a rotation of T radians, the UL
          and UR corners are at points T radians along the unit
          circle.  Compute the x and y coordinates of both these
          points and take the max of absolute values; these represent
          the half width and half height of the containing rectangle.
          The arithmetic is done using formulas for sin(a+b) and cos(a+b),
          where b = T.  For the UR corner, sin(a) = h/d and cos(a) = w/d.
          For the UL corner, replace a by (pi - a), and you have
          sin(pi - a) = h/d, cos(pi - a) = -w/d.  The equations
          given below follow directly.

=head2 pixRotate

PIX * pixRotate ( PIX *pixs, l_float32 angle, l_int32 type, l_int32 incolor, l_int32 width, l_int32 height )

  pixRotate()

      Input:  pixs (1, 2, 4, 8, 32 bpp rgb)
              angle (radians; clockwise is positive)
              type (L_ROTATE_AREA_MAP, L_ROTATE_SHEAR, L_ROTATE_SAMPLING)
              incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK)
              width (original width; use 0 to avoid embedding)
              height (original height; use 0 to avoid embedding)
      Return: pixd, or null on error

  Notes:
      (1) This is a high-level, simple interface for rotating images
          about their center.
      (2) For very small rotations, just return a clone.
      (3) Rotation brings either white or black pixels in
          from outside the image.
      (4) The rotation type is adjusted if necessary for the image
          depth and size of rotation angle.  For 1 bpp images, we
          rotate either by shear or sampling.
      (5) Colormaps are removed for rotation by area mapping.
      (6) The dest can be expanded so that no image pixels
          are lost.  To invoke expansion, input the original
          width and height.  For repeated rotation, use of the
          original width and height allows the expansion to
          stop at the maximum required size, which is a square
          with side = sqrt(w*w + h*h).

  *** Warning: implicit assumption about RGB component ordering 

=head2 pixRotateBinaryNice

PIX * pixRotateBinaryNice ( PIX *pixs, l_float32 angle, l_int32 incolor )

  pixRotateBinaryNice()

      Input:  pixs (1 bpp)
              angle (radians; clockwise is positive; about the center)
              incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK)
      Return: pixd, or null on error

  Notes:
      (1) For very small rotations, just return a clone.
      (2) This does a computationally expensive rotation of 1 bpp images.
          The fastest rotators (using shears or subsampling) leave
          visible horizontal and vertical shear lines across which
          the image shear changes by one pixel.  To ameliorate the
          visual effect one can introduce random dithering.  One
          way to do this in a not-too-random fashion is given here.
          We convert to 8 bpp, do a very small blur, rotate using
          linear interpolation (same as area mapping), do a
          small amount of sharpening to compensate for the initial