:title Image Collector
:label imageCollector

** Contents **~~
<<imageCollector#startupImages|Startup>>~~
<<imageCollector#loadImage|Load an image>>~~
<<imageCollector#loadAnimationImage|Load many images>>~~
<<imageCollector#animationImage|Build animation from images>>~~
<<imageCollector#colorTransformationImage|Color Transformation>>~~
<<imageCollector#selectionImage|Selecting image parts>>~~
<<imageCollector#groupTransformationImage|Group Transformations>>~~
<<imageCollector#buildAnimationImage|Build Animations>>~~
<<imageCollector#filteringImage|Apply/build Filters>>~~
<<imageCollector#originImage|Origin Notice>>~~
<<imageCollector#savingImage|Save as one Image>>~~
<<imageCollector#exportImage|Export>>~~
 
:image ImageCollector1.png|Image Collector example|fileopen
:anchor startupImages

For information regarding the wording used (Image, ImageInstance, ImageSequence, ImageCollection) see the FAQ -> Wording.

The Screen is divided into a couple of sections:~~
1) Top Section~~
In the top section the ImageCollection management stuff is shown. ImageCollections can be loaded saved and divided into classes.

2) Left Side~~
On the left side you can see the current loaded ImageCollection displayed with the corresponding ImageSequences. You can select the ImagesSequence using the mouse button.

3) Right Side~~
The current loaded image is displayed in the image area. Selections can be made with the mouse. The slider can be used to adjust zoom settings.

4) Middle Section
Here is where all the "music" plays. See further explaination below.


:h2 File
What is "File"?
An ImageCollection is saved to a simple (xml) file, which includes all information about the ImageCollection.
The ". . ."-Button opens a file dialog to open such a collection. To save to a new collection you MUST enter a filename.
Some operations to images / collections are only possible if a filename (and a class) is given.

:h2 Class (es)
Each collection of images can (must) be divided (at least one) into classes. 
All classes and all image-information in those classes are saved into one (xml) file (see above). 
To allow distinguishing images in one ImageCollection, you can also give each ImageSequence a specific class. All ImageSequences that have the same class in one ImageCollection are displayed together.~~
E.g.~~
Filename:~~
____Nature (the ImageCollection will be saved to a file in directory "xml/Graphics" named "Nature.xml")~~
Classes:~~
____Rocks~~
____Trees~~
____Flowers~~
etc.~~
Some operations to images / collections are only possible if a class (and a filename) is given.

:h2 Load an image
:anchor loadImage
The first thing when you start working with TT will be to load an image, from which you might want to extract single image entities (ImageInstances).
To load an image you press the ". . ."-Button next to the textfield labled "Image source". A Dialog like:~~
:image loadimage.png|Load a multi image|fileopen
will be opened.~~
You select the image to be opened in the dialog box. In the above example a special case is shown, where each image of an animation called "FlyingSoul" is available as a seperate image file. ~~
~~
In the help file many proceedings will be explained by doing a step by step instruction to build an animated ImageCollection. ~~Therefor to stay with the example lets assume the image "flying e0000.bmp" was selected.
(notice there are alltogether 16 file called "flying e00x.bmp")
~~
After pressing Ok, the selected image is loaded and shown on the right side of the window in the image view area.~~

Supported image-types are:~~
JPG, BMP, PNG, GIF~~

:h2 Image view area
On the right side of the screen an area is shown which is at the beginning showing a checkboard pattern to symbolize the area is "empty". After loading an image file, the area shows the loaded image. ~~
If the image is larger than the display - it may be scrolled.~~
Next to it is a slider with which you can adjust to a zoom factor of your chosing.~~
Using the mouse on the area you can select an area of the image as the "current" selection. The selection is than also shown in the smaller area to the left labeled "current" selection. The selection parameters are displayed in the source image section (coordinates, width, height etc).

:h2 Load an animation set of images
:anchor loadAnimationImage

With the exmaple started in **"Load an image"** one can also load the whole animation set. To load a number of images at once and collect them into one ImageSequence, the filenames must be formated as:~~
- a fixed filename~~
- with a counter at the the end~~
- the counter must be zero filled to the highest used digit~~
- the numbering is zero based (first images filename ends with 0)~~
~~

Following these rules you can enter the image count in the textfield labeled "Count". After pressing the button "Add file series" all images are loaded and displayed on the bottom of the screen in the ImageSequence display.
~~

**New**~~
If you want to load multiple images for an animation you can as of now also just multiselect the images you want to load. All selected images will be loaded as a sequence. (The old way still also works)~~

~~
This looks than like:
:image multiimage.png|ImageSequence|fileopen

:h2 Animations
:anchor animationImage
At this point the first animation is more or less "done". The ImageInstances of the ImageSequence are still distributed over many single image files. This can be "corrected" by pressing the button "Save Anim image". After pressing the button, the whole ImageSequence is saved to a new image (png) file, which holds all ImageInstances of the current ImageSequence.~~
Clicking one of the ImageInstances of the ImageSequence and thus selecting the  ImageInstance as current selection and pressing the button "Get source" will display the newly created image in the image area to the right.~~
Pressing the toggle button under "animation" called "play" will play the animation (you might want to enter an animation delay parameter, the delay is measured in milliseconds).

:h3 As one animation sequence
The animation as of now is not yet part of an ImageCollection. You can add the current ImageSequence to the collection by pressing the button "Add as (anim) image". By pressing the button the current ImageSequence is added to the collection and the collection is saved.~~
If an ImageSequence with the same name is already part of the collection the saving is cancled (tick the "replace if name exists" checkbox to overwrite).
~~The current situation should look like:
:image singleAnimSourceImage.png|ImageSequnce|fileopen

:h2 Color Transformations
:anchor colorTransformationImage
The image above has a set background color. In many situations, when you want to use an animation, it is preferable to have parts of the animation non opaque.~~
You can set any color to have an alpha channel of 0 very easily using TT.~~
To stay with the above example...~~
In the middle of the screen there is a tab called "Color transformation". Select that tab. ~~
:image ColorTrans1.png|ImageSequence|fileopen
With the mouse go to the image area and click any spot with the color you would like to be transparent. In the example click an "gray" spot.
You will see that the color-values in the "Color at Cursor" fields will be changes accordingly.
When pressing the button "All selected Color to Background" - well the chosen color will be set to have an alpha channel of 0.~~
To preserve the changes for future generations you should save the "new" image using the "Save Image" button.~~
(In order for the changed to take effect on the current ImageSequence, the ImageSequence **must** already be part of an ImageCollection, and the button "Re Set" must be pressed. This is neccessary, since all images are cached by TT. The "Re Set" clears the cache and reloads all images)
~~The result should look like:
:image ColorTrans2.png|ImageSequnce|fileopen

:h3 Adjusting color of an ImageSequence
In the second half of the Color Transformation tab there are couple of spinners, for RGB and HSB adjustment. These spinners adjust the colors of the current imageSequence. Therefor these settings might as well belong to the tab "Group transformation" 

:h2 Crop
:anchor cropImage
As you see in above images, animations and other images can have much spare "room" about them. This room occupies memory which might well be used for other more important stuff. These images can be cropped to the size which they actually occupy.~~
For ImageSequences (aka animations) this can be problematic, since each ImageInstance of such a sequence may have differing crop parameters. An ImageSequence of differently cropped ImageInstances may look weird. ~~
All of this can be taken into account, when croping is done by TT.~~
First - switch to the tab called "Crop".~~
The easiest and safest way to crop an ImageSequence is to not change any settings on the tab. Press "Crop image independend". (No actual croping is done yet - only the croping parameters are cacluclated and displayed). ~~
Keep the checkboxes "Keep Offset" (unselected) and "internal Offset" (selected) as they are and press "Apply Crop".
After that - the ImageInstances of the sequence are: ~~
- all cropped
- the minimal boundaries of all images put together are calculated
- each image gets an "internal" offset in relation to these boundaries
- the animation can be shown (using these offsets) as befor, without the ImagesInstances "bumping" arround
:image CropDone.png|Crop done|fileopen
~~
This is what you should almost allways want to do.~~
In case you like experimenting with croping, here the short explaination of the checkboxes on the crop tab:~~
- "Keep Offset": If selected the offset of the images after apply crop are kept even in a single tile. This is usefull when using fixed sized tiles, which are only partially pixeled. 
- "internal Offset": If selected the offsets of the image after apply crop are kept for the best animation offset. Each resulting image has the same size. If NO checkbox is selected each image in the animation has its own crop settings! 
~~
~~
If croping was done and an internal offset was calculated, you can use these (as explained above) to correctly display animations. On the left side the two areas ("Current selection" and "Animation") both have underneath checkboxes called "of". If selected the calculated internal offsets are used in the display - the ImageSequence should be displayed "clean". If the checkboxes are not selected, the image is displayed with optimal croping (might be bumping).

:h2 Select a sub image / Select many sub images
:anchor selectionImage
In the image Aarea on the rigth side, using the mouse you can select a sub image. The corresponding parameters are displayed in section titled "Source image(s)".~~

:h3 Grid/Lock/Order
You can build ImageSequences from a single image with the facilities offerd by the mechanisms of the "Source image(s)" area, as there are:~~
- **Height / Width**: Display or input of the current selected images width and height.
- **PosX / PosY**: Display or input of the current selected images position in the image area.
- **Lock**: Locks the current height and width, you can use the mouse to move the selection area.
- **Apply**: Apply the current parameters to the image area.
- **Paint seletion**: Draws a colored rectangle on the image area of the current selection.
- **Multi selection in image**: You can enter a "grid" of selections which can be added to the current ImageSequence. The grid is built from several parameters:~~
1) XStart/YStart: where the grid begins
2) XGap/YGap: how big is the gap between to grid selections
3) Width/Height: The width and height of the grids single selections is taken from the "single selection image" parameters
4) X# and Y#: how many grid selections horizontally or vertically
5) all #: overall limit of grid selections
6) vertical first: default is left/right and top/down. If selected the default ordering changes to top/down, left/right.

The two buttons: "Add single selection" and "Add series" do what you would expect of them.

Here an example of a multi selection image after the "Add series" button was pressed.
:image AnimFrom1.png|Animation frm single image|fileopen

:h2 Group transformations
:anchor groupTransformationImage
There are a couple of transformations that can be applied to an ImageSequence:~~
- Scale (each ImageInstance is scaled to size)
- Canvas Size (original ImageInstances scale is kept, ImageInstance is centered)
- Opacity (set opacity for the ImageSequence)
- Rotate
- Mirror 
- Create seamless (double mirrors current image -> double size, but seamless)

All of these are fairly self explainatory and will not be further documented.

:h2 Build animations
:anchor buildAnimationImage
There are a handull of animations, which can be automatically built from an ImageInstance. Animation building is accessed via the tab: "Build animation"
- Rotation (angle: 0 - 360)
- Opacity (transparancy: 0-255)
- scaling (size in percent: 1-100)
All animations require information about how many steps between start and end should be built , and a starting and end value .~~
When hitting the "Apply" button the corresponding new generated ImageInstances are added to the current ImageSequence.

:h2 Add to ImageCollection
There are two different methods of adding a ImageSequence to an ImageCollection.
1) Press the "Add as (anim) image"~~
With that you add the current ImageSequence as ONE ImageSequence to the current ImageCollection (remember, Filename and Class must be provided).
2) Press the "Add as multiple images" button.~~
With that you add each ImageInstance of the current ImageSequence as an individual ImageSequence to the ImageCollection. This is usefull, if you have a tile collection of different tiles, which you have in a single Image. The tiles in the image can be seperated using the multi selection explained above. Naturally, you do not want that ImageSequence of different tiles to appear as an animation in your ImageCollection. 
Example: the bonus of a PacMan game, collected via multi selection, and added using above described method:
:image MultiImages.png|Multi Images|fileopen

:h2 Filtering
:anchor filteringImage
This one is rather complex. The background why this tab was created lies in the way tiles may be used to create a tilemap. The main reason this tab was implemented is a technique called **Tile Transition**. ~~
For a very good explaination, and the only in TT fully implemented tile transition look at the following web page:~~
[[http://www.gamedev.net/page/resources/_/technical/game-programming/tilemap-based-game-techniques-handling-terrai-r934|Tile/Map-Based Game Techniques: Handling Terrain Transitions]]
The short form is, that you can built terrain transition tiles between two terrains of a map using about 30 variations of one tile, and blend that tile over the other terrain. You can also implement a priority between terrain types.~~
In the following image you can see the transition types. 
:image TileTransition.png|Tile Transition variations|fileopen

The gray area represents the area where the tile is kept "intact". The black area represents where the tile from the different terrain will "shine thru"

The filter tab contains two different functionalities. On the left side titled "Source" with an apply button and on the right side something call "Meta-Filter".

:image Filtering.png|Filtering|fileopen

:h3 Filtering
Here you can select an ImageCollection, a class in the collection and an ImageSequence within that class. That selected ImageSequence will in the following be called "Filter". If you "apply" that filter to the currently selected ImageSequence (from now on called "Source") following will happen:
a) The size of the filter images will (internally) be resized to the size of the current source
b) for each image of the source ImageSequence, each of the filter ImageSequence images will be "applied" in the way: 
- a new image (target) will be created (and added to the source ImageSequence), the target image will consist partly of the source image and partly of the filter image
- for each pixel where the color of the filter image is not black (0,0,0 -> RGB) the pixel of the filter image will be copied to the target image
- for each pixel where the color of the filter image is black (0,0,0 -> RGB) the pixel of the source image will be copied to the target image
- Also: for each pixel where the color of the filter image is black (0,0,0 -> RGB) the pixel of the target image will receive the alpha value of the filter image of that corresponding pixel

With that method you can generate quite easily and nearly automatic ImageSequences for tile transitions. [Perhaps some other usages might be interesting to]

Example:
1) For the filter you can select the collection: "xnaExample"
2) Class: MaskBase
3) ImageSequence: FilterArtifact2
You can not see it in that selection, but the above ImageSequence looks like:
:image TransitionSequence.png|TransitionSequence|fileopen

If you hit apply for example for the following scenario:
:image PreTransition.png|example one grass|fileopen

The result will look like:
:image PostTransition.png|Example artifact grass|fileopen

If you save these images as multiple images, you can later use them with the TT-TileManager to create transition tiles.

:h3 Meta-Filter
As seen in the last section, applying filter (once you have filters) is quite easy.
But to create thirty or so transition filters is quite tedious. For that reason the section Meta-Filter was built.~~
Current implementeded only meta-filter option is "Built Artifact transition filter" - you can do exactly what it says. As input you need three of the 30 required filters. With these three you can build (due to symetry) the other filter images automatically.~~
Following filter images must be present.
:image PreMetaFilter.png|Meta TransitionSequence|fileopen

By hitting the button - all other artifact filters are built automatically:
:image TransitionSequence.png|Full TransitionSequence|fileopen
(You still have to save them to the current collection...)

Well the whole idea is not to use the above examples, but to built meta-filters of your own, so that smooth and approriate transitions can be made!

**Note to Filtering**~~
Although there is no special support for ISO filtering, the above descriped 
filterings can also be used to create ISO-Filters.~~
Just do "normal" filtering:~~
a) rotate the result by 45 degrees
b) adjust the size (scaling)

For many filters this might be sufficient enough.

But remember for nice ISO views the sides of the filter might be required not to be equal, a simple ISO filter from a Meta-Filter will miss the different angles.
So in order to have **good** ISO filter you might do all required transition filters by hand.


:h2 Origin Notice
:anchor originImage
Each Image, can (should) have an origin notice. Hopefully you have the right to use the image. If you start with your collection you can (should) give credit to the artist(s). You can enter the credit information using HTML tags (switch between source and parsed view).
:image origin.png|Origin notice!|fileopen

:h2 Save class as new single image
:anchor savingImage
Using the button (top of the window) "Save class as new single image" you can save the complete class of your ImageCollection as ONE new Image. The ImageCollection, each ImageSequence and each ImageInstance will be adjusted to use that image.

:h2 User export
:anchor exportImage
Using the "User Export" button, you can export your ImageCollection - or the ImageSequence or whatever - to a format you like or would like to use. 
Per default all data is saved in a XML-Format in a subdirectory called "xml/Graphics".~~
With the user export you can code your OWN specific export routines in java.
An example is given to export the data to another even simpler xml-format. The library used to implement the export is called Java-Beanshell. The syntax is very much like (old) Java (no template support e.g.). But nonetheless you can very easily export to any format you like. Example:~~

:image UserExport.png|User Export|fileopen

