SpriteHoe
by Black Squirrel


WHAT IT DOES ====================================
SpriteHoe kills wasted space in sprite sheets, or at least tries to. In a perfect world, SpriteHoe would do nothing, for a perfect world means perfect sprite sheets, i.e. those without wasted space. SpriteHoe aims to make sprite sheets a bit more compact in terms of resolutions, thus minimising bandwidth, loading times, memory etc. etc. The contents aren't compromised and the process takes mere seconds. It's all good news.

Images passed in are processed and churned out (by default) as "xxx_cropped.png". So if you throw in "Mario.png", you'll get "Mario_cropped.png". The original source will not be deleted unless you demand it to be.

As a bonus, it'll also convert BMPs and GIFs into PNGs. For all sprite sheets should really be in PNG format.


WHAT IT DOESN'T DO =============================

SpriteHoe is not here to compete in FASTEST PROGRAM or MOST EFFICIENT competitions. It merely does one job - make tacky sheets slightly less tacky. 

SpriteHoe does not "fix" sprite sheets. It does no aligning of individual frames of animation (because alignment depends on the animation). It does not "organise" sheets in any way. For perfect sheets use an image editor and sort out the mess by hand.

SpriteHoe does not preserve invisible "grids" which GOOD sprite sheets may conform to. It is designed to make a bad job better - a good job may be made worse.

SpriteHoe cannot identify extreme levels of idiocy. If someone has written "BLANK SPACE" in the blank space, it will not crop this space out fully. It does not get along well with text, so if text needs to be added, save it until after SpriteHoe has worked its magic.

SpriteHoe will convert images to 32-bit RGBA format during the operation. 99% of you won't care. For the 1% who demand that palette entries be organised in a certain way, you will lose this information during the process (though I should stress, there is no colour loss of any sort).

SpriteHoe does not handle GIF or APNG animations, JPEGs or one of your kray-zee propriatary formats.

It also doesn't run insanely fast or efficiently, as it was built in Java and I'm no Java expert. It is only compatible with Windows-based computers.


WHAT IT WILL PROBABLY NEED=====================

The Java runtime environment (a reasonably up-to-date version). Most people who have used the internet in the last five or so years should have installed this at some point, and will have been whined at if it isn't up to date.

If not:

http://www.java.com/en/download/

Notepad (or even better, Notepad++) is a good choice for editing that batch file too.


IMPROVING PERFORMANCE =========================

SpriteHoe takes, by default, the top left pixel as the "background colour". If the sprite sheet author has been silly and has applied borders, SpriteHoe may need to be run more than once, the first time (hopefully) stripping the image of its borders. Complicated borders will confuse SpriteHoe, so it's best to try and remove them.

I already said text doesn't get on with SpriteHoe getting rid of that and any other unnecessary stuff (such as very large images) will help it.

Success is more likely if your sheet is "rectangular", rather than "square". Wider or taller images increases the likelihood of SpriteHoe generating cells. You're best not shoving all your animations on one line though - SpriteHoe currently gets confused and will start aligning things upwards if you do. A potential fix for version 2.0 if it is released.


HOW IT WORKS ===================================
SpriteHoe goes through some relatively easy steps:

1. Cycles through the image to find wasted rows and columns of pixels. "Highlight" them, creating a wonky grid with cells of varying widths and heights.
2. Cycles through each cell in the same way.
3. Crops out highlighted sections. Moves the contents upwards and to the left if possible.
3. Cycles through new image, picking up a second set of wasted rows and columns which may have been created by the above step.
4. Crops out all remaining wasted space. Moves the contents upwards and to the left.
5. Save, and we're done.


ARGUMENTS ======================================
SpriteHoe has a few special options, all of which are turned off by default. Tag them on the end of a command and you'll get FASCINATING results.

--gloat
Enables "gloat mode". Under this mode, SpriteHoe does no cropping at all - it just draws red and blue lines where wasted space has been calculated. Fun for message boards if you want to rub this sort of thing in people's faces.

--debug
Enables "debug mode" and thus has the console throw out some potentially meaningless technobabble.

--replace
Replaces the source file with the new one, rather than creating a new copy. Useful for batch processing, not so much if you don't like the results, as the process cannot be reversed, hence why I had this disabled by default.

--deresize
Enables "intelligent de-resize", which, as the name suggests, de-resizes images "intelligently". So if you've got a sprite that's been stretched by a quirky figure such as 59%, SpriteHoe will attempt to restore the original image. Emphasis on "attempt" though - it is not (yet) smart enough to deal with simple sprites where repetition is more common.

RELEASE NOTES ==================================

2.0 (9/09/2011)
- Added "intelligent de-resize".
- "--" arguements work as well as "-" ones. If that makes sense.
- Some code cleanups. It might run 0.00000001% faster now.
- Bugfixes
-- #1: Program hangs if last row (but not second-last) needs cropping.
-- #2: If not supplied with an image, SpriteHoe may try to "open" other arguements.


1.0 (05/08/2011)
- Initial Release

DISTRIBUTION AND THE LIKE ======================
SpriteHoe is free to distribute but it would be very nice if in doing so, you shove this readme along with it.