├── AtlasMaker.jsx
├── media
    ├── test-atlases.jpg
    └── atlasmaker-screen.jpg
├── resources
    └── amlogo72.png
├── include
    ├── RectanglePacker.js
    ├── PackerContainer.jsx
    ├── Sorters.jsx
    ├── ImageInfo.jsx
    ├── Packer.jsx
    ├── TileGrid.jsx
    ├── AtlasPacker.jsx
    └── ExportOrderWindow.jsx
├── changes.txt
├── test
    └── create-test-images.jsx
├── readme.txt
└── README.md


/AtlasMaker.jsx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/richardjdare/Atlasmaker/HEAD/AtlasMaker.jsx


--------------------------------------------------------------------------------
/media/test-atlases.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/richardjdare/Atlasmaker/HEAD/media/test-atlases.jpg


--------------------------------------------------------------------------------
/resources/amlogo72.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/richardjdare/Atlasmaker/HEAD/resources/amlogo72.png


--------------------------------------------------------------------------------
/include/RectanglePacker.js:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/richardjdare/Atlasmaker/HEAD/include/RectanglePacker.js


--------------------------------------------------------------------------------
/media/atlasmaker-screen.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/richardjdare/Atlasmaker/HEAD/media/atlasmaker-screen.jpg


--------------------------------------------------------------------------------
/include/PackerContainer.jsx:
--------------------------------------------------------------------------------
1 | //----------------------------------------------------------------------------
// AtlasMaker
// AllPackers.jsx - array of rectangle packers. Add your packer here
//
// Author: Richard Dare
// richardjdare@googlemail.com
// http://richardjdare.com 
//----------------------------------------------------------------------------
#include "TileGrid.jsx"
#include "AtlasPacker.jsx"

function PackerContainer(){
	this.allPackers = [
        new TileGrid(),
        new AtlasPacker()
	];
};


--------------------------------------------------------------------------------
/include/Sorters.jsx:
--------------------------------------------------------------------------------
 1 | //----------------------------------------------------------------------------
 2 | // AtlasMaker
 3 | // sort.jsx - image sorting functions
 4 | //
 5 | // Author: Richard Dare
 6 | // richardjdare@googlemail.com
 7 | // http://richardjdare.com 
 8 | //----------------------------------------------------------------------------
 9 | 
10 | #include "ImageInfo.jsx"
11 | 
12 | function SorterContainer(){
13 |         this.sorters={
14 | 			'none'	: function (a,b) { return 1; },
15 | 			'width'	: function (a,b) { return a.width - b.width; },
16 | 			'height': function (a,b) { return a.height - b.height; },
17 | 			'area'  : function (a,b) { return a.width*a.height - b.width*b.height; },
18 | 			'magic' : function (a,b) { return Math.max(a.width,a.height) - Math.max(b.width,b.height); }
19 | }
20 | };


--------------------------------------------------------------------------------
/include/ImageInfo.jsx:
--------------------------------------------------------------------------------
1 | //----------------------------------------------------------------------------
// AtlasMaker
// ImageInfo.jsx - All images we work on are represented by one of these.
//
// Author: Richard Dare
// richardjdare@googlemail.com
// http://richardjdare.com 
//----------------------------------------------------------------------------

function ImageInfo(width,height,fileName,fullPath,exportIndex)
{
	this.width = width;
	this.height= height;
	this.fileName=fileName;
	this.fullPath = fullPath;
	
	// is this image rotated (0 or 90')
	this.angle = 0;

	// has this image been placed on the atlas?
	this.imagePlaced = false;
	
	// what page is this image on?
	this.pageIndex = 0;
	
	// location in export file. This can be modified by the user
	this.exportIndex = exportIndex;
	
	// position on atlas
	this.posX = -1;
	this.posY = -1;
};


--------------------------------------------------------------------------------
/changes.txt:
--------------------------------------------------------------------------------
1 | CHANGES

v0.7.4 - 02/08/2016 Margins were not being added to export file. Reported by Hassan via blog

v0.7.3 - 08/02/2014 - rewrote GetHomeDirectory(). Old method of finding working directory not working on latest Photoshop
Reported by Miq via blog

v0.7.2 - 07/01/2014 - AtlasMaker can now load any image format that Photoshop can handle

v0.7.1 - 29/10/2013 - Fixed a bug when sorting sprites. Reported by Jospic via blog

v0.7 - 24/11/2012 - 90% rewritten, merged Spritegrabber script into AtlasMaker

v0.6 - 21/03/2010 - AtlasMaker will not die if you have a src image
bigger than the dest document. Reported by Adam via blog

v0.5 - 25/11/2009 - AtlasMaker now handles empty pixels correctly
also, layers are now named after their src image.

v0.4 - 23/11/2009 - Fixed margin problems. Reported by ShaderMax via blog 

v0.3 - 04/10/2009 - AtlasMaker now compensates for the fact that 
photoshop trims empty pixels from selections. - rjd

v0.2 - 24/09/2009 - fixed a bug that stopped file export working
reported by Senthan via blog


--------------------------------------------------------------------------------
/test/create-test-images.jsx:
--------------------------------------------------------------------------------
 1 | //------------------------------------------------------------------------
 2 | // Generate some random test images for AtlasMaker
 3 | // 2019 Richard Dare - richardjdare.com
 4 | //------------------------------------------------------------------------
 5 | 
 6 | var numImages = 20;
 7 | var maxWidth = 100;
 8 | var maxHeight= 100;
 9 | 
10 | // set this to true to only make images of maxWidth * maxHeight - ie. tiled images.
11 | var fixedSize = false;
12 | 
13 | // where to save images
14 | var destDir = Folder.selectDialog("Select Destination Directory");
15 | 
16 | if(destDir!=null){
17 |     for(var i = 0;i<numImages;i++){
18 |         
19 |         var width = maxWidth;
20 |         var height = maxHeight;
21 |         
22 |         if(!fixedSize){
23 |          width = randomInt(maxWidth);
24 |          height= randomInt(maxHeight);
25 |         }
26 |    
27 |         var img = documents.add(width,height, 72.0, "AtlasMaker-test-00"+i,NewDocumentMode.RGB, DocumentFill.TRANSPARENT);
28 |         img.artLayers[0].applyClouds();
29 |         
30 |         var file = new File(destDir.absoluteURI+"/AtlasMaker-test-00"+i);
31 |         saveOptions = new JPEGSaveOptions();
32 |         saveOptions.embedColorProfile = true;
33 |         saveOptions.formatOptions = FormatOptions.STANDARDBASELINE;
34 |         saveOptions.matte = MatteType.NONE;
35 |         saveOptions.quality = 9;
36 |         
37 |         img.saveAs(file, saveOptions, true,Extension.LOWERCASE);
38 |         img.close(SaveOptions.DONOTSAVECHANGES);
39 |     }
40 | }
41 | 
42 | function randomInt(max) {
43 |   return Math.floor(Math.random() * Math.floor(max));
44 | }


--------------------------------------------------------------------------------
/include/Packer.jsx:
--------------------------------------------------------------------------------
1 | //----------------------------------------------------------------------------
// AtlasMaker
// Packer.js - Base class for an AtlasMaker Packing techniques.
//
// Author: Richard Dare
// richardjdare@googlemail.com
// http://richardjdare.com 
//----------------------------------------------------------------------------

function Packer(){};

// All packers must have a name. It's used in the main ui dropdown
Packer.prototype.name = "Undefined Packer";

// Does this packer rotate sprites? NOTE: rotation not implemented yet!
Packer.prototype.allowsRotation = false;

// Does the user want to rotate sprites?
// AtlasMaker will set this variable before running the packer.
Packer.prototype.usingRotation = false;

// width and height of atlas image.
Packer.prototype.atlasWidth = 0;
Packer.prototype.atlasHeight= 0;

// margin around each image.
// when images are passed to ONLINE packers, the margin is already added on.
// you only worry about this when writing OFFLINE packers.
Packer.prototype.margin = 0;

// this is used to report error messages to AtlasMaker.
Packer.prototype.errorFlag = false;

// this is an array of strings containing any error messages your packer
// wants to report.
Packer.prototype.errorMessages =[];

// the application will display a custom string for the packer at the top
// of the ui. Use this to present information to the user.
Packer.prototype.statusMessage = "";

//----------------------------------------------------------------------------
// Init() - AtlasMaker calls this when your packer is selected
// from the ui, before running the packer itself.
// Parameters: width  - user selected width of atlas
//             height - user selected height of atlas
//----------------------------------------------------------------------------
Packer.prototype.Init = function(width,height){return null;};

//----------------------------------------------------------------------------
// Calculate() - Perform texture atlas calculation.
// Parameters: allImages - an array of ImageInfo objects
//----------------------------------------------------------------------------
Packer.prototype.Calculate = function(allImages){return null;};

//----------------------------------------------------------------------------
// ClearErrors()
//----------------------------------------------------------------------------
Packer.prototype.ClearErrors = function(){errors =[];errorFlag = false};


--------------------------------------------------------------------------------
/include/TileGrid.jsx:
--------------------------------------------------------------------------------
1 | //----------------------------------------------------------------------------
// AtlasMaker
// TileGrid - basic tilemap packer for AtlasMaker
// This uses the functionality from the original SpriteGrabber script.
// Use this packer on tiles, or sprites that are all the same size
//
// Author: Richard Dare
// richardjdare@googlemail.com
// http://richardjdare.com 
//----------------------------------------------------------------------------

#include "Packer.jsx"
#include "ImageInfo.jsx"

// make TileGrid inherit from Packer
TileGrid.prototype = new Packer;
TileGrid.prototype.constructor = TileGrid;

//override data members
TileGrid.prototype.name = "Tile Grid";
TileGrid.prototype.allowsRotation = false;

//----------------------------------------------------------------------------
// Constructor
//----------------------------------------------------------------------------
function TileGrid(){
	this.docWidth = 0;
	this.docHeight= 0;
	this.docCols = 0;
	this.docRows = 0;
};

//----------------------------------------------------------------------------
// Init() - called when this packer is selected
//----------------------------------------------------------------------------
TileGrid.prototype.Init = function(width,height){
	this.docWidth = width;
	this.docHeight= height;
	this.docCols = 0;
	this.docRows = 0;
};

//----------------------------------------------------------------------------
// Calculate() - Create the tile grid
//----------------------------------------------------------------------------
TileGrid.prototype.Calculate = function(srcImages){
	// scan through the images and work out how big our tiles are

	var tileWidth =0;
	var tileHeight=0;

	for(var v in srcImages)
	{
		var i = srcImages[v];
		if(i.width > tileWidth)
			tileWidth = i.width;
		if(i.height > tileHeight)
			tileHeight = i.height;
	}

    // add on a margin
    tileWidth+=this.margin*2;
    tileHeight+=this.margin*2;

	// calculate rows, columns, number of pages needed
	this.docCols = Math.floor(this.docWidth/tileWidth);
	this.docRows = Math.floor(this.docHeight/tileHeight);

	var spritesPerPage = this.docCols * this.docRows;
	
	var numPages = Math.ceil(srcImages.length / spritesPerPage);

    // rjd: this will be displayed on the atlasmaker main ui
    this.statusMessage = "Rows:"+srcImages.length / this.docCols + "  Columns:"+ this.docCols + "  Tile Size:"+tileWidth+"px x "+tileHeight+"px";

	var count =0;
	for(var p=0;p<numPages;p++)
	{
		for(var y=0;y<this.docRows;y++)
		{
			for(var x=0;x<this.docCols;x++)
			{
				if(count>=srcImages.length)
					return true;

				var i = srcImages[count];
				i.posX = x * tileWidth;
				i.posY = y * tileHeight;
				i.imagePlaced = true;

				i.pageIndex = p;
				count++;
			}
		}
	}
	return true;
};


--------------------------------------------------------------------------------
/include/AtlasPacker.jsx:
--------------------------------------------------------------------------------
1 | //----------------------------------------------------------------------------
// Atlasmaker
// AtlasPacker.jsx - rectangle packer for Atlasmaker
// This just wraps Ivan Montes' RectanglePacker.js so it can be used in
// Atlasmaker
//
// Author: Richard Dare
// richardjdare@googlemail.com
// http://richardjdare.com 
//----------------------------------------------------------------------------

#include "Packer.jsx"
#include "ImageInfo.jsx"
#include "RectanglePacker.js"

// make it inherit from Packer
AtlasPacker.prototype = new Packer;
AtlasPacker.prototype.constructor = AtlasPacker;

//override data members
AtlasPacker.prototype.name = "Texture Atlas";
AtlasPacker.prototype.allowsRotation = false;

//----------------------------------------------------------------------------
// Constructor
//----------------------------------------------------------------------------
function AtlasPacker(){
	this.docWidth = 0;
	this.docHeight= 0;
	this.docCols = 0;
	this.docRows = 0;
    
    //----------------------------------------------------------------------------
    // CalcAtlas
    //----------------------------------------------------------------------------
    this.CalcAtlas = function(currentPage,sourceFiles){

        var nofit = 0;
        var packer = new NETXUS.RectanglePacker(this.docWidth, this.docHeight);
		
        for(var i=0;i<sourceFiles.length;i++)
        {
            var coords;
            var sourceImage = sourceFiles[i];

            if(!sourceImage.imagePlaced)
            {
                // rjd: calculate the margin: we put <docMargin> pixels on each side,like css margins.
                var m = this.margin * 2;

                // find out where to put the image...
                coords = packer.findCoords(sourceImage.width+m,sourceImage.height+m);
                if(coords)
                {
                    sourceImage.posX = coords.x;
                    sourceImage.posY = coords.y;
                    sourceImage.imagePlaced=true;
                    sourceImage.pageIndex = currentPage;
                }
                else
                {
                    nofit++;
                }
            }
        }
        return nofit;
    };
};

//----------------------------------------------------------------------------
// Init() - called when this packer is selected
//----------------------------------------------------------------------------
AtlasPacker.prototype.Init = function(width,height){
	this.docWidth = width;
	this.docHeight= height;
	this.docCols = 0;
	this.docRows = 0; 
};

//----------------------------------------------------------------------------
// Calculate() - make the atlas
//----------------------------------------------------------------------------
AtlasPacker.prototype.Calculate = function(srcImages){
    
    var imagesToPack = srcImages.length;
    var page=0;
 
	while(imagesToPack>0)
	{	
        imagesToPack = this.CalcAtlas(page++,srcImages);
	}
    
	return true;
};




--------------------------------------------------------------------------------
/include/ExportOrderWindow.jsx:
--------------------------------------------------------------------------------
1 | //----------------------------------------------------------------------------
// AtlasMaker
// ExportOrderWindow - This window lets the user specify the order of images
// in the export file. That way you can keep logically consecutive images
// together, no matter where they are on the atlas
//
// Author: Richard Dare
// richardjdare@googlemail.com
// http://richardjdare.com 
//----------------------------------------------------------------------------

#include "ImageInfo.jsx"

//----------------------------------------------------------------------------
// ExportOrderWindow()
//----------------------------------------------------------------------------
function ExportOrderWindow(){
    this.mainWindow;
    this.exportImages=[];
    this.orderBox;
    this.orderChanged;

    this.Open = function(exportList){
 
        // rjd: This is a bit crap. need deep copy
        this.exportImages = eval(exportList.toSource());
        this.exportImages.sort(this.SortByExportIdx);
  
        this.orderChanged = false;
        this.CreateUI();
        this.mainWindow.show();
	};
	
	//------------------------------------------------------------------------
	// CreateUI() - create export order window +  buttons
	//------------------------------------------------------------------------
	this.CreateUI = function(){
		this.mainWindow =new Window('dialog', "re-order export files");
		this.mainWindow.alignChildren = "fill";
		this.mainWindow.mainPanel = this.mainWindow.add("panel");
		this.mainWindow.mainPanel.orientation = "row";
		
		var mainPanelRef = this.mainWindow.mainPanel;
		
	//	mainPanelRef.leftCol = mainPanelRef.add("panel");
		//mainPanelRef.leftCol.preferredSize = [200,400];
		mainPanelRef.orderBox = mainPanelRef.add("listbox",undefined, '', {multiselect: true});

		mainPanelRef.orderBox.preferredSize = [200,400];
		mainPanelRef.orderBox.navItems = new Array();
		this.orderBox = mainPanelRef.orderBox;
		for(var i in this.exportImages)
		{
			mainPanelRef.orderBox.navItems[i] = mainPanelRef.orderBox.add("item",""+this.exportImages[i].fileName);
		}
		
		mainPanelRef.rightCol = mainPanelRef.add("panel");
		mainPanelRef.rightCol.preferredSize = [100,400];
		mainPanelRef.rightCol.upButton = mainPanelRef.rightCol.add("button",undefined,"up");
		mainPanelRef.rightCol.upButton.onClick = this.OnUpButton;
		mainPanelRef.rightCol.downButton = mainPanelRef.rightCol.add("button",undefined,"down");
		mainPanelRef.rightCol.downButton.onClick = this.OnDownButton;
		
		// kludge!
		mainPanelRef.rightCol.upButton.context = this;
		mainPanelRef.rightCol.downButton.context =this;
		this.mainWindow.bottomPanel = this.mainWindow.add("group");
		this.mainWindow.bottomPanel.orientation="row";
		this.mainWindow.bottomPanel.alignment="right";
		this.mainWindow.bottomPanel.okButton = this.mainWindow.bottomPanel.add("button",undefined,"Ok");
		this.mainWindow.bottomPanel.okButton.onClick = this.OnOkButton;
		this.mainWindow.bottomPanel.okButton.context = this;
		
		this.mainWindow.bottomPanel.cancelButton = this.mainWindow.bottomPanel.add("button",undefined,"Cancel");
		this.mainWindow.bottomPanel.cancelButton.onClick = this.OnCancelButton;

	};

	//------------------------------------------------------------------------
	// OnUpButton()
	//------------------------------------------------------------------------
	this.OnUpButton = function(){
		var selection = this.context.GetSelected();
		var orderBox = this.context.orderBox;
		
		if(selection[0]>0)
		{
            this.context.ClearSelection();
            var toBeMoved = orderBox.navItems[(selection[0]-1)].text;

            for(var i=selection[0];i<=selection[1];i++)
            {
                var x = orderBox.navItems[i].text;
                orderBox.navItems[i-1].text = x;
            }
            orderBox.navItems[(selection[1])].text = toBeMoved;

            for(var i=selection[0]-1;i<selection[1];i++)
                orderBox.navItems[i].selected = true;
		}
	};

	//------------------------------------------------------------------------
	// OnDownButton()
	//------------------------------------------------------------------------
	this.OnDownButton = function(){
		var selection = this.context.GetSelected();
		var orderBox = this.context.orderBox;
		
		if(selection[1] < orderBox.navItems.length-1)
		{
			this.context.ClearSelection();
			var v = parseInt(selection[1]) + 1;
			var toBeMoved = orderBox.navItems[v].text;
			
			for(var i=selection[1];i>=selection[0];i--)
			{
				var x = orderBox.navItems[i].text;
				orderBox.navItems[parseInt(i)+1].text = x;
			}
			orderBox.navItems[(selection[0])].text = toBeMoved;
	
			for(var i=parseInt(selection[0])+1;i<=parseInt(selection[1])+1;i++)
				orderBox.navItems[i].selected = true;
		}
	};

	//------------------------------------------------------------------------
	// OnOkButton()
	//------------------------------------------------------------------------
	this.OnOkButton = function(){
		//save changes to image list
		var orderBox = this.context.orderBox;
		var imageArray=this.context.exportImages;
		
		for(var i in orderBox.navItems)
		{
			var s = orderBox.navItems[i].text;
			for(var j in imageArray)
			{
				if(s == imageArray[j].fileName)
					imageArray[j].exportIndex = parseInt(i);
			}
		}

        this.context.orderChanged = true;
        this.context.mainWindow.close();
	};

	//------------------------------------------------------------------------
    // OrderWasChanged() - let caller know if export order was changed
    //------------------------------------------------------------------------
    this.OrderWasChanged = function(){
        return this.orderChanged;
    };

	//------------------------------------------------------------------------
	// GetReorderedImages() Let the caller retrieve reordered images
	//------------------------------------------------------------------------
    this.GetReorderedImages = function(){
        return this.exportImages;
    };

	//------------------------------------------------------------------------
	// GetSelected() - return an array containing the top and bottom of an 
	//  orderbox selection
	//------------------------------------------------------------------------
	this.GetSelected = function(){
		var topItem=-1;
		var bottomItem=-1;
		for(var i in this.orderBox.navItems)
		{
			if(this.orderBox.navItems[i].selected)
			{
				if(topItem==-1)
				{
					topItem = i;
					bottomItem=i;
				}
				else
					bottomItem = i; 
			}
		}
		return [parseInt(topItem),parseInt(bottomItem)];
	};

	//------------------------------------------------------------------------
	// ClearSelection()
	//------------------------------------------------------------------------
	this.ClearSelection = function(){
		for(var i in this.orderBox.navItems)
			this.orderBox.navItems[i].selected = false;
	};

	//------------------------------------------------------------------------
	// SortByExportIdx - sort the image directory by export order
	//------------------------------------------------------------------------
	this.SortByExportIdx = function(a,b){
		if(a.exportIndex>b.exportIndex)
			return 1;
		if(a.exportIndex<b.exportIndex)
			return -1;
		return 0;
	};
};


--------------------------------------------------------------------------------
/readme.txt:
--------------------------------------------------------------------------------
1 | ==========================================================================================
AtlasMaker v0.7.3
2009 - 2014

Richard Dare
www.richardjdare.com
richardjdare@googlemail.com
==========================================================================================

AtlasMaker is a Photoshop script for generating texture atlases and tile grids. In other words, it takes a directory full of images and arranges them into a single, larger image. It's intended primarily for game development, but can also be used to create CSS sprites for the web.

Features:
============================================
* Cross platform - tested in Photoshop CS3,CS4,CS5 on Windows and MacOSX.
* Open Source
* Several image sorting algorithms. Find the most efficient one for your textures.
* Add a margin to each image.
* Custom data file export
* Extendable - It's easy to add your own rectangle packing algorithms and sorting methods


Installing AtlasMaker
============================================

There are two ways of running AtlasMaker in Photoshop
Unzip atlasmaker-v0.7.1.zip to your photoshop scripts folder. On windows this is usually:
c:\Program Files\Adobe\Photoshop CSsomething\Presets\Scripts

On a Mac this folder is at:
Applications/Photoshop CSsomething/Presets/Scripts

When you next start Photoshop, AtlasMaker should appear in the File->Scripts menu.

Or you can run the script without installing by unzipping the atlasmaker folder somewhere, selecting Scripts->Browse from the file menu and then selecting AtlasMaker.jsx


Quick start guide
============================================

The first thing to do is select a directory of images by clicking "browse" at the top of the window. Once you have done this, AtlasMaker will scan through the images and collect size information about them.

You'll notice that some text will appear underneath "Number of Files". This is a notification from the Tile Grid Packer telling you how many rows and columns your images will take up given the default document size. Different packing methods provide different notification messages according to their nature.

Next, you want to select your packing method. If your images are texture maps of different sizes then you want to select the "Atlas Maker". If you are making a traditional 2d game where the sprites are all the same size, then you want to select the "Tile Grid"

Then you can optionally select a sorting method. Sorting the images in different ways can improve the efficiency of the texture atlas. Some packing methods do not allow sorting, and will disable this option if they are selected.

You can also add a margin here if you want a gap between your textures. Margins are added on to the width and height of each image just like CSS margins.

Next, click "Document Settings" and you will be able to set the size of the texture atlas you are going to create. You can also set the document name here, and choose if you want to flatten all the layers into one, once the atlas is complete.

Now click "Create Atlas" and you're done.

==========================================================================================
AtlasMaker Reference Guide
==========================================================================================

* Interface Overview
*  * File selection and notification area
*  * Panel selection area
*  *  * Atlas settings panel
*  *  * Destination image panel
*  *  * Export file panel
* Extending AtlasMaker

Interface Overview
============================================

The AtlasMaker interface is split into three main parts. The source file selection and notification area is at the top of the window. Below that are the texture atlas options, which have been split into three panels to save space. You can flip between each panel by clicking on the items in the panel selection area on the left hand side.

At the very bottom of the window are three self explanatory buttons. About, Create Atlas and Cancel.

File Selection and Notification Area
============================================

At the top of this area is the file selector. clicking "browse" will open a file requester that you can use to select the directory containing the images you want in your atlas. AtlasMaker will then scan through the images and make some initial calculations. AtlasMaker can load any images photoshop can. Any non-image files in the selected folder will be ignored.

Underneath the file selector is the notification area. It contains the following information:

Number of Images: How many image files are in the source directory.
Pages: How many pages, or individual texture atlases will be needed to hold them. 

The notification area can contain information provided by different packing methods. If you select the "Tile Grid" packer, you will see how many rows and columns the grid will be. The kind of notifications that appear here will depend entirely on the packing algorithm.

Items in the notification area may change when you edit atlas options.


Atlas Settings Panel
============================================

Packing Method: This dropdown contains the available packing methods. By default there are 2: "Tile Grid" and "Texture Atlas"

Sorting Method: This dropdown lets you choose how images are sorted before being put in the atlas. Different settings can result in better atlas generation depending on your data.

Reverse Sort: Tick this checkbox to perform the selected sorting method in reverse.

Rotate: Not implemented yet. In the future, AtlasMaker will be able to rotate images for improved packing.

Margin: You can add a margin of any number of pixels around each image in the atlas. It works just like CSS margins.


Destination Image Panel
============================================

Document Name: Set the Photoshop document name (not the filename) of the destination image. If you have multiple images, use the tag #n to substitute the page number into the text.

Width: The destination image width in pixels
Height: The destination image height in pixels

Merge Layers: By default, AtlasMaker will give each texture its own layer in the destination image. If this is checked, they will be merged down into a single layer.

Fill Background Layer with Background Color: This will create a filled background layer using whatever background color you have set in Photoshop.


Export File Panel
============================================

If you tick the “Enable datafile export” checkbox, AtlasMaker will create a text file, containing a chunk of text for each texture. Each chunk is generated from the text in the "Line Template" box. Tags are used to substitute information about each image into the text:

#i - Image index (0.. number of Images in directory)

#filename – Filename of source image

#width – Sprite width

#height – Sprite height

#x – X position of top left corner on spritesheet

#y - Y position of top left corner on spritesheet

#p – page number

Lets say your game engine loads textures or sprites like this: “TextureManager->GetSprite(x,y,width,height);” and you have 50 images to load. You can generate all 50 calls by entering the following into the line template box:

TextureManager->GetSprite(#x,#y,#width,#height);

AtlasMaker will then generate 50 lines containing the correct coordinates and dimensions for each Image.

You can enter multi-line text chunks, to create XML fragments for example, but you must use ctrl-enter for each newline.

Export File Name  - Browse: Use this to select the name and location of your export file

Reorder Export file: You can change the order of the images in the export file. This allows you to group related images together wherever they are on the atlas.

Clicking the button will open a window listing all the image files. You can select image files and move them around by clicking "up" or "down". You can shift-click to select multiple images and move them as a group.


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # AtlasMaker
  2 | ![AtlasMaker](/media/atlasmaker-screen.jpg)
  3 | 
  4 | AtlasMaker is a Photoshop script for generating texture atlases and tile grids. In other words, it takes a directory full of images and arranges them into a single, larger image. It's intended primarily for game development, but can also be used to create CSS sprites for the web.
  5 | 
  6 | ![Examples](/media/test-atlases.jpg)
  7 | 
  8 | *Created with AtlasMaker: left, a texture atlas with variable sized images. Right, a tile grid. Images used are randomly generated*
  9 | 
 10 | ## Features
 11 | * Cross platform - tested in Photoshop CS3,CS4,CS5,CC on Windows and MacOS X.
 12 | * Open Source
 13 | * Several image sorting algorithms. Find the most efficient one for your textures.
 14 | * Add a margin to each image.
 15 | * Custom data file export
 16 | * Extendable - It's easy to add your own rectangle packing algorithms and sorting methods
 17 | 
 18 | ## Installing AtlasMaker
 19 | There are two ways of running AtlasMaker in Photoshop.
 20 | Unzip atlasmaker to your photoshop scripts folder. On windows this is usually:
 21 | c:\Program Files\Adobe\Photoshop CSsomething\Presets\Scripts
 22 | 
 23 | On a Mac this folder is at:
 24 | Applications/Photoshop CSsomething/Presets/Scripts
 25 | 
 26 | When you next start Photoshop, AtlasMaker should appear in the File->Scripts menu.
 27 | 
 28 | Or you can run the script without installing by unzipping the AtlasMaker folder somewhere, selecting Scripts->Browse from the file menu and then selecting AtlasMaker.jsx
 29 | 
 30 | ## Quick Start Guide
 31 | The first thing to do is select a directory of images by clicking "browse" at the top of the window. Once you have done this, AtlasMaker will scan through the images and collect size information about them.
 32 | 
 33 | You'll notice that some text will appear underneath "Number of Files". This is a notification from the Tile Grid Packer telling you how many rows and columns your images will take up given the default document size. Different packing methods provide different notification messages according to their nature.
 34 | 
 35 | Next, you want to select your packing method. If your images are texture maps of different sizes then you want to select the "Atlas Maker". If you are making a traditional 2d game where the sprites are all the same size, then you want to select the "Tile Grid"
 36 | 
 37 | Then you can optionally select a sorting method. Sorting the images in different ways can improve the efficiency of the texture atlas. Some packing methods do not allow sorting, and will disable this option if they are selected.
 38 | 
 39 | You can also add a margin here if you want a gap between your textures. Margins are added on to the width and height of each image just like CSS margins.
 40 | 
 41 | Next, click "Document Settings" and you will be able to set the size of the texture atlas you are going to create. You can also set the document name here, and choose if you want to flatten all the layers into one, once the atlas is complete.
 42 | 
 43 | Now click "Create Atlas" and you're done.
 44 | 
 45 | ## AtlasMaker Reference Guide
 46 | * Interface Overview
 47 |  * File selection and notification area
 48 |  * Panel selection area
 49 |  * Atlas settings panel
 50 |  * Destination image panel
 51 |  * Export file panel
 52 | * Extending AtlasMaker
 53 | 
 54 | ### Interface Overview
 55 | The AtlasMaker interface is split into three main parts. The source file selection and notification area is at the top of the window. Below that are the texture atlas options, which have been split into three panels to save space. You can flip between each panel by clicking on the items in the panel selection area on the left hand side.
 56 | 
 57 | At the very bottom of the window are three self explanatory buttons. About, Create Atlas and Cancel.
 58 | 
 59 | ### File Selection and Notification Area
 60 | At the top of this area is the file selector. clicking "browse" will open a file requester that you can use to select the directory containing the images you want in your atlas. AtlasMaker will then scan through the images and make some initial calculations. AtlasMaker can load any images photoshop can. Any non-image files in the selected folder will be ignored.
 61 | 
 62 | Underneath the file selector is the notification area. It contains the following information:
 63 | 
 64 | Number of Images: How many image files are in the source directory.
 65 | Pages: How many pages, or individual texture atlases will be needed to hold them. 
 66 | 
 67 | The notification area can contain information provided by different packing methods. If you select the "Tile Grid" packer, you will see how many rows and columns the grid will be. The kind of notifications that appear here will depend entirely on the packing algorithm.
 68 | 
 69 | Items in the notification area may change when you edit atlas options.
 70 | 
 71 | ### Atlas Settings Panel
 72 | Packing Method: This dropdown contains the available packing methods. By default there are 2: "Tile Grid" and "Texture Atlas"
 73 | 
 74 | Sorting Method: This dropdown lets you choose how images are sorted before being put in the atlas. Different settings can result in better atlas generation depending on your data.
 75 | 
 76 | Reverse Sort: Tick this checkbox to perform the selected sorting method in reverse.
 77 | 
 78 | Rotate: Not implemented yet. In the future, AtlasMaker will be able to rotate images for improved packing.
 79 | 
 80 | Margin: You can add a margin of any number of pixels around each image in the atlas. It works just like CSS margins.
 81 | 
 82 | ### Destination Image Panel
 83 | Document Name: Set the Photoshop document name (not the filename) of the destination image. If you have multiple images, use the tag #n to substitute the page number into the text.
 84 | 
 85 | Width: The destination image width in pixels
 86 | Height: The destination image height in pixels
 87 | 
 88 | Merge Layers: By default, AtlasMaker will give each texture its own layer in the destination image. If this is checked, they will be merged down into a single layer.
 89 | 
 90 | Fill Background Layer with Background Color: This will create a filled background layer using whatever background color you have set in Photoshop.
 91 | 
 92 | 
 93 | ### Export File Panel
 94 | If you tick the “Enable datafile export” checkbox, AtlasMaker will create a text file, containing a chunk of text for each texture. Each chunk is generated from the text in the "Line Template" box. Tags are used to substitute information about each image into the text:
 95 | 
 96 | **\#i** - Image index (0.. number of Images in directory)
 97 | 
 98 | **\#filename** – Filename of source image
 99 | 
100 | **\#width** – Sprite width
101 | 
102 | **\#height** – Sprite height
103 | 
104 | **\#x** – X position of top left corner on spritesheet
105 | 
106 | **\#y** - Y position of top left corner on spritesheet
107 | 
108 | **\#p** – page number
109 | 
110 | Lets say your game engine loads textures or sprites like this: “TextureManager->GetSprite(x,y,width,height);” and you have 50 images to load. You can generate all 50 calls by entering the following into the line template box:
111 | 
112 | TextureManager->GetSprite(#x,#y,#width,#height);
113 | 
114 | AtlasMaker will then generate 50 lines containing the correct coordinates and dimensions for each Image.
115 | 
116 | You can enter multi-line text chunks, to create XML fragments for example, but you must use ctrl-enter for each newline.
117 | 
118 | Export File Name  - Browse: Use this to select the name and location of your export file
119 | 
120 | Reorder Export file: You can change the order of the images in the export file. This allows you to group related images together wherever they are on the atlas.
121 | 
122 | Clicking the button will open a window listing all the image files. You can select image files and move them around by clicking "up" or "down". You can shift-click to select multiple images and move them as a group.
123 | 
124 | 


--------------------------------------------------------------------------------