![]() |
Murl Engine API
Version 2024.1
|
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.textureSlotInterval="1"
Increment for texture slots per output image, default is "1".<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.list="../example/example.txt"
Read the names for the images from a text file. Each name has to be seperated by a new line.skipImages="1"
Counts up on each image and skips the next image when the counter reaches the given value. The counter starts with 0, and resets to 0 after a skip. 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.planeApplyCropCenter="no"
Overwrite applyCropCenter from PlaneGraphXML
if specifiedplaneApplyRasterCenter="no"
Overwrite applyRasterCenter from PlaneGraphXML
if specifiedsequenceApplyCropCenter="no"
Overwrite applyCropCenter from SequenceGraphXML
if specifiedsequenceApplyRasterCenter="no"
Overwrite applyRasterCenter from @cSequenceGraphXML if specifiedscaleFactor="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.prescaleDivisors="1"
A comma-separated list of prescale divisors for which to generate output image variants. Allowed values are 1, 2, 4, 8, 16, 32, 64 and 128.<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.
Supported attributes:
name=""
Output image file name, default is "image.png".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".fileType="DEFAULT"
Generated output image type, from IEnums::FileType. streamFormat="DEFAULT"
The encoded data stream format, from IEnums::VideoStreamFormat. pixelFormat="UNDEFINED"
The encoded pixel format, from IEnums::PixelFormat. mipMapGenerationMode="DEFAULT"
From IEnums::MipMapGenerationMode. compressionType="DEFAULT"
The type of compression, from IEnums::CompressionType. compressionQuality="90.0"
Compression quality, if applicable. Inside the <Image> element, it is possible to specify any number of variants for the output image(s), together with a number of conditions for identifying a specific variant according to the target device's inherent properties such as e.g. operating system, video API or platform feature:
<Variant/>
Output image variant.
Supported attributes:
includeForUserConfigurations="" excludeForUserConfigurations=""
Comma-separated inclusion/exclusion lists of app-defined configuration strings.includeForLanguages="" excludeForLanguages=""
Comma-separated inclusion/exclusion lists of values from the IEnums::Language enumeration.includeForTargetClasses="" excludeForTargetClasses=""
Comma-separated inclusion/exclusion lists of values from the IEnums::TargetClass enumeration.includeForTargetDevices="" excludeForTargetDevices=""
Comma-separated inclusion/exclusion lists of values from the IEnums::TargetDevice enumeration.includeForTargetHosts="" excludeForTargetHosts=""
Comma-separated inclusion/exclusion lists of values from the IEnums::TargetHost enumeration.includeForOperatingSystems="" excludeForOperatingSystems=""
Comma-separated inclusion/exclusion lists of values from the IEnums::OperatingSystem enumeration.includeForGpus="" excludeForGpus=""
Comma-separated inclusion/exclusion lists of values from the IEnums::Gpu enumeration.includeForVideoApis="" excludeForVideoApis=""
Comma-separated inclusion/exclusion lists of values from the IEnums::VideoApi enumeration.includeForAudioApis="" excludeForAudioApis=""
Comma-separated inclusion/exclusion lists of values from the IEnums::AudioApi enumeration.includeForFeatures="" excludeForFeatures=""
Comma-separated inclusion/exclusion lists of values from the IEnums::Feature enumeration.scaleFactor="1.0"
Additional image scale factor for the given variant.Additionally, the following attributes are supported for controlling the image variant's output encoding; see the correspoding attributes in the output <Image> element description above.
fileType="DEFAULT"
Generated output image type, from IEnums::FileType.streamFormat="DEFAULT"
The encoded data stream format, from IEnums::VideoStreamFormat.pixelFormat="UNDEFINED"
The encoded pixel format, from IEnums::PixelFormat.mipMapGenerationMode="DEFAULT"
From IEnums::MipMapGenerationMode.compressionType="DEFAULT"
The type of compression, from IEnums::CompressionType.compressionQuality="90.0"
Compression quality, if applicable.When generating the output package, any given image variants are defined first in the package.xml file (in their given order), followed by the default image specification defined by the variant's parent output <Image>.
<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".usePathPrefix="no"
Creates a prefix to the id from the file path. Separators ('/', '\', ':') are replaced by '_'.useExtensionPostfix="no"
Creates a postfix to the id from the file extension.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".applyCropCenter="no"
Set posX
and posY
to correct image center for cropped input image (cropCenter
not used). Can be combined with applyRasterCenter
.applyRasterCenter="no"
Set posX
and posY
to correct image center for sizeRaster
rounding-up (sizeRaster
> 1) Can be combined with applyCropCenter
.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.usePathPrefix="no"
Creates a prefix to the id from the file path. Separators ('/', '\', ':') are replaced by '_'.useExtensionPostfix="no"
Creates a postfix to the id from the file extension.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".applyCropCenter="no"
Set posX
and posY
to correct image center for cropped input image (cropCenter
not used). Can be combined with applyRasterCenter
.applyRasterCenter="no"
Set posX
and posY
to correct image center for sizeRaster
rounding-up (sizeRaster
> 1) Can be combined with applyCropCenter
.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.usePrescale=""
Manually define the "usePrescale" attribute of the <FlatTexture> node. If omitted, the attribute is set to true whenenableAutomaticSwapping=""
Directly set the "enableAutomaticSwapping" attribute of the the <FlatTexture> node.enableManualSwapping=""
Directly set the "enableManualSwapping" attribute of the the <FlatTexture> node.swapped=""
Directly set the "swapped" attribute of the the <FlatTexture> node.<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" mipMapGenerationMode="FAST"> <Variant mipMapGenerationMode="FAST" pixelFormat="ETC2_RGBA8_8BPP" compressionQuality="50" includeForFeatures="TEXTURE_COMPRESSION_ETC2"/> <Variant mipMapGenerationMode="FAST" pixelFormat="PVRTC_RGBA_4BPPV1" compressionQuality="70" includeForFeatures="TEXTURE_COMPRESSION_PVRTC"/> </Image> <PlaneGraphXML name="my_planes.xml"/> </Output> </AtlasGenerator>