ConvertHGR - A simple image converter for Apple2 HGR Mode
---------------------------------------------------------

Really basic - launch it, then either click 'open' or drag and
drop your image file onto the window. It will be converted for
the Apple2's HGR Bitmap mode. There are no options for other modes.

There are a few controls available once the image is loaded:

-Nudge Right & Left - because Bitmap mode has color 
limitations for every 7 horizontal pixels, you can sometimes 
get a better result by shifting a few pixels. It never makes
sense to shift more than 7 pixels, so the program will stop
there. Usually after 4 pixels you are better off trying the
other direction. Loading a new image clears the nudge count.

-Nudge Up & Down - these shift the image up and down one pixel
at a time. Hold Shift for two pixels at a time, hold control for
4 at a time, and hold shift and control together for 8 at a time.
Up and Down refers to the virtual 'camera' direction and only
applies if the image is larger than the display due to one of 
the 'Fill Mode's in the options being set. Scrolling farther
than is possible will simply make it stop moving - the counter
will still change. You can see this in the output text window.
Loading a new image clears the nudge count.

-Stretch Hist (Hist) - this stretches the histogram of the 
image to improve contrast and enhance colors. It can also cause 
a pretty severe color shift, but in some cases it helps the 
detail of the image.

-Use Perceptual Color matching (Perc) - this changes the color
matching system to favour a model of human color visibility,
giving green the most importance, red second, and blue third.
This can often improve an image and provide more pleasing 
results, although it can sometimes result in more color shift.

-Greyscale - converts the image to greyscale on load, before any
filtering or conversion takes place. The limited Apple2 palette
is often able to render scenes more pleasingly in this mode.

-Green View - converts the image to a representation of how it
may look on a monochrome monitor, with the color removed. Note
that half-pixel representations are not displayed, but will be
saved correctly. It does not matter if you save in color or green
mode, the same data will be written. Restore the color view
with the Reload button.

-Dithering - This system uses dithering to improve the apparent 
color accuracy of the image. You can change the error distribution 
in the dialog. Each value indicates the ratio, out of 16, of the 
error that goes to that pixel. In addition, three buttons set
recommended defaults:

Floyd-Stein - sets Floyd-Steinberg dithering
Pattern - sets a regular ordered dither (every other pixel, old Ordered)
Order1 - true ordered dither with 2x2 matrix and offset adjust (use the slider)
Order2 - ordered dither with 2x2 matrix and error distribution
Order3 - true ordered dither with 4x4 matrix and offset adjust (use the slider)
Order4 - ordered dither with 4x4 matrix and error distribution
No Dither - disables dithering

Note that if the total of all values entered is less than 16,
some of the error will be lost (sometimes you may wish this!). 
If the value is more than 16, errors will accumulate and may 
induce artifacts.

The 'error mode' has two values that control how the software
deals with error correction distributed from multiple pixels.
In most cases, a pixel will receive error distribution data from
three other pixels. 'Average' mode (the default) will use the
average error when calculating a new pixel. Accumulate is the
old mode, and lets the error total up when calculating a new
pixel. Average is arguably more correct but sometimes Accumulate
gives better results (although it is usually noisier).

The setting "Luma Emphasis" scales the brightness component of each
pixel by the entered amount to control the importance of brightness
versus color. If greater than 100%, then brightness is more important,
if less, then color is more important. If 100%, then both are equally
important.

Max Color Shift controls how far each color is allowed to shift
towards a legal Apple2 HGR color BEFORE dithering takes place. This
reduces the amount of dithering at the expense of a more pronounced
color shift. Values greater than 10 or 15% will generally result in
a full color remap with little to no dithering, so keep it low!

You can set the ratios used for the Perceptual filter. Set a value
from 0-100 percent for each of the red, green and blue channels.
Ideally they should total 100, otherwise the image will definately
change. A lower value indicates that the quality of the match is
less important (allowing the color to substitute for others). A
higher value means the quality of the match is more important -
in non-perceptual mode all three have a setting of 33.3%. The default
settings are based on the scale traditionally used for converting RGB 
to luminence, with slight adjustment to taste.

When not using Perceptual mode, you can set a Luma Emphasis, this controls
how much more important brightness changes are than color changes.
Lower values tend to wash out the image, higher values tend to create
more noise.

The 'Gamma' setting applies a Gamma correction to the original image.
The value entered here is treated as a percentage, so 100 is equal to
a gamma of 1.0 (no correction). Higher values will brighten dark areas,
lower values will increase shadows.

This dialog also allows you to choose between various
resizing filters, the default is bilinear.

It also has a dropdown for a 'fill mode'. This affects images
which are not in a 4:3 ratio. In Full mode (the default), the
entire image is scaled to fit. Otherwise, the image is scaled
so that the smaller axis fits the screen, and the rest is
cropped off based on your setting, which can be top/left,
middle, or bottom/right (the setting is what part is kept).

-Open - opens a new file. Many standard image types
are supported. Files which are already in Apple2 format
are not supported at this time.

-Save Pic - saves the picture either as a memory dump (.HGR)
or as a new DOS 3.3 compatible DSK image (.DSK). In the case
of the DSK image, a bootable DOS3.3 disk will be written with
the file named "HGRFILE", and a small HELLO program to display
it. Note that the disk format is fixed and the HGRFILE will
always be stored starting on track 18, sector 0.

Note that the image is briefly displayed in green-mode during
saving, then reloaded afterwards.

-Reload - most configuration and setting changes do not re-render
the image, because of how long this takes. Press Reload to reload and
re-render the image. If you try to save without pressing Reload,
the system will remind you.

A Special mode also exists where you can randomly
browse an entire folder (this was me being silly). 
Double click anywhere on the dialog where there is no
button, and 'Open' will become 'Next'. Click it, and
select a file in a folder you would like to browse.
All images in that folder (and all subfolders) will
be available in random order each time you click 'Next'.
You can process and save any you like. To exit this
mode you must close the program.

Finally, there is a simple command line interface.
Passing one filename will cause that image to be loaded and
displayed in the GUI automatically.
Passing a second makes the result automatically be saved to
that filename without displaying the GUI. Two files will be
saved, an HGR (memory dump) file, and a BMP showing the result.
Pass "/?" to see other options, but most are just overrides
for the INI file.

Due to the large number of options and the differences between
images, getting pleasing output is a bit of an art. Try playing
with one option at a time, reloading each change, to get a feel
for how each affects the image.

This program uses the ImgSource Library by Smaller Animals Software.

//
// (C) 2023 Mike Brent aka Tursi aka HarmlessLion.com
// This software is provided AS-IS. No warranty
// express or implied is provided.
//
// This notice defines the entire license for this software.
// All rights not explicity granted here are reserved by the
// author.
//
// You may redistribute this software provided the original
// archive is UNCHANGED and a link back to my web page,
// http://harmlesslion.com, is provided as the author's site.
// It is acceptable to link directly to a subpage at harmlesslion.com
// provided that page offers a URL for that purpose
//
// Source code, if available, is provided for educational purposes
// only. You are welcome to read it, learn from it, mock
// it, and hack it up - for your own use only.
//
// Please contact me before distributing derived works or
// ports so that we may work out terms. I don't mind people
// using my code but it's been outright stolen before. In all
// cases the code must maintain credit to the original author(s).
//
// Unless you have explicit written permission from me in advance,
// this code may never be used in any situation that changes these
// license terms. For instance, you may never include GPL code in
// this project because that will change all the code to be GPL.
// You may not remove these terms or any part of this comment
// block or text file from any derived work.
//
// -COMMERCIAL USE- Contact me first. I didn't make
// any money off it - why should you? ;) If you just learned
// something from this, then go ahead. If you just pinched
// a routine or two, let me know, I'll probably just ask
// for credit. If you want to derive a commercial tool
// or use large portions, we need to talk. ;)
//
// Commercial use means ANY distribution for payment, whether or
// not for profit.
//
// If this, itself, is a derived work from someone else's code,
// then their original copyrights and licenses are left intact
// and in full force.
//
// http://harmlesslion.com - visit the web page for contact info
//

