NAME

       png23d - PNG to 3D file conversion

SYNOPSIS

       png23d  [-V] [-v] [-f finish] [-o type] [-t transparency] [-l quantisation] [-w width] [-h
       height] [-d depth] [-O optimisation] [-b complexity] [-m filename] input output

DESCRIPTION

       png23d is a tool which converts a PNG image into a three  dimensional  file  suitable  for
       modelling applications especially for 3D printers.

OPTIONS

       -V     Display the program version and exit.

       -v     Make the program produce verbose output.

       -t     The  colour  which is used for transparent output. Valid range is 0 to 255(default)
              or 'x' to disable.

       -l     The number of levels into  which  the  colour-space  is  divided.  Valid  range  is
              1(default)  to 256. Note that as of version 1.0 not all output generators obey this
              parameter or may use a different finish type to that specified if the parameter  is
              not 1.

       -w     The output target width (x dimension). The source PNG width is used by default.

       -h     The  output  target height (y dimension). Note most outputs will simply ignore this
              parameter and retain the original image aspect ratio based on the width parameter.

       -d     The output target depth (z dimension) The number of levels specified is used as the
              default.

       -o     Specifies the output type

              pgm     Output  a  PGM  format  bitmap.  This  can  be used to verify the level and
                      quantisation parameters are set correctly.
              rscad   Output a scad format file  for  use  with  OpenSCAD.   This  file  will  be
                      comprised  of  a union of cubes. The finish cannot be controlled (it is raw
                      blocks) and the resulting scad object may be very complex.
              scad    Output a scad format file  for  use  with  OpenSCAD.   This  file  will  be
                      comprised of a single polyhedron mesh.  For larger images this polygon will
                      be exceptionally complex and may contain many thousands of triangles.
              stl     Output a binary stereolithography format file.  These files  are  comprised
                      of simple triangles, the output can be directly used by several 3D printing
                      systems.   The  generated  meshes  are  a  convex  manifold  but  are   not
                      simplified.
              astl    Same as the stl entry but generates a textural file instead of binary.

       -f     Specifies the finish out the output 3D mesh the default is cube which keeps all the
              cube faces. The smooth option uses a marching  square  algotithm  to  gives  sloped
              edges  and  reduces jaggies. The rect finish is for the rscad output type only. The
              surface type generates a simple heightmap surface.

       -O     Specify the mesh optimisation level of 0, 1(the default) or 2.

              0   No mesh optimisation will be performed. This will be fast to  execute  but  the
                  resulting  mesh will be exceptionally complex and will almost certainly require
                  additional processing in another tool such as meshlab.

              1   Mesh simplification using  edge  removal  algorithm  will  be  performed.  This
                  process  is  relatively fast and the result maintains the exact blocky geometry
                  from the generation process. Typically this produces reasonable results for non
                  complex extrusions.
              2   Mesh  simplification  using  quadratic  surface  removal. This has not yet been
                  implemented!  Use  a  tool  such  as  meshlab  if  you  require  this  type  of
                  simplification.

       -b     The  bloom  filter  complexity  which controls the size of the filter and number of
              iterations(functions) used by vertex indexing as part of  the  mesh  simplification
              process.  Valid range is 0 to 16 with a default of 2. Most users will never need to
              alter this parameter. It is useful only if they are experiencing a high filter miss
              rate on exceptionally large meshes with 10 million facets or more).

       -m     The  filename  to  save  the mesh optimisation debug output to. This is a generated
              html file which graphically shows each stage of the mesh  simplification.  This  is
              useful  only  for  debugging purposes and for images above a few hundred facets the
              output can run to many hundreds of megabytes.

       input  Specifies the source PNG file to convert from.

       output Specifies the output file.

EXAMPLES

       To convert from foo.png to foo.scad in scad polyhedron output format:

              png23d -o pscad foo.png foo.scad

       To convert from foo.png to foo.stl in binary STL output format with smooth finish:

              png23d -f smooth -o stl foo.png foo.scad

       To convert from foo.png to foo.stl in ascii STL output format with smooth  finish  and  50
       unit output width:

              png23d -f smooth -o astl -w 50 foo.png foo.scad

AUTHOR

       Copyright © 2011 Vincent Sanders

       Permission  is  hereby  granted,  free  of  charge, to any person obtaining a copy of this
       software and associated documentation files (the "Software"),  to  deal  in  the  Software
       without  restriction, including without limitation the rights to use, copy, modify, merge,
       publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
       to whom the Software is furnished to do so, subject to the following conditions:

       The  above  copyright notice and this permission notice shall be included in all copies or
       substantial portions of the Software.

       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT  WARRANTY  OF  ANY  KIND,  EXPRESS  OR  IMPLIED,
       INCLUDING  BUT  NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
       PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE  LIABLE
       FOR  ANY  CLAIM,  DAMAGES  OR  OTHER  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
       OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR  THE  USE  OR  OTHER
       DEALINGS IN THE SOFTWARE.

                                        18th October 2011                               png23d(1)