home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 518.lha / Convert_v2.2 / convert.doc.pp / convert.doc
Encoding:
Text File  |  1991-06-09  |  10.5 KB  |  259 lines
  1. ===========================================================
  2.    Convert.doc - for v2r2 - last updated May 13th, 1991
  3. ===========================================================
  4.  
  5. Credits:
  6. --------
  7. Software created by Pete Patterson for Black Belt Systems
  8. Additional coding by Ben Williams
  9. Documentation written by Ben Williams
  10. Funding by Black Belt Systems
  11. Project: HAM-E hardware support
  12.  
  13. Program revisions from version 1.0 to date:
  14. ===========================================
  15. v2r2 - Fixed bug in 24 bit save routine with widths > 800
  16.      - Fixed bug in scaling which affected brightness
  17.  
  18. v2r1 - Fixed bug in RAW RGB load (and maybe elsewhere)... if you accepted
  19.        either of the default width or height, the program would quit
  20.      - 32 bit Targa file support
  21.      - 16 bit Targa file support
  22.  
  23. v2r0 - Fixed bug in Targa conversions
  24.      - Added mouse interface
  25.  
  26. v1r6 - Fixed bug causing crashes if memory allocation failed
  27.      - Intergerized scaling for approximately 7x speed improvement
  28.  
  29. v1r5 - Fixed bug in loading 24 bit files that appeared in v1r4
  30.      - Added load of IBM (yech!) Dpaint "LBM" files
  31.      - Added load of IBM DPaint non-LBM files (recent DPaint versions)
  32.      - Added "shuffle" features to convert from and to X-Spex
  33.        compatible 3-d interleaved images
  34.  
  35. v1r4 - Added support for 18 bit IFF "ScanLab" files
  36.      - Added Support for Black Belt paint UPB8 (UnPackedBrush-8) brushes
  37.  
  38. v1r3 - Added HAM-E ham and reg mode single and multi field loaders
  39.  
  40. v1r2 - Added ability to read one type of targa file ("Opticks" generated)
  41.  
  42. v1r1 - Fixed bug in loading RGB8 and RGN files in v1r0
  43.      - Added scaling options (-px, -py, -%x, -%y)
  44.  
  45. v1r0 - Initial release version.
  46.  
  47. Introduction:
  48. -------------
  49. The convert tool was created to fill a specific need of the Black Belt
  50. Systems HAM-E product customer base. The HAM-E is a graphics device
  51. which can display color information far more accurately than the Amigas
  52. built in graphics capabilities allow. As such, the HAM-E display
  53. formatting software takes as input CBM standard 24 bit IFF files, the
  54. format defined by CBM specifically for this type of use.
  55.  
  56. Unfortunately, many otherwise powerful Amiga products such as Impulses
  57. Turbo Silver, Byte by Bytes Sculpt series and some of the PD ray trace
  58. products don't save standard files; instead, they save raw files,
  59. or partially (sometimes totally!) non-conformant "other" formats, some
  60. of which they consider proprietary.
  61.  
  62. Certain other software products often save image formats that are
  63. designed to take advantage of various features in the Amiga's graphics
  64. system that allow enhancement of certain image modes. HAM-E, SHAM and
  65. Dynamic HiRes are examples of this type of image file. ASDGs "The Art
  66. Department" saves 24 bit files with special chunks in them called
  67. "CLUT" chunks that modify the 24 bit data in various ways. All of these
  68. differing image file formats bring chaos to our supposedly orderly
  69. "standard image format" environment.
  70.  
  71. The convert tool is able to read many of these file formats, optionally
  72. scale the input file to a new size for output, and write it out as a
  73. completely standard, "100% vanilla" 24 bit IFF file as per the CBM
  74. specification. Once this is done, the resulting file can be sent to the
  75. HAM-E render software, or any other Amiga tool that can read 24 bit IFF.
  76.  
  77. The convert tool has been made available free of charge to our
  78. customers as a service to them. Use by other parties is allowable as
  79. well.
  80.  
  81. Use of Convert:
  82. ---------------
  83. There are basically two types of image files that convert supports.
  84. First, we have "unified" image files. These are files where all of the
  85. iamge information is contained in one file, with enough other
  86. information to allow the convert tool to identify the file type and
  87. then act accordingly. The other is "raw" individual RGB files, where
  88. three individual files make up the complete image; and there is no
  89. information in these files to help the tool know what the file type is,
  90. or what its resolution is, and so on.
  91.  
  92. If you use convert from the CLI or shell, then you will use the command
  93. switches, documented below.
  94.  
  95. If you use convert from the workbench, or if you type "convert" without
  96. any command line switches, then you are presented with a user interface
  97. that consists of control panels and buttons. This mode is better suited
  98. for interactive operations. The command line mode is better suited for
  99. script-based operations.
  100.  
  101. Unified Image File Use:
  102. -----------------------
  103. This consists of simply specifying an input and an output file:
  104.  
  105.     1> convert -i input_file -o output_file
  106.  
  107. This will take the input file and create a 24 bit IFF output file of
  108. the same resolution. The filenames may be presented in any order, as
  109. long as they are preceeded by the "-i" and "-o" switches. Note that for
  110. Targa format files, you must specify the -t flag anywhere on the command
  111. line. The width and height of the image is stored within the Targa file,
  112. but there is nothing in a Targa format file which identifies it as such.
  113.  
  114. Raw Image File Use:
  115. -------------------
  116. For any raw RGB file triplet, the "-i" option is not used. Instead,
  117. there are five (5) required command line switches that tell the convert
  118. software how to deal with this image. You must provide the names of
  119. each of the three raw files, as well as the horizontal and vertical
  120. resolution of the image contained in these files. Here is an example:
  121.  
  122.     1> convert -r file1 -g file2 -b file3 -x 320 -y 400 -o output_file
  123.  
  124. The parameters may be presented in any order, as long as all five of
  125. the -o, -r, -g, -b, -x, and -y switches are present.
  126.  
  127. Optional Output Scaling:
  128. ------------------------
  129. For either unified file types or raw RGB files, you have the option to
  130. scale the output file. You can do this as a percentage of input size,
  131. or to specific X:Y output requirements, or a mixture of both
  132. techniques. For the examples we'll use the unified form of the command
  133. since it's shorter and a little easier to understand; but these scaling
  134. options may also be applied in exactly the same way to raw RGB file
  135. conversion operations. Here are some examples:
  136.  
  137.     1> convert -i infile -o outfile -%x 50
  138.  
  139. This will scale the X axis to 50% of the original size. Since there is
  140. no scale specification for the Y axis, it will remain the original
  141. size.
  142.  
  143. If you need to scale both axis to 50%, then you specify that for both:
  144.  
  145.     1> convert -i infile -o outfile -%x 50 -%y 50
  146.  
  147. You can specify the output size directly in pixels, as well. The
  148. following example will create a 320x400 output, regardless of the size
  149. of the input file:
  150.  
  151.     1> convert -i infile -o outfile -px 320 -py 400
  152.  
  153. And this will scale the x axis to 50% of it's original size while
  154. ensuring a 200 line vertical size:
  155.  
  156.     1> convert -i infile -o outfile -%x 50 -py 200
  157.  
  158. You can mix and match percent and specific X and Y options as needed;
  159. don't use a percentage and a specific pixel specification for the same
  160. axis.
  161.  
  162. The scaling options also allow enlargement. For percentages, just
  163. specify values greater than 100; for pixel sizes, if the output size is
  164. larger than the input file size, then the output file will be enlarged
  165. in that dimension or dimensions. Here's an example:
  166.  
  167.     1> convert -i infile -o outfile -%x 200 -%y 200
  168.  
  169. Unified Image File Formats Supported:
  170. -------------------------------------
  171.  1 - 2 color IFF images
  172.  2 - 4 color IFF images
  173.  3 - 8 color IFF images
  174.  4 - 16 color IFF images
  175.  5 - 32 color IFF images
  176.  6 - 64 color "half-bright" IFF images
  177.  7 - 64 color HAM-E register mode single field images
  178.  8 - 64 color HAM-E register mode dual field images
  179.  9 - 128 color HAM-E register mode single field images
  180. 10 - 128 color HAM-E register mode dual field images
  181. 11 - 128 color IFF images
  182. 12 - 192 color HAM-E register mode single field images
  183. 13 - 192 color HAM-E register mode dual field images
  184. 14 - 256 color IFF images
  185. 15 - 256 color GIF images
  186. 16 - 256 color HAM-E register mode single field images
  187. 17 - 256 color HAM-E register mode dual field images
  188. 18 - 256 color HAM-E UPB8 brushes
  189. 19 - 4096 color photon paint IFF images
  190. 20 - 4096 color photon paint IFF brushes
  191. 21 - 4096 color DigiPaint IFF images
  192. 22 - 4096 color DigiPaint IFF brushes
  193. 23 - 4096 color Dynamic HiRes images
  194. 24 - 4096 color ARZ0 images ("TAD")
  195. 25 - 4096 color ARZ1 images ("TAD")
  196. 26 - 4096 color AHAM images ("TAD")
  197. 27 - 4096 color SHAM images ("info")
  198. 28 - 4096 color RGBN images ("Silver")
  199. 29 - 262144 color HAM-E ham mode single field images
  200. 30 - 262144 color HAM-E ham mode single field, multi-bank images
  201. 31 - 262144 color HAM-E ham mode dual field images
  202. 32 - 262144 color HAM-E ham mode dual field, multi-bank images
  203. 33 - 262144 color "ScanLab" 18 bit IFF files
  204. 34 - 16 million color RGB8 ("Silver")
  205. 35 - 16 million color 24-bit IFF images with CLUT chunks ("TAD")
  206. 36 - 16 million color 24-bit IFF images
  207. 37 - 16 million color QRT Trace files
  208. 38 - 16 million color DKB Trace files
  209. 39 - 16 million color TARGA files (Opticks)
  210.  
  211. Available Command Line Switches:
  212. ================================
  213.  
  214. For Help
  215. --------
  216. ?                 ...for list of options
  217. h                 ...for list of options
  218. -h                ...for list of options
  219. help              ...for list of options
  220.  
  221. For Specifying a Unified Input File:
  222. ------------------------------------
  223. -i [dev:dir/file]     ...unified input file (may include path)
  224.  
  225. For Specifying Targa Input:
  226. ---------------------------
  227. -t                    ...use -i for Targa file name
  228.  
  229. For Specifying raw RGB Input Files (All these switches are required):
  230. ---------------------------------------------------------------------
  231. -r [dev:dir/file]     ...raw red file (may include path)
  232. -g [dev:dir/file]     ...raw green file (may include path)
  233. -b [dev:dir/file]     ...raw blue file (may include path)
  234. -x [width]            ...raw source width
  235. -y [height]           ...raw source height
  236.  
  237. For Specifying the Output File (Required):
  238. ------------------------------------------
  239. -o [dev:dir/file]     ...24 bit output file (may include path)
  240.  
  241. For Scaling the output file to a percentage of the input file:
  242. --------------------------------------------------------------
  243. -%x [% value]         ...destination image width
  244. -%y [% value]         ...destination image height
  245.  
  246. For Scaling the output file to a specific Pixel Width:
  247. ------------------------------------------------------
  248. -px [pixel value]     ...destination image width
  249. -py [pixel value]     ...destination image height
  250.  
  251. To change an "over-under" X_Spex image to "Interleaved":
  252. --------------------------------------------------------
  253. -3d                   ...takes over-under, makes interleaved
  254.  
  255. To change an "Interleaved" X_Spex image to "over-under":
  256. --------------------------------------------------------
  257. -2d                   ...takes interleaved, makes over-under
  258.  
  259.