ascompose.c(1)

libAfterImage/ascompose
  ascompose is a tool to compose image(s) and display/save it based on
 supplied XML input file.

 ascompose -f file|-s string [-o file] [-t type] [-V]"
 ascompose -f file|-s string [-o file] [-t type] [-V]"
 ascompose -f file|-s string [-o file] [-t type] [-V] [-n]"
 ascompose -f file|-s string [-o file] [-t type] [-V] [-r]"
 ascompose [-h]
 ascompose [-v]
 ascompose reads supplied XML data, and manipulates image accordingly.
 It could transform images from files of any supported file format,
 draw gradients, render antialiased texturized text, perform
 superimposition of arbitrary number of images, and save images into
 files of any of supported output file formats.
 At any point, the result of any operation could be assigned a name,
 and later on referenced under this name.
 At any point during the script processing, result of any operation
 could be saved into a file of any supported file types.
 Internal image format is 32bit ARGB with 8bit per channel.
 Last image referenced, will be displayed in X window, unless -n option
 is specified. If -r option is specified, then this image will be
 displayed in root window of X display, effectively setting a background
 for a desktop. If -o option is specified, this image will also be
 saved into the file or requested type.
 ascompose can be compiled to not reference X Window System, thus
 allowing it to be used on web servers and any other place. It does not
 even require X libraries in that case.
 Supported file types for input are :
 XPM   - via internal code, or libXpm library.
 JPEG  - via libJpeg library.
 PNG   - via libPNG library.
 XCF   - via internal code. For now XCF support is not complete as it
         does not merge layers.
 PPM/PNM - via internal code.
 BMP, ICO, CUR - via internal code.
 GIF   - via libungif library.
 TIFF  - via libtiff library (including alpha channel support).
 see libAfterImage/ASImageFileTypes for more.
 Supported file types for output :
 XPM   - via internal code, or libXpm library.
 JPEG  - via libJpeg library.
 PNG   - via libPNG library.
 GIF   - via libungif library.
 TIFF  - via libtiff library (including alpha channel support).
    -h --help          display help and exit.
    -f --file file     an XML file to use as input.
    -s --string string an XML string to use as input.
    -n --no-display    don't display the last referenced image.
    -r --root-window   draw last referenced image image on root window.
    -o --output file   output last referenced image in to a file.
                       You should use -t to specify what file type to
                       use. Filenames are meaningless when it comes to
                       determining what file type to use.
    -t --type type     type of file to output to.
    -v --version       display version and exit.
    -V --verbose       increase verbosity. To increase verbosity level
                       use several of these, like: ascompose -V -V -V.
    -D --debug         maximum verbosity - show everything and
                       debug messages.
 ascompose could be used both with and without X window system. It has
 been tested on most UNIX flavors on both 32 and 64 bit architecture.
 It has also been tested under CYGWIN environment on Windows 95/NT/2000
 libAfterImage         all the image manipulation routines.
 libAfterBase          Optionally. Misc data handling such as hash
                       tables and console io. Must be used when compiled
                       without X Window support.
 libJPEG               JPEG image format support.
 libPNG                PNG image format support.
 libungif              GIF image format support.
 libTIFF               TIFF image format support.
  Ethan Fisher          <allanon at crystaltokyo dot com>
 Sasha Vasko           <sasha at aftercode dot net>
 Eric Kowalski         <eric at beancrock dot net>

libAfterImage/ascompose/sample
 Here is the default script that gets executed by ascompose, if no
 parameters are given :
    static char* default_doc_str = "\
    <composite op=hue>\
      <composite op=add>\
        <scale width=512 height=384><img src=rose512.jpg/></scale>\
        <tile width=512 height=384><img src=back.xpm/></tile>\
      </composite>\
      <tile width=512 height=384><img src=fore.xpm/></tile>\
    </composite>\
    ";

libAfterImage/ascompose/tags
 Here is the list and description of possible XML tags to use in the
 script :
    img       - load image from the file.
    recall    - recall previously loaded/generated image by its name.
    text      - render text string into new image.
    save      - save an image into the file.
    bevel     - draw solid bevel frame around the image.
    gradient  - render multipoint gradient.
    mirror    - create mirror copy of an image.
    blur      - perform gaussian blur on an image.
    rotate    - rotate/flip image in 90 degree increments.
    scale     - scale an image to arbitrary size.
    crop      - crop an image to arbitrary size.
    tile      - tile an image to arbitrary size.
    hsv       - adjust Hue, Saturation and Value of an image.
    pad       - pad image with solid color from either or all sides.
    solid     - generate new image of requested size, filled with solid
              color.
    composite - superimpose arbitrary number of images using one of 15
              available methods.
 Each tag generates new image as the result of the transformation -
 existing images are never modified and could be reused as many times
 as needed. See below for description of each tag.
 Whenever numerical values are involved, the basic math ops (add,
 subtract, multiply, divide), unary minus, and parentheses are
 supported.
 Operator precedence is NOT supported.  Percentages are allowed, and
 apply to the "size" parameter of this function.
 Each tag is only allowed to return ONE image.

libAfterImage/ascompose/tags/img
  img - load image from the file.

 <img id="new_img_id" src=filename/>
 id     Optional.  Image will be given this name for future reference.
 src    Required.  The filename (NOT URL) of the image file to load.
  The special image src "xroot:" will import the background image
 of the root X window, if any.  No attempt will be made to offset this
 image to fit the location of the resulting window, if one is displayed.

libAfterImage/ascompose/tags/recall
  recall - recall previously generated and named image by its id.

 <recall id="new_id" srcid="image_id">
 id       Optional.  Image will be given this name for future reference.
 srcid    Required.  An image ID defined with the "id" parameter for
          any previously created image.

libAfterImage/ascompose/tags/text
  text - render text string into new image, using specific font, size
        and texture.

 <text id="new_id" font="font" point="size" fgcolor="color"
       bgcolor="color" fgimage="image_id" bgimage="image_id"
       spacing="points">My Text Here</text>
 id       Optional.  Image will be given this name for future reference.
 font     Optional.  Default is "fixed".  Font to use for text.
 point    Optional.  Default is 12.  Size of text in points.
 fgcolor  Optional.  No default.  The text will be drawn in this color.
 bgcolor  Optional.  No default.  The area behind the text will be drawn
          in this color.
 fgimage  Optional.  No default.  The text will be textured by this image.
 bgimage  Optional.  No default.  The area behind the text will be filled
          with this image.
 spacing  Optional.  Default 0.  Extra pixels to place between each glyph.
  <text> without bgcolor, fgcolor, fgimage, or bgimage will NOT
 produce visible output by itself.  See EXAMPLES below.

libAfterImage/ascompose/tags/save
  save - write generated/loaded image into the file of one of the
        supported types

 <save id="new_id" dst="filename" format="format" compress="value"
       opacity="value" replace="0|1" delay="mlsecs">
 id       Optional.  Image will be given this name for future reference.
 dst      Required.  Name of file image will be saved to.
 format   Optional.  Ouput format of saved image.  Defaults to the
          extension of the "dst" parameter.  Valid values are the
          standard AS image file formats: xpm, jpg, png, gif, tiff.
 compress Optional.  Compression level if supported by output file
          format. Valid values are in range of 0 - 100 and any of
          "deflate", "jpeg", "ojpeg", "packbits" for TIFF files.
          Note that JPEG and GIF will produce images with deteriorated
          quality when compress is greater then 0. For JPEG default is
          25, for PNG default is 6 and for GIF it is 0.
 opacity  Optional. Level below which pixel is considered to be
          transparent, while saving image as XPM or GIF. Valid values
          are in range 0-255. Default is 127.
 replace  Optional. Causes ascompose to delete file if the file with the
          same name already exists. Valid values are 0 and 1. Default
          is 1 - files are deleted before being saved. Disable this to
          get multimage animated gifs.
 delay    Optional. Delay to be stored in GIF image. This could be used
          to create animated gifs. Note that you have to set replace="0"
          and then write several images into the GIF file with the same
          name.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/bevel
  bevel - draws solid bevel frame around the image.

 <bevel id="new_id" colors="color1 color2"
        border="left top right bottom">
 id       Optional.  Image will be given this name for future reference.
 colors   Optional.  Whitespace-separated list of colors.  Exactly two
          colors are required.  Default is "#ffdddddd #ff555555".  The
          first color is the color of the upper and left edges, and the
          second is the color of the lower and right edges.
 borders  Optional.  Whitespace-separated list of integer values.
          Default is "10 10 10 10".  The values represent the offsets
          toward the center of the image of each border: left, top,
          right, bottom.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/gradient
  gradient - render multipoint gradient.

 <gradient id="new_id" angle="degrees" width="pixels" height="pixels"
           colors ="color1 color2 color3 [...]"
           offsets="fraction1 fraction2 fraction3 [...]"/>
 id       Optional.  Image will be given this name for future reference.
 refid    Optional.  An image ID defined with the "id" parameter for
          any previously created image.  If set, percentages in "width"
          and "height" will be derived from the width and height of the
          refid image.
 width    Required.  The gradient will have this width.
 height   Required.  The gradient will have this height.
 colors   Required.  Whitespace-separated list of colors.  At least two
          colors are required.  Each color in this list will be visited
          in turn, at the intervals given by the offsets attribute.
 offsets  Optional.  Whitespace-separated list of floating point values
          ranging from 0.0 to 1.0.  The colors from the colors attribute
          are given these offsets, and the final gradient is rendered
          from the combination of the two.  If both colors and offsets
          are given but the number of colors and offsets do not match,
          the minimum of the two will be used, and the other will be
          truncated to match.  If offsets are not given, a smooth
          stepping from 0.0 to 1.0 will be used.
 angle    Optional.  Given in degrees.  Default is 0.  This is the
          direction of the gradient.  Currently the only supported
          values are 0, 45, 90, 135, 180, 225, 270, 315.  0 means left
          to right, 90 means top to bottom, etc.

libAfterImage/ascompose/tags/mirror
  mirror - create new image as mirror copy of an old one.

  <mirror id="new_id" dir="direction">
 id       Optional. Image will be given this name for future reference.
 dir      Required. Possible values are "vertical" and "horizontal".
          The image will be flipped over the x-axis if dir is vertical,
          and flipped over the y-axis if dir is horizontal.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/blur
  blur - perform a gaussian blurr on an image.

 <blur id="new_id" horz="radius" vert="radius">
 id       Optional. Image will be given this name for future reference.
 horz     Optional. Horizontal radius of the blur in pixels.
 vert     Optional. Vertical radius of the blur in pixels.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/rotate
  rotate - rotate an image in 90 degree increments (flip).

  <rotate id="new_id" angle="degrees">
 id       Optional. Image will be given this name for future reference.
 angle    Required.  Given in degrees.  Possible values are currently
          "90", "180", and "270".  Rotates the image through the given
          angle.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/scale
  scale - scale image to arbitrary size

 <scale id="new_id" ref_id="other_imag" width="pixels" height="pixels">
 id       Optional. Image will be given this name for future reference.
 refid    Optional.  An image ID defined with the "id" parameter for
          any previously created image.  If set, percentages in "width"
          and "height" will be derived from the width and height of the
          refid image.
 width    Required.  The image will be scaled to this width.
 height   Required.  The image will be scaled to this height.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/crop
  crop - crop image to arbitrary area within it.

  <crop id="new_id" refid="other_image" srcx="pixels" srcy="pixels"
        width="pixels" height="pixels" tint="color">
 id       Optional. Image will be given this name for future reference.
 refid    Optional. An image ID defined with the "id" parameter for
          any previously created image.  If set, percentages in "width"
          and "height" will be derived from the width and height of the
          refid image.
 srcx     Optional. Default is "0". Skip this many pixels from the left.
 srcy     Optional. Default is "0". Skip this many pixels from the top.
 width    Optional. Default is "100%".  Keep this many pixels wide.
 height   Optional. Default is "100%".  Keep this many pixels tall.
 tint     Optional. Additionally tint an image to specified color.
          Tinting can both lighten and darken an image. Tinting color
          0 or #7f7f7f7f yeilds no tinting. Tinting can be performed on
          any channel, including alpha channel.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/tile
  tile - tile an image to specified area.

  <tile id="new_id" refid="other_image" width="pixels" height="pixels"
        x_origin="pixels" y_origin="pixels" tint="color">
 id       Optional. Image will be given this name for future reference.
 refid    Optional. An image ID defined with the "id" parameter for
          any previously created image.  If set, percentages in "width"
          and "height" will be derived from the width and height of the
          refid image.
 width    Optional. Default is "100%". The image will be tiled to this
          width.
 height   Optional. Default is "100%". The image will be tiled to this
          height.
 x_origin Optional. Horizontal position on infinite surface, covered
          with tiles of the image, from which to cut out resulting
          image.
 y_origin Optional. Vertical position on infinite surface, covered
          with tiles of the image, from which to cut out resulting
          image.
 tint     Optional. Additionally tint an image to specified color.
          Tinting can both lighten and darken an image. Tinting color
          0 or #7f7f7f7f yields no tinting. Tinting can be performed
          on any channel, including alpha channel.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/hsv
  hsv - adjust Hue, Saturation and/or Value of an image and optionally
 tile an image to arbitrary area.

 <hsv id="new_id" refid="other_image"
      x_origin="pixels" y_origin="pixels" width="pixels" height="pixels"
      affected_hue="degrees|color" affected_radius="degrees"
      hue_offset="degrees" saturation_offset="value"
      value_offset="value">
 id       Optional. Image will be given this name for future reference.
 refid    Optional. An image ID defined with the "id" parameter for
          any previously created image.  If set, percentages in "width"
          and "height" will be derived from the width and height of the
          refid image.
 width    Optional. Default is "100%". The image will be tiled to this
          width.
 height   Optional. Default is "100%". The image will be tiled to this
          height.
 x_origin Optional. Horizontal position on infinite surface, covered
          with tiles of the image, from which to cut out resulting
          image.
 y_origin Optional. Vertical position on infinite surface, covered
          with tiles of the image, from which to cut out resulting
          image.
 affected_hue    Optional. Limits effects to the renage of hues around
          this hue. If numeric value is specified - it is treated as
          degrees on 360 degree circle, with :
              red = 0,
              yellow = 60,
              green = 120,
              cyan = 180,
              blue = 240,
              magenta = 300.
          If colorname or value preceded with # is specified here - it
          will be treated as RGB color and converted into hue
          automagically.
 affected_radius
          Optional. Value in degrees to be used in order to
          calculate the range of affected hues. Range is determined by
          substracting and adding this value from/to affected_hue.
 hue_offset
          Optional. Value by which to adjust the hue.
 saturation_offset
          Optional. Value by which to adjust the saturation.
 value_offset
          Optional. Value by which to adjust the value.
  One of the Offsets must be not 0, in order for operation to be
 performed.
 This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/pad
  pad - pad an image with solid color rectangles.

 <pad id="new_id" refid="other_image" left="pixels" top="pixels"
      right="pixels" bottom="pixels" color="color">
 id       Optional. Image will be given this name for future reference.
 refid    Optional. An image ID defined with the "id" parameter for
          any previously created image.  If set, percentages in "pixel"
          pad values will be derived from the width and height of the
          refid image.
 left     Optional. Size to add to the left of the image.
 top      Optional. Size to add to the top of the image.
 right    Optional. Size to add to the right of the image.
 bottom   Optional. Size to add to the bottom of the image.
 color    Optional. Color value to fill added areas with. It could be
          transparent of course. Default is #FF000000 - totally black.
  This tag applies to the first image contained within the tag.  Any
 further images will be discarded.

libAfterImage/ascompose/tags/solid
  solid - generate image of specified size and fill it with solid color.

 <solid id="new_id" color="color" width="pixels" height="pixels"/>
 id       Optional. Image will be given this name for future reference.
 color    Optional.  Default is "#ffffffff".  An image will be created
          and filled with this color.
 width    Required.  The image will have this width.
 height   Required.  The image will have this height.

libAfterImage/ascompose/tags/composite
  composite - superimpose arbitrary number of images on top of each
 other.

 <composite id="new_id" op="op_desc"
            keep-transparency="0|1" merge="0|1">
 id       Optional. Image will be given this name for future reference.
 op       Optional. Default is "alphablend". The compositing operation.
          Valid values are the standard AS blending ops: add, alphablend,
          allanon, colorize, darken, diff, dissipate, hue, lighten,
          overlay, saturate, screen, sub, tint, value.
 merge    Optional. Default is "expand". Valid values are "clip" and
          "expand". Determines whether final image will be expanded to
          the maximum size of the layers, or clipped to the bottom
          layer.
 keep-transparency
          Optional. Default is "0". Valid values are "0" and "1". If
          set to "1", the transparency of the bottom layer will be
          kept for the final image.
  All images surrounded by this tag will be composited with the given op.
 All tags surrounded by this tag will be given the following
 additional attributes in addition to their normal ones.  Under no
 circumstances is there a conflict with the normal child attributes.
 crefid   Optional. An image ID defined with the "id" parameter for
          any previously created image. If set, percentages in "x"
          and "y" will be derived from the width and height of the
          crefid image.
 x        Optional. Default is 0. Pixel coordinate of left edge.
 y        Optional. Default is 0. Pixel coordinate of top edge.
 clip_x   Optional. Default is 0. X Offset on infinite surface tiled
          with this image, from which to cut portion of an image to be
          used in composition.
 clip_y   Optional. Default is 0. Y Offset on infinite surface tiled
          with this image, from which to cut portion of an image to be
          used in composition.
 clip_width
          Optional. Default is image width. Tile image to this width
          prior to superimposition.
 clip_height
          Optional. Default is image height. Tile image to this height
          prior to superimposition.
 tile     Optional. Default is 0. If set will cause image to be tiled
          across entire composition, unless overridden by clip_width or
          clip_height.
 tint     Optional. Additionally tint an image to specified color.
          Tinting can both lighten and darken an image. Tinting color
          0 or #7f7f7f7f yields no tinting. Tinting can be performed
          on any channel, including alpha channel.

 libAfterImage