![]() |
Murl Engine API
Version 2018.3
|
The Texture Atlas Generator is a command-line tool.
atlas_generator -c [--config] file [-a [--attribute] attributeName="attributeValue"] [-q [--quiet]]
--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.The configuration file is a standard XML file and should start with:
<?xml version="1.0"?>
The root tag is:
<AtlasGenerator>
myAttribute="myValue"
User defined attributes which can be evaluated using attribute="{myAttribute}"
. --attribute
command-line parameter.<Input>
Input related tags described in the Input section.<Output>
Output related tags described in the Output section.One or more input sections are allowed.
The input section tag is:
<Input>
Contains all input image related information. 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. 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. cropLeft="2" cropTop="2" cropRight="-2" cropBottom="-2"
Crop using border relative pixel coordinates. <Scale/>
Default scale for all input images. 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. <Slots/>
Default slot properties for all input images. 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. 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. 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. names="image1.png, image2.png, image3*.png"
Input image file names, image names can use wildcard patterns * ? [0-z]
. '.'
are ignored, except the specified pattern starts with '.'
. sortOrder="..."
and exclude="..."
are applied.exclude="image4.png, image5.png, image*.jpg"
Exclude file names for image file names using wildcard patterns. * ? [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. 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="90deg""
Add attributes to PlaneGraphXML <PlaneGeometry> tag.atlasAttributes="angle="90deg""
Add attributes to AtlasXML <Rectangle> tag.sequenceAttributes="angle="90deg""
Add attributes to SequenceGraphXML <PlaneSequenceGeometry> tag.Only one output section is allowed.
The output section tag is:
<Output>
Contains all output image related information. path="path/to/package"
The output section supports the following tags:
<Atlas/>
Atlas generation properties. 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. 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. 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. 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. 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. minSizeX="0" minSizeY="0" [minSize="0"]
Minimum Output image size in pixels. 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. <PlaneGeometry id="" frameSizeX="" frameSizeY="" texCoordX1="" texCoordX2="" texCoordY1="" texCoordY2=""/>
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="90deg""
Add attributes to <PlaneGeometry>
tag.<AtlasXML/>
Output atlas XML file name and properties. <Rectangle coordSizeX="" coordSizeY="" texCoordX1="" texCoordY1="" texCoordX2="" texCoordY2="" [textureSizeX="" textureSizeY=""] [name=""] [materialSlot="" parametersSlot="" textureSlots=""]/>
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="90deg""
Add attributes to <Rectangle>
tag.<SequenceGraphXML/>
Output plane sequence geometry XML file name and properties. <PlaneSequenceGeometry id="" atlasResourceId="[packageId]:[resourceId]" index=""/>
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="90deg""
Add attributes to <PlaneSequenceGeometry>
tag.<TextureGraphXML/>
Output Texture XML file name and properties if specified. 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. 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:
Crop
Matte
Scale
repeatBorder
Rotate
margin
and sizeRaster
Fill
the marginMatte
on the marginPack 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="http://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>