Create file format

Defines a new image file format. An unlimited number of new formats can be added. Once defined, the new format is automatically recognized by tnimage and can be loaded and saved without any special action.

Custom formats are particularly useful if reading medical images from an X-ray scanner, which vary from one manufacturer to the other. Images can be compressed by a number of available methods.

Of course, with this much flexibility it is impossible to test every possible combination of parameters on every destination platform, so it is advisable to make a test image before proceeding, to make sure the file is readable on the target system.

Note: It is necessary have write permission in the directory where the file formats is stored in order for this to work. The location of this file can be changed by changing the format_list line in tnimage.ini (default location is $HOME/.tnimage/formats ).

Defining a custom format is a very flexible and convenient way of storing images, since someone else wishing to view the image only needs the corresponding image descriptor file.

When reading a custom image file, tnimage first looks for the file descriptor in the directory

$HOME/.tnimage/formats .

This file descriptor is an ordinary text file, which can be created manually or by using the ``Create file format'' menu option. The filename of the file descriptor must be the same as the ``Identifier'' described below.

Here is the procedure for creating a new custom format:

1. Click on ``File...Create file format''.
2. Select target platform - This option will determine the order in which bytes should be swapped. If the destination computer is not a PC, Mac, or IBM mainframe, pick whichever seems closest. Many UNIX systems use ``big-endian''-type processors similar to the Mac. MVS systems use ``little-endian'' processors similar to the PC.
3. Bit packing - If bits/pixel is not a multiple of 8, the individual image bits can be packed into bytes or allowed to expand to the next largest multiple of 8. This allows for faster reading but results in larger file sizes. Packing bits is performed differently in GIF and TIFF files as shown:

   If mode=GIF

   Assumes bits are packed in the following format (example for n=9 bits pixel, where a,b,c... are pixels) :

                        7  6  5  4    3  2  1  0    
                      ----------------------------  
       Byte 1          a7 a6 a5 a4   a3 a2 a1 a0    
       Byte 2          b6 b5 b4 b3   b2 b1 b0 a8    
       Byte 3          c5 c4 c3 c2   c1 c0 b8 b7    
       Byte 4          d4 c3 d2 d1   d0 c8 c7 c6    
       ...
   

   If mode=TIF Assumes bits are packed in the following format (example for n=9) :

                        7  6  5  4    3  2  1  0   
                      ---------------------------- 
       Byte 1          a8 a7 a6 a5   a4 a3 a2 a1   
       Byte 2          a0 b8 b7 b6   b5 b4 b3 b2   
       Byte 3          b1 b0 c8 c7   c6 c5 c4 c3   
       Byte 4          c2 c1 c0 d8   d7 d6 d5 d4
   

   In most cases, the bit packing should be left at ``none''.

4. Format identification - This determines how tnimage should recognize an image in the new format. If ``by identifier'', tnimage will look for the specified identifier string at the specified offset in the file. For instance, if the file always starts with the characters ``II'', the identifier is II and the identifier offset is 0. If the image is to be identified ``by extension'', any file having an extension the same as the specified identifier will be identified as a file of that type. This would be appropriate if the file always ended with the extension ``.lum'' for example.

   Note: Compressed formats can only be identified by extension.

5. Identifier - any string up to 64 characters that should be used by tnimage to identify the file. The final `null' (0x00) character is not expected to be in the file.
6. File offsets - This opens a list of parameters that may be extracted from the image file header. Each parameter must be present at the specified offset in all image files of this type. The maximum size in bytes for the parameter is shown in parentheses. For example, an entry shown in the listbox such as

   Y size (2) 8

   means the image contains two bytes starting at a position 8 bytes from the start of the file that indicate the image height (Y size) in pixels. If an offset is set to 65535, it will be ignored.

   It is very important that none of the offsets overlap with each other, and that no offsets are included in the file descriptor that do not actually exist in the image file. For example, if an offset for a palette (color LUT) is specified at offset 76, no other parameters can have offsets between 76 and 844, because the palette uses 768 bytes. tnimage does not check for this.

   The parameters in the table below can be recognized from the image file. Note that, when creating the format descriptor, it is necessary to enter the position in the file where the parameter resides, not the actual value. At run time, tnimage will fill in the value automatically. The ``number of bytes'' in the table below refers to the maximum size in bytes that the parameter can attain. Thus, for X size, with only 2 bytes, the maximum width of an image is only 65535. This was done to provide the ability to read certain other (older) image formats as custom format images.

   Parameter	Bytes	Meaning
   Identifier	64	Format identifier or file extension
   X size	2	Width of image in pixels
   Y size	2	Height of image in pixels
   Bits/pixel	2	Bits per pixel in image
   Color type	2	0=Grayscale, 1=Indexed color, 2=true color
   Compression	2	0=no compression, 1=compressed
   Red bpp	2	Bits/pixel for red
   Green bpp	2	Bits/pixel for green
   Blue bpp	2	Bits/pixel for blue
   Black bpp	2	Bits/pixel for black
   X position	2	Position of left edge of image in pixels
   Y position	4	Position of top of image in pixels
   Frames	4	No. of frames in image
   Frames/sec	2	Speed of ``movie'' for multi-frame images
   Chromakey	2	-1=inverse, 0=none, 1=normal chromakey
   Chr.gray min	4	Min. pixel value for chromakey if image is grayscale
   Chr.gray max	4	Max. pixel value for chromakey if image is grayscale
   Chr. RGB min	4	Min. RGB value for chromakey if image is color
   Chr. RGB max	4	Max. RGB value for chromakey if image is color
   Palette	768	Colormap for image, if image is Indexed color
   Image offset	2	Starting offset for image data.

   When creating a new image format, it is advantageous to separate the parameters by at least 4 bytes for future compatibility. Also, there is no harm in specifying an offset for a parameter (such as frames/sec) even if it will never be used.

   The image data are stored in pixel order, starting at the upper left of the image, as RGBRGB... for color images or IIIIIIII.. for indexed or grayscale images. Successive frames are stored without any intervening spaces, except that, if bit packing is used, unused bits at the end of a line or frame are set to 0 and each line and frame starts on a new byte.

   Unless the images are always the same size, the image offset should be the highest offset. If the format descriptor file is edited manually, the entries do not need to be in any particular order.

   NOTE: If a nonzero value is specified for ``Bytes to skip'', this value will override any value in the file at position image offset for the start of image data.

7. External header file - If the format of the image file is unknown, a custom format can still be created provided that a sample of the image is available. Enter the filename of this sample image in ``Header file'', and the number of bytes in its header in the next box. Tnimage will then copy the specified number of bytes from the sample image into the start of any new images created in that format. The sample image must always be present. The number of bytes that should be copied to create a valid image file is usually a power of 2 (32, 128, etc). This procedure is obviously risky, since the header being copied may only be valid for an image of a certain size or image depth.

8. Default parameters - these are numbers that will be used as defaults if no offsets are specified for a given parameter (i.e., the offset is 65535). Most of these are self-explanatory.
   1. Bits/pixel that the destination system expects. This can be calculated from the number of colors on the screen, using the formula

      No. of colors = $2 ^ {(Bits/pixel)}$.

      Thus, if there are only 2 colors (black and white), there is 1 bit per pixel.

   2. x size in pixels
   3. y size in pixels
   4. RGB bits per pixel
   5. Black bits per pixel (if image is CMYK)
   6. No. of frames (must be at least 1)

9. Compression - If ``compression'' is set to ``On'', the following three items will be used to execute an external compression program to compress and decompress the image file. This has the advantage that, if new or proprietary compression schemes become available, they can easily be incorporated into custom images. For example, one could use a fractal image compression program if it became available.
   1. Command - The compression command line. tnimage will append the image filename to the end of whatever is entered here. For example, gzip -f will cause the image file to be compressed with gzip. The `f' option is essential to prevent gzip from prompting for a `yes or no' if the zipped file already exists. tnimage already checks for this.
   2. Extension - The string added by the compression program, if any. If a string is entered, the file must end in that string in order to be correctly identified. (Example: .gz ).
   3. Decompress - The decompression command line. The program performing the decompression must send its output to `stdout' and not to a file. This is accomplished in gunzip with the `-c ' option. With this feature, it is not necessary to create a temporary unzipped file before reading the image and the original .gz file remains intact.

Warning: Incorrect settings in the format file can crash tnimage.