DXF Halftone version 2.1
This software is released under GNU General Public License v3.0

This program can be used to preview and create a halftone patterns from png, jpg and bmp images.
The created pattern can then be exported to the dxf file format. GCode toolpath can also be made for V-Bits to cut the pattern with a CNC machine.

You can check my other projects & new versions of this program at my site:
http://www.students.tut.fi/~syvajar3/
Or at Youtube:
http://www.youtube.com/user/metalfusionf

----------------
Version History:
----------------

4.9.2011 V 2.1

Polishing, some important fixes.

IMPROVEMENTS / FIXES:
-Fixed multiple problems with path width calculation algorithm.
-More accurate results with large line spacing values.
-Much less noise / artefacts with small resolution source images.
-Fixed path endpoint sizing problems.
-Improved performance with large image files.
-Optimised toolpath generation ( shorter rapids ) for dot halftones.
-Added "optimiserapids" option to save file format. When set to zero, all path filler lines will be run in the same direction.
-Fixed a nasty memory leak where none of the memory allocated for the path data was freed.
-It was caused by the Blitzmax's carbage collector's inability to handle circular references.
-Now works with huge amounts of filler dots ( tested with over 5 Million dots ).
-Also tested to work with up to 100 Megapixel source images.
-Changed the default settings to give a better first impression.

KNOWN ISSUES:
-Filenames/paths containing spaces will not be read correctly from a settings file.
This is because of the settings file format uses a space between field name and data.
Changing the limiting character would break compability with older versions.
-Source image size requirement increases with the amount of dots/samples because there is no interpolation between pixels.
Images should be resized with an image editor before use. ( 1-2 Mpx is enough for most cases )
-Sine paths that go outside the work area and come back will miss the points that are outside.
This can lead to problems with dxf and GCode
-Garbage collection can sometimes take quite a long time.

---

7.8.2011 V 2.0

Another major (and possibly last) release! ( Unless someone is willing to pay me to add features x, y and z :) )
Source code size has more than doubled since version 1.5

IMPROVEMENTS / FIXES:
-Reorganised some UI elements
-Some minor fixes

NEW FEATURES:
-Line width modulation
-Completely different way of making halftones
-GCode Export
- V-Bit GCode generation for both types of fillers
-Dxf export for line halftone

-Documentation has been updated

KNOWN ISSUES:
-Filenames/paths containing spaces will not be read correctly from a settings file.
This is because of the settings file format uses a space between field name and data.
-Crazy values will make the program crash.
-The program will not work correctly with massive amounts of dots / path samples ( n > 300 000 )
Probably due to a integer overflow somewhere in the Blitzmax's Tlist class or my own code.
-Sine paths that go outside the work area and come back will miss the points that are outside.
This can lead to problems with dxf and GCode

---

27.7.2011 V 1.5

MAJOR RELEASE!

IMPROVEMENTS / FIXES:
-Complete user interface overhaul.
-Preview is now in its own window
-Added tabs to the main window
-Now using the system file selector for all files
-Rearranged elements to logical groups
-Preview window now shows the dot count and generation time
-Minor tuning to the dot sizing algorithm
-Fixed the rotated square drawing position
-Lots of minor stuff such as some code restructuring and comments

NEW FEATURES:
-Resizable preview window
-Saving and loading program settings from a file
-Autosave settings on export-option
-Added X and Y offsets to dot grid options
-Preview zoom outwards changed to use mipmapping
-Added support for exporting square dots as polylines
-Added support for exporting work area border rectangle
-Export range-option to export only dots of certain size

-Updated and restructured the documentation

KNOWN ISSUES:
-Filenames/paths containing spaces will not be read correctly from settings file.
This is because of the settings file format uses space between field name and data.

---

8.11.2010 V 1.0
First Release.

---

------------------
::::USER GUIDE::::
------------------

After changing any values you must press the "UPDATE PREVIEW"-button on the preview-window to make them take effect and see the results!
The export will be like the preview, if you change any values ( other than maybe GCode settings ) you also have update the preview before export.

Resetting all values to defaults is easy: Just close the program, delete the HTSettings.txt and start the program again.

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

"GENERAL"-TAB

All the settings on this tab will affect both Dot halftone and Path width modulation effects.

Start by specifying the source image file name/path. The button with marked "..." can be used to launch a file selector.

Settings

Program settings can be saved to a separate text-file. To save current settings, select a filename with the "..."-button or type it manually
and press the "Save"-button. To load settings you need to select a previously saved file and press the "Load"-button
These files contain nearly all of the UI-settings, including the source image filename and path.
The settings files are fully compatible ( forwards and backwards ) with older versions of the program but contain much more parameters.

If settings cannot be loaded from HTSettings.txt ( file doesn't exist ), hardcoded defaults will be used.

If the "Save on export"-checkbox is selected, settings will be saved at the same time with dxf export so you can easily modify previous work.
HTSettings.txt is still used to save the settings on exit and will be overwritten if exists.

Color Switch

Color Switch switches the foreground (filler) and background colors. This also changes the filler dot sizes!

Workpiece dimensions

Width and height determine the actual size of the full pattern in millimeters.
(or inches or meters etc. as dxf or GCode does not care what units you are using as long as you are consistent with them)
If one of these two is omitted (or set to zero) then it is calculated from the other by using the aspect ratio of the input image.

Edge border determines the minimum distance from edge to the center point of filler dot or path sample point.
This also accepts negative values which is useful if you don't get the whole area filled otherwise.
Too small ( < -.5*spacing or so ) values will crash the program. Negative Border values will not work well ( and are not necessary ) with
the path halftone.
Especially if using the divisor with sine paths, negative border values will produce errors.

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

"DOT HALFTONE"-TAB

Dot grid

The Spacing value determines the distance between filler dot's center points.

Rotation is the angle of the filler grid in degrees.

Min diameter is the minimum diameter of the filler circles. The program also accepts negative values,
this can be useful sometimes to adjust the size scale or if the image doesn't have a full range of colors.
Use negative values with caution!

Max diameter is the maximum diameter of filler circles. Fit max D button sets the maximum diameter to Spacing - Minimum diameter.
If you use larger maximum diameter than spacing the filler circles might overlap.

X-offset and Y-offset can be used to fine-tune the position of the dot grid. This is useful when making low resolution halftones and making
the edges symmetrical.
Too Large values will cause the grid to move outside the work area.

Filler type

The program has 3 filler types: Circle , Square and Rotated Square. Since version 1.5 all of these can be exported.
Circles generally give the best results, but in some cases squares can look nicer with their sharp edges and higher contrast.


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

"PATH WIDTH MODULATION"-TAB

Path parameters

Spacing is the distance between path lines. With sine wave the line is that along which the curve is symmetrical. ( center, average, whatever )
The pattern generation always starts by making lines and finding their endpoints. After that sampling points are placed evenly on them and their
sizes calculated.

Rotation is the angle of the path lines in degrees. Values where A mod 45 = 0 and the source picture is a perfect square can lead to some
problems.

Min and max width specify the limits to the modulation of the path width. I usually use at least 0.5 mm in the minimum width and
max width = spacing - min width

Wavelength and Amplitude only affect the sine wave and can be used to set those properties.
The formula is: (amplitude/2) * sin(x * wavelength + offset)
Higher amplitude values can make the paths overlap and require more sample points to look good.

X-offset and Y-offset can be used to fine-tune the position of the paths. These values are not inputs to the sine function, but move the
starting point.

Path type

These radiobuttons control the path type. Lines give accurate results when the spacing is low, but I usually find low-amplitude sine curves
more aesthetically pleasing.

Path sampling parameters

Spacing is the distance along the line at which intervals sample points are taken.


With sine waves there are two kinds of sample points, ones that take their width value from the source image and those that don't.
With high sample counts there aren't that many pixels to base the calculations on per sample. Pixels cannot be sharedor the result won't
be true to the original. The points that don't take their width values from the image use linear linear interpolation to smooth the result
and keep the waves flowing nicely. With straight lines these in-between points are useless and are not generated.

Divisor field specifies the integer value ( 1 -> n ) how many non-imagesample points will be made per one sample point that calculates the width
from image.
Example: With spacing value of 1 mm and divisor of 2 you get points every millimeter, but samples are taken from the image only each 2 mm.

This is important because you will see kind of "noise" in the path width when the image samples are very close to eachother.
This means that the samples are based on just a few pixels.

To get high resolution and smooth curves, use small spacing value and play with the divisor values to get the best result.
Looking and zooming at the generated dxf helps a lot.

Another option is to use a very high resolution source image, but then the pattern generation times could grow exponentially.


Offset increment value is added to each sine wave's offset value. The wave offsets are set so that they are coherent, flowing nicely with
constant space between them. However, with this value you can change that and for example make all the peaks meet eachother with the setting
of wavelenght / 2.

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

"DXF EXPORT"-TAB

DXF export

DXF export uses same logic with file name/path as the source image and settings.
".dxf" will be automatically added to the filename after you close the file selector.

Border rectangle can be exported with the filler pattern as polyline. The size of this rectangle is the same as the work piece dimensions
specified in the "General"-tab.

Press the "EXPORT DXF"-button to export to the file specified in the textbox above.
If the file you have selected is locked or doesn't have write permissions, you won't get a message in the main window's status area.

Dot size range

You can specify the minimum and maximum size of dots to be exported. With this feature you can leave out portions of the filler or create
multiple files with only certain size of dots in them easily.
"Active"- checkbox is used to turn this feature off without the need to change the values.

Please note that these settings will also affect the GCode export when working in "dot halftone" mode.

The effect of these values is not shown in the preview-window.

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

"GCODE EXPORT"-TAB

Please note that the GCode export only supports using V-shaped router bits for engraving.
Only the dots or lines will have GCode made for them, you will need to make the cutout toolpath yourself or in some CAM-program.

The generated GCode is "unit neutral". It doesn't set the units to metric or imperial. This so you can use either one for values in the
program.

Workpiece material surface is assumed to be at the Z-axis zero coordinate.

You should always verify the generated GCode with some kind of toolpath visualiser or simulator before use.
Exporting as dxf and inspecting it is also wise.

Tool and feed

V-bit angle specifies the included angle that your cutting tool has. Values should be 0 < angle < 180 in degrees.
90 degree bits are a good compromise, but you can have more accuracy with 60 degree bits or engrave on thin boards with a 120 degree one.

Feedrate is the speed that the machine will use to carve paths. This will be used to run along the path from start to finish, so you have be
sure your tool and machine can make quick plunges at this speed as the line width changes. The value is inserted directly into the GCode, so
units will depend on your control software settings.

Plunge rate is the speed at which the tool can move vertically into the material. Plunge rate is used to move the cutter from safe-z to desired
depth.

Zero position

This group has 5 radiobuttons that can be used to set the XY-origin relative to the work area. Options are the four corners or center point.
If you want to use a custom zero position, you can edit the settings file which has zeropx and zeropy parameters. After editing, you have to
load it again.
Clicking on any of the radiobuttons will reset the variables and custom settings will be lost.

Home Position

Home position is the set of coordinates that the machine will be run to in the beginning and in the end of the program. These are relative to
the zero point. Home Z cannot be lower than the Safe-Z

Misc

Spindle rpm (revolutions per minute) is quite self explanatory. It is set in the beginning of the program.

Safe Z is the Z-axis value at which is safe to do rapid moves. This means clearing any obstacles ( such as clamps ) on the work surface area
and on the way to the home position.
When doing "dot halftone"-engraving the safe Z should be set as low as possible to minimise the time it takes to move from one point to another.
Plunge speed is used when moving from safe-Z downwards ( drilling, not when cutting paths )

GCode export

Use the "..." button to or textbos to select filename or press the "EXPORT GCODE" button to generate and export the GCode.
".tap" will be automatically added to the filename after you close the file selector.

If the file you have selected is locked or doesn't have write permissions, you won't get a message in the main window's status area.

Please note that the all the setting on the "General"-tab and dot size range settings on the "DXF export"-tab also affect the GCode output.


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

(C) Tomi Syväjärvi 2011
[e-mail]