Atlas Generator

Texture Atlas Generator

The Texture Atlas Generator is a command-line tool.

Usage

atlas_generator -c [--config] file [-a [--attribute] attributeName="attributeValue"] [-q [--quiet]]

Description

  • --config or -c, mandatory, multiple: XML configuration file name.
  • --attribute or -a, optional, multiple: Attribute assignment for use in XML attribute="{}".
  • --quiet or -q, optional, switch: Suppress information printing.
  • --debug or -d, optional, switch: Print debug information.

XML configuration file

The configuration file is a standard XML file and should start with:

  • <?xml version="1.0"?>

The root tag is:

  • <AtlasGenerator>
    Supported attributes and tags:
    • myAttribute="myValue" User defined attributes which can be evaluated using attribute="{myAttribute}".
      User defined attributes can be overwritten by using the --attribute command-line parameter.
    • <Input> Input related tags described in the Input section.
    • <Output> Output related tags described in the Output section.

Input section

One or more input sections are allowed.

The input section tag is:

  • <Input> Contains all input image related information.
    Supported attributes:
    • path="path/to/my/images" The path prefix for all input files, the default path is empty.

The input section supports the following tags:

  • <Crop/> Default crop for all input images.
    Supported attributes:
    • cropThreshold="A[f|i|h]" Automatically crop the image using an alpha channel threshold value.
    • cropCenterX="0" cropCenterY="0" [cropCenter="0"] Set the crop center pixel position, default is no center.
    • cropSizeX="100" cropSizeY="100" [cropSize="100"] Crop using a specified pixel size.
      If specified, the cropCenter position is supported and automatic cropping is disabled.
    • cropLeft="2" cropTop="2" cropRight="-2" cropBottom="-2" Crop using border relative pixel coordinates.
      If positive, the position is relative to the left/top border.
      If negative, the position is relative to the right/bottom border.
      If specified, the cropCenter position is ignored and automatic cropping is disabled.
  • <Scale/> Default scale for all input images.
    Supported attributes:
    • scaleFactor="1.0" [scaleFactorX="1.0"] [scaleFactorY="1.0"] Scale is applied, only if specified and the scale factor is not equal to 1.0.
    • filterType="BILINEAR" [filterWidth="1.0"] Apply bilinear scaling filter.
    • filterType="LINEAR" Apply linear scaling filter.
    • filterType="GAUSSIAN" [filterWidth="3.0" filterSigma="1.0"] Apply gaussian scaling filter.
      The default filter is BILINEAR with filter width 1.0.
  • <Slots/> Default slot properties for all input images.
    Supported attributes:
    • materialSlot="0" The material slot index.
    • parametersSlot="0" The parameter slot index.
    • textureSlots="0,1,2" The texture slots indices.
    • textureSlot.0="0" .. textureSlot.7="0" The texture slot index for a specific unit.
  • <Matte/> Default matte color for all input images.
    Supported attributes:
    • color="R[f|i|h], G[f|i|h], B[f|i|h] | RRGGBBh" [threshold="A[f|i|h]"] Apply the matte color to all pixels having an alpha value less or equal to the threshold value.
  • <Fill/> Default fill color for all input images.
    Supported attributes:
    • color="R[f|i|h], G[f|i|h], B[f|i|h], A[f|i|h] | AARRGGBBh" Apply the fill color to the image border / margin.
  • <Image/> Input image file names and properties.
    Supported attributes:
    • names="image1.png, image2.png, image3*.png" Input image file names, image names can use wildcard patterns * ? [0-z].
      If using wildcard patterns, files starting with '.' are ignored, except the specified pattern starts with '.'.
      If an image name uses wildcard patterns, the attributes sortOrder="..." and exclude="..." are applied.
    • exclude="image4.png, image5.png, image*.jpg" Exclude file names for image file names using wildcard patterns.
      The exclude file names can use wildcard pattterns too * ? [0-z].
    • sortOrder="ASCENDING" [sortOrder="DESCENDING"] [sortOrder="NONE"] Sort order for image file names using wildcard patterns, default is ASCENDING.
    • name="myImage.png" Deprecated, equivalent to names="image.png" .
    • scanAll="yes" Deprecated, equivalent to names="*" .
    • sizeX="0" sizeY="0" [size="0"] Scale to absolute size in pixels, if specified; if size is zero, the original image size is used, the scale factor setting is ignored.
    • rotate="" [rotate="CW"] [rotate="CCW"] Rotate image clockwise (CW) or counterclockwise (CCW).
    • planeApplyAngleZ="yes" Overwrite applyAngleZ from <PlaneGraphXML>, if specified.
    • sequenceApplyAngleZ="yes" Overwrite applyAngleZ from <SequenceGraphXML>, if specified.
    • id="" Set the image identifier. Used for <PlaneGeometry> id and <Rectangle> name attribute.
      The default name is the input image file name without extension. If more than one image file name is specified, this attribute is used to prefix the name.
    • cropThreshold="A[f|i|h]" Overwrite default <Crop> alpha threshold, if specified.
    • cropCenterX="0" cropCenterY="0" [cropCenter="0"] Overwrite default <Crop> center, if specified.
    • cropSizeX="100" cropSizeY="100" [cropSize="100"] Overwrite default <Crop> size, if specified.
    • cropLeft="2" cropTop="2" cropRight="-2" cropBottom="-2" Overwrite default <Crop> border, if specified.
    • scaleFactor="1.0" [scaleFactorX="1.0"] [scaleFactorY="1.0"] Overwrite default <Scale> factor, if specified.
    • filterType="" [filterWidth="" filterSigma=""] Overwrite default <Scale> filter, if specified.
    • materialSlot="0" Overwrite default <Slots> material slot index, if specified.
    • parametersSlot="0" Overwrite default <Slots> parameter slot index, if specified.
    • textureSlots="0,1,2" Overwrite default <Slots> texture slots indices, if specified.
    • textureSlot.0="0" .. textureSlot.7="0" Overwrite default <Slots> texture slot index for a specific unit, if specified.
    • matteColor="R[f|i|h], G[f|i|h], B[f|i|h] | RRGGBBh" [threshold="A[f|i|h]"] Overwrite default <Matte> if specified.
    • fillColor="R[f|i|h], G[f|i|h], B[f|i|h], A[f|i|h] | AARRGGBBh" Overwrite default <Fill> if specified.
    • margin="0" [marginX="0"] [marginY="0"] Overwrite margin of <Output> <Image> if specified.
    • renderBorder="0" [renderBorderX="0"] [renderBorderY="0"] Overwrite margin border rendering size of default <Output> <Image> if specified.
    • repeatBorder="1" [repeatBorderX="1"] [repeatBorderY="1"] Overwrite repeat pixels into margin border of default <Output> <Image> if specified.
    • atlasTexDivisor="1.0" [atlasTexDivisorX="1.0"] [atlasTexDivisorY="1.0"] Overwrite texDivisor of <Output> <AtlasXML> if specified.
    • atlasTexSizeX="0.0" atlasTexSizeY="0.0" Overwrite texSize of <Output> <AtlasXML> if specified.
    • atlasNormalizeTexCoords="yes" Overwrite normalizeTexCoords of <Output> <AtlasXML> if specified.
    • planeTexDivisor="1.0" [planeTexDivisorX="1.0"] [planeTexDivisorY="1.0"] Overwrite texDivisor of <Output> <PlaneGraphXML> if specified.
    • planeTexSizeX="0.0" planeTexSizeY="0.0" Overwrite texSize of <Output> <PlaneGraphXML> if specified.
    • planeNormalizeTexCoords="yes" Overwrite normalizeTexCoords of <Output> <PlaneGraphXML> if specified.
    • planeAttributes="angle=&quot;90deg&quot;" Add attributes to PlaneGraphXML <PlaneGeometry> tag.
    • atlasAttributes="angle=&quot;90deg&quot;" Add attributes to AtlasXML <Rectangle> tag.
    • sequenceAttributes="angle=&quot;90deg&quot;" Add attributes to SequenceGraphXML <PlaneSequenceGeometry> tag.

Output section

Only one output section is allowed.

The output section tag is:

  • <Output> Contains all output image related information.
    Supported attributes:
    • path="path/to/package"
      The path prefix for all output files, the default path is empty.

The output section supports the following tags:

  • <Atlas/> Atlas generation properties.
    Supported attributes:
    • positionRaster="1" [positionRasterX="1"] [positionRasterY="1"] Raster for input image position in atlas, default is 1. Margins and sizeRaster are multiplied by the position raster.
    • sizeRaster="1" [sizeRasterX="1"] [sizeRasterY="1"] Raster for input image size in atlas, default is 1. Input images are centered inside the raster area.
    • packing="BIN_PACKING" Image packing algorithm, default is BIN_PACKING (based on codeincomplete.com/posts/2011/5/7/bin_packing).
    • packingOrder="MAX_SIDE" Packing order for BIN_PACKING only, default is MAX_SIDE.
      packingOrder="MAX_SIDE" Sort images by calculating Max(width, height) per image.
      packingOrder="WIDTH" Sort images by width.
      packingOrder="HEIGHT" Sort images by height.
      packingOrder="AREA" Sort images by area (width * height).
      packingOrder="ID_ASCENDING" Sort images ascending by id.
      packingOrder="ID_DESCENDING" Sort images descending by id.
      packingOrder="NONE" Do not sort images.
    • packing="LEFT_TO_RIGHT" Pack images left-right and top-down. Images are selected in the given input image order, calculating the output image size as well as creating multiple output files is not supported.
  • <Matte/> Default matte color for the output image.
    Supported attributes:
    • color="R[f|i|h], G[f|i|h], B[f|i|h] | RRGGBBh" Fills the empty output image before processing the input images, the default color is 0i, 0i, 0i, 0i.
  • <Fill/> Default fill color for output image.
    Supported attributes:
    • color="R[f|i|h], G[f|i|h], B[f|i|h], A[f|i|h] | AARRGGBBh" Fills the empty output image before processing the input images, the default color is 0i, 0i, 0i, 0i.
  • <Image/> Output image file name and properties.
    Supported attributes:
    • name="" Output image file name, default is "image.png".
    • compressionType="DEFAULT" Output Image compression type, use compressionType="BEST" for maximum PNG compression.
    • sizeX="0" sizeY="0" [size="0"] Output image size in pixels.
      If packing="BIN_PACKING" the image size is calculated and this setting represents the maximum size.
      If packing="LEFT_TO_RIGHT" this setting is required.
    • minSizeX="0" minSizeY="0" [minSize="0"] Minimum Output image size in pixels.
      If packing="BIN_PACKING" the image size is calculated starting from the minimum size.
      If packing="LEFT_TO_RIGHT" this setting is ignored.
    • multiFiles="yes" Create multiple output images if necessary with a maximum size specified by sizeX/Y="", default is "no".
    • sizeRaster="1" [sizeRasterX="1"] [sizeRasterY="1"] Raster for calculating output image size, default is 1.
    • powerOfTwo="yes" Calculate the image size by power of two, default is "yes", size raster is ignored.
    • horizontalFirst="yes" Favour growing size in horizontal direction, default is "yes".
    • margin="0" [marginX="0"] [marginY="0"] Default margin for all input images, default is 0. renderBorder and repeatBorder must fit into margin.
    • renderBorder="0" [renderBorderX="0"] [renderBorderY="0"] Default margin border rendering size for all input images, default is the margin value.
    • repeatBorder="1" [repeatBorderX="1"] [repeatBorderY="1"] Default repeat pixels into margin border for all input images, default is "0".
  • <PlaneGraphXML/> Output plane geometry XML file name and properties.
    Creates a <Graph> XML file containing for each input image an entry:
    <PlaneGeometry id="" frameSizeX="" frameSizeY="" texCoordX1="" texCoordX2="" texCoordY1="" texCoordY2=""/>
    Entries are written in the given input image tags order.
    Supported attributes:
    • name="" Output xml file name, default is "graph_planes.xml".
    • multiFiles="yes" Create a separate xml file per output image, default is "no".
    • texDivisor="1.0" [texDivisorX="1.0"] [texDivisorY="1.0"] Divisor for frameSize, default is 1.0.
    • texSizeX="0.0" texSizeY="0.0" Overwrite the frameSize values if not 0.0.
    • normalizeTexCoords="yes" Normalize texCoords in range [0 .. 1], default is "yes", if "no" textureSize is set to atlas image size and the texCoords are calculated in range [0 .. atlas image size].
    • sizeInScale="no" Write frameSize into scaleFactor if "yes", default is "no". Creates <PlaneGeometry id="" scaleFactorX="" scaleFactorY="" texCoordX1="" texCoordX2="" texCoordY1="" texCoordY2=""/>.
    • materialSlot="0" The default material slot index.
    • parametersSlot="0" The default parameter slot index.
    • textureSlots="0,1,2" The default texture slots indices.
    • textureSlot.0="0" .. textureSlot.7="0" The default texture slot index for a specific unit.
    • textureSlotInterval="1" Increment for texture slots per output image, default is "1".
    • applyAngleZ="yes" Rotate image back via angleZ="+/-90deg" if input image was processed with rotate="CW" or rotate="CCW".
    • attributes="angle=&quot;90deg&quot;" Add attributes to <PlaneGeometry> tag.
  • <AtlasXML/> Output atlas XML file name and properties.
    Creates an <Atlas> XML file containing for each input image an entry:
    <Rectangle coordSizeX="" coordSizeY="" texCoordX1="" texCoordY1="" texCoordX2="" texCoordY2="" [textureSizeX="" textureSizeY=""] [name=""] [materialSlot="" parametersSlot="" textureSlots=""]/>
    Entries are written in the given input image tags order.
    Supported attributes:
    • name="" Output xml file name, default is "atlas_rectangles.xml" or "atlas_image_rectangles.xml" if images attribute is set.
    • multiFiles="yes" Create a separate xml file per output image, default is "no".
    • images="image1.png, image2*.png" Include specified input images, image names can use wildcard patterns * ? [0-z]. If this attribute is specified the multiFiles="" attribute is ignored.
    • texDivisor="1.0" [texDivisorX="1.0"] [texDivisorY="1.0"] Divisor for coordSize, default is 1.0.
    • texSizeX="0.0" texSizeY="0.0" Overwrite the coordSize values if not 0.0.
    • normalizeTexCoords="yes" Normalize texCoords in range [0 .. 1], default is "yes", if "no" the corresponding <PlaneSequenceGeometry> textureSize is set to atlas image size and the <AtlasXML/> texCoords are calculated in range [0 .. atlas image size].
    • createTextureSize="no" Create <Rectangle> textureSizeX and textureSizeY attributes if normalizeTexCoords="no".
    • createNames="no" Create <Rectangle> name attributes containing the image identifier.
    • createSlots="no" Create <Rectangle> slot attributes. If any slot is specified the default value is "yes" otherwise "no".
    • materialSlot="0" The default material slot index.
    • parametersSlot="0" The default parameter slot index.
    • textureSlots="0,1,2" The default texture slots indices.
    • textureSlot.0="0" .. textureSlot.7="0" The default texture slot index for a specific unit.
    • textureSlotInterval="1" Increment for texture slots per output image, default is "1".
    • attributes="angle=&quot;90deg&quot;" Add attributes to <Rectangle> tag.
  • <SequenceGraphXML/> Output plane sequence geometry XML file name and properties.
    Creates a <Graph> XML file containing for each input image an entry:
    <PlaneSequenceGeometry id="" atlasResourceId="[packageId]:[resourceId]" index=""/>
    Supported attributes:
    • name="" Output xml file name, default is "graph_plane_sequences.xml".
    • multiFiles="yes" Create a separate xml file per output image, default is "no".
    • packageId="" Package identifier for referencing the <Rectangle> instances.
    • resourceId="" Resource identifier for referencing the <Rectangle> instances. Default is the AtlasXML name attribute without extension.
    • materialSlot="0" The default material slot index.
    • parametersSlot="0" The default parameter slot index.
    • textureSlots="0,1,2" The default texture slots indices.
    • textureSlot.0="0" .. textureSlot.7="0" The default texture slot index for a specific unit.
    • textureSlotInterval="1" Increment for texture slots per output image, default is "1".
    • applyAngleZ="yes" Rotate image back via angleZ="+/-90deg" if input image was processed with rotate="CW" or rotate="CCW".
    • attributes="angle=&quot;90deg&quot;" Add attributes to <PlaneSequenceGeometry> tag.
  • <TextureGraphXML/> Output Texture XML file name and properties if specified.
    Creates a <Graph> XML file containing <FlatTexture> and <TextureState> per output image and optional <Instance>.
    • name="" Output XML File name, default is "graph_textures.xml".
    • namespace="" Create an enclosing namespace.
    • textureId="" The Texture identifier. Default is the output image file name without extension.
    • textureSlot="0" The texture slot index.
    • textureSlotInterval="1" Increment for texture slot per output image, default is 1.
    • textureUnit="0" The texture unit index.
    • useMipMaps="no" The texture mip-maps attribute.
    • planeGraphInstance="yes" Create instances of the PlaneGraphXML graphs.
    • sequenceGraphInstance="yes" Create instances of the SequenceGraphXML graphs.
    • flatTextureAttributes="" Add attributes to <FlatTexture> tag.
    • textureStateAttributes="" Add attributes to <TextureState> tag.
  • <PackageXML/> Output Package XML file name and properties if specified.
    Creates a <Package> XML file containing <Resource> and optional an <Instance> of the texture graph.
    • name="" Output XML File name, default is "package.xml".
    • packageId="images" The package identifier. Adds [packageId].murlres to output path if output path does not end with .murlres. Sets <SequenceGraphXML> packageId="[packageId]" if no packageId is specified in <SequenceGraphXML>.
    • textureGraphInstance="yes" Create a static instance of the <TextureGraphXML>.
    • parentNodeId="" The parent node id of the static graph instance.

The input image processing is done per image in the following order:

  1. Crop
  2. Apply Matte
  3. Scale
  4. Draw repeatBorder
  5. Rotate
  6. Make final size including margin and sizeRaster
  7. Fill the margin
  8. Apply Matte on the margin

XML Example

Pack all images from path my_images1 and my_images_2 to an atlas image and create the corresponding graph XML file.
Each image gets a margin of 1 pixel and an even-numbered size in the atlas.

<?xml version="1.0" encoding="utf-8"?>

<AtlasGenerator xmlns="https://murlengine.com">

    <Input path="my_images1">

        <Image names="*"/>

    </Input>

    <Input path="my_images2">

        <Image names="*.png"/>

    </Input>

    <Output path="my_package.murlres">

        <Atlas sizeRaster="2"/>

        <Image name="my_atlas.png" margin="1"/>

        <PlaneGraphXML name="my_planes.xml"/>

    </Output>

</AtlasGenerator>


Copyright © 2011-2018 Spraylight GmbH.