kermit.columbia.edu/kermit.columbia.edu.tar/kermit.columbia.edu/sixel/pcx2six.doc

Text File | 1996-12-10 | 16KB | 469 lines

PCX2SIX
SIXEL Graphics Utility
Guide 1.00

PCX2SIX
conversion program
SIXEL Graphics Utility
Guide

  Author(s)   Date      Rev   Page  Comments
  J.G.Zvonar  12/4/95   1.00  all   Original Version

  John G. Zvonar
  10309 Trout Cove
  Austin, Tx 78749

  EMAIL [e-mail]


Table of Contents

1. Introduction. . . . . . . . . . . . . . . . . . . . . . . .  1

2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . .  2

4. Conventions . . . . . . . . . . . . . . . . . . . . . . . .  4

5. Overview. . . . . . . . . . . . . . . . . . . . . . . . . .  5

6. Using PCX2SIX . . . . . . . . . . . . . . . . . . . . . . .  7

7. Palette file format . . . . . . . . . . . . . . . . . . .   11

8. Limitations . . . . . . . . . . . . . . . . . . . . . . .   12

9. Troubleshooting . . . . . . . . . . . . . . . . . . . . .   13


1. Introduction

    The ability to display pictures on the VAX systems both inside
    of specifications and as stand alone reference documents can
    aid in the daily job performance.  This utility provides the
    ability to put any PC picture into native VAX/VMS SIXEL format.

  1.1 Major Components

    1.1.1 VAX/VMS

    1.1.2 PCX2SIX.EXE

    1.1.3 Graphics capable terminal or emulator

  1.2 Copyrights & Trademarks

    1.2.1 SIXEL - Digital Equipment Corporation

    1.2.2 Windows - Microsoft Corporation

    1.2.3 PAINT, PBRUSH, PCX - ZSoft Corporation

    1.2.4 Kermit - Columbia University2. Scope

    This document will cover the use of the PCX2SIX utility to
    create pictures in SIXEL format for specifications and stand
    alone pictures.  The features provided will be described as
    will the few limitations of the conversion utility.

  2.1 Intended Audience

    This user guide is written assuming that the reader has at
    least a basic familiarity with DOS, and has a need to display
    SIXEL graphics perhaps on a VAX/VMS system.

  2.2 What is not covered

    This document does not cover information related to PCX or
    SIXEL or the internal program code.

    This document will not cover the details of creating the
    graphic that is to be displayed, other than how to get it into
    the correct file format.

    Limited coverage of how to get the file from PC platforms to
    the VAX/VMS system will be done.

    No coverage of Windows or DOS is attempted.

  2.3 General Information

    2.3.1 The author has no association with ZSoft Corporation.

    2.3.2 The conversion utility is supplied as is. FREE of charge.

    2.3.3 The utility is for unlimited, unrestricted use except as
          follows.  The utility may not be bundled with other "FOR
          SALE" software without prior written permission from John
          G. Zvonar, otherwise the utility may be given away for
          FREE with all documentation.

    2.3.4 There is no warranty, period!

    2.3.5 The SIXEL output has been tested on TRUE VT340 terminals
          and various terminal emulators.


3. References

  3.1 Additional Documents Required

      No additional documents are needed for using the PCX2SIX
      utility to create pictures for use in a SIXEL graphics
      environment.


4. Conventions

  4.1 Items of special interest are in bold characters.

  4.2 User typed input is in underlined italics.

  4.3 Single stroke key presses are identified as press <key>.  The
      keys <enter> and <ret> or <return> are used interchangeably.


5. Overview

  Graphics provided as reference documents or as part of the
  operating specification provide significant benefit over just
  having words for descriptions, or using character based pictures.
  This utility allows the viewing of PC based pictures on the
  VAX/VMS system using the capability of terminals supporting SIXEL
  graphics protocol.


  5.1 SIXEL Graphics

    The DEC Terminals which support SIXEL graphics information can
    display pictures with VGA to Super VGA (PC based measure)
    quality levels.  The SIXEL protocol is a bitmap based graphics
    capability supplied by DEC integral to several terminals in VT
    terminal product line.  Many VT terminal emulators also provide
    full, or partial, SIXEL graphics support, most in at least 16
    colors.

  5.2 PCX Format

    5.2.1 The ZSoft PCX format was chosen was chosen to be the
          'common format' for the utility.  This was chosen due to
          the wide variety of applications on many different
          platforms that support and generate PCX files.  PCX files
          are bitmap files.

    5.2.2 Any application that can create PCX files can generate a
          file suitable for the PCX2SIX utility.  Color is
          supported for up to 256 colors.  Note though that most
          terminals only support the first 16 colors.

    5.2.3 Almost all PC Windows applications can output to this
          format at least through the WINDOWS clipboard capture.

    5.2.4 PAINT supplied with Windows can put any clipboard image
          into the PCX format.

    5.2.5 The final SIXEL files can still be used to create hard
          copy output by printing them to an appropriate network
          SIXEL printer once they are on the VAX/VMS system.

    5.2.6 The PCX2SIX utility will not add or delete pixels.  If
          the number of X direction pixels was 640 then the number
          of X direction SIXELS will also be 640.  See section 8.2
          for more information.5.3General procedure outline

    5.3.1 Select an application package for graphics generation on
          your platform of choice running your operating system of
          choice.

    5.3.2 Create the drawing.

    5.3.3 If needed capture the picture to the clipboard and paste
          it into PAINT.  Save the image as a PCX file.

    5.3.4 Convert the file using the PCX2SIX utility.

    5.3.5 Upload/Transfer the SIXEL file to the VAX/VMS system.

    5.3.6 Use the type command to display the picture and determine
          if the appearance is what was desired.  With MS Kermit
          the REPLAY command can also be used to display the SIXEL
          graphic without transferring the graphic to a VMS host
          system.

    5.3.7 Use the PCX2SIX command line switches as needed to change
          the picture appearance.


6. Using PCX2SIX

  This section describes basic operation of the PCX2SIX conversion
  utility.  This is a DOS PC based tool.  No special PC
  requirements are needed.

  6.1 Hardware: IBM Compatible PC

    6.1.1 The utility will create the SIXEL file on the hard disk.
          There must be enough free disk space for the output
          files.

    6.1.2 There must be at least three free file spaces available
          from the FILES & BUFFERS settings.  This is usually not
          a problem.

    6.1.3 The utility should run in as little as 64K of ram.

  6.2  Software: PCX2SIX.EXE

    6.2.1 The only software required for the conversion is the
          PCX2SIX utility itself.

    6.2.2 Create a directory for the utility then use a copy
          command to copy the executable from the distribution disk
          onto the hard disk.

  6.3. Running PCX2SIX

    6.3.1 The conversion utility is started by typing pcx2six
          followed by the full filename and optional extension. For
          example:

            C:>pcx2six test.pcx   <ret>

    6.3.2 Note that unless otherwise indicated the file must reside
          in the current directory. Optionally a disk drive and
          path may precede the full filename and optional
          extension.  For example:

            C:>pcx2six D:\files\test.pcx   <ret>

          In this case the output file test.six will also reside in
          the directory D:\files.

    6.3.3 The file is now transferred to the VAX using any number
          of utilities, or displayed in Kermit v 3.14 using the
          REPLAY command at the prompt.  The file is an ASCII file,
          do not use a binary file transfer protocol.  The file may
          be viewed on the VAX by a simple TYPE command.


  6.4 Optional Command line inputs

      There are numerous optional command line switches to allow
      minor customizing and correction of the bitmap images.

    6.4.1 The command line input will accept a second filename
          parameter.  This filename parameter indicates to the
          utility that the output is to be directed into a file
          with a user specified file name.  The parameter is the
          filename to create.

    6.4.2 When invoked as C:>pcx2six test.pcx capture.txt  <ret>
          the file capture.txt will be created and will contain all
          of the SIXEL commands needed to draw the picture.

    6.4.3 After transfer the SIXEL file may be viewed by using the
          VAX/VMS type command, for example $type capture.txt
          <ret>. Kermit 3.14 can also be used to view the file, at
          the prompt >replay capture.txt

    6.4.4 This SIXEL file is also suitable for printing on any
          SIXEL compatible printer.

  6.5 The Palette Features

    A feature of the utility is the ability to adjust the palette.
    Most of the command line switches are related to palette
    manipulation.  The SIXEL protocol supports up to 256 colors,
    however most emulators only support 16.  Best results have been
    obtained by keeping to 16 or less colors.

    6.5.1 The /I Switch

          The /I switch will instruct the utility to Ignore any
          palette information.  This means that it will select the
          colors based on id number but will make no attempt to
          adjust the RGB value of the id number.  In this case the
          terminal palette colors will be used for display, even if
          the colors have been changed by someone or something.
          Note that under normal condition the terminal colors map
          well to the standard PC colors.

    6.5.2 The /P Switch

          The /P switch will instruct the utility to create and use
          a default Palette.  The default palette will be identical
          to the factory default 16 color palette on a VT340.

    6.5.3 The /R Switch

          The /R switch will instruct the utility to Read in and
          use a palette file.  The palette file name must be the
          same as the PCX file being processed but with the
          extension of .PAL.  This feature allows fine tuning of
          the individual palette values for the SIXEL output file.
          The palette file format is discussed later in this
          document.

    6.5.4 The /W Switch

          The /W switch will instruct the utility to Write out the
          palette information.  A file with the same name as the
          PCX input file but with the extension of .PAL will be
          created.  If the file already exists it will be
          overwritten.  This output file is in the same format that
          is needed for the /R switch.

    6.5.5 The /S Switch

          The default output disables SIXEL scrolling.  This is to
          insure that the image does not roll off of the top of the
          screen.  Using the /S switch will ENABLE SIXEL scrolling
          if desired.

    6.5.6 The /M Switch

          The /M switch must be followed by a number between 0 and
          15.  This number sets the color to be used for the
          Monochrome image conversion.  The default if /M is not
          used is color 7 (white).  The exact syntax would appear
          as /M5 to use color 5 for the monochrome image.  Note
          that this does not change the background color which will
          remain at whatever the terminal has set into the palette
          for color 0.

    6.5.7 The /B Switch

          On occasion it may be desirable to scale up or down the
          palette values.  The /B allows the scaling without having
          to modify a palette file.  The exact syntax would be
          /B120 or /B90.  The scaling is performed relative to 100,
          so /B120 will increase the palette numbers by
          approximately 120/100, whereas /B90 would decrease the
          palette values by about 90/100.  The maximum palette
          value is 100.  The default /B value is 100.

    6.5.8 The /X and /Y Switches

          The two switches /X and /Y work together to set the pixel
          aspect ratio.  The default values are 2 and 1 for X and
          Y respectively.  These switches can be used to change
          somewhat the size of the image.  The switches when used
          would look like /X2 /Y1.

  6.6 Multiple command line switches may be used.  The only
      restriction is to separate the switches requiring a numeric
      input by a space.

    6.6.1 Good Example: C:>pcx2six input output /P/W/B110 /S

    6.6.2 Bad Example:  C:>pcx2six input output /P/B110/W/S

    6.6.3 Summary:  Switches /B, /M, /X, /Y must all be followed
                    by a space.

7. Palette file format

  7.1 The palette file used by the utility is in ASCII.

  7.2 There is one line per color, and there must be either 16 or
      256 lines or the palette file will be considered invalid.

  7.3 The color values are stored three to a line in Red Green Blue
      format.

  7.4 Each RGB value is separated by a vertical bar character |.

  7.5 The file may be edited with any ASCII editor like NOTEPAD, or
      DOS EDIT utility.

  7.6 An example file:

|0|0|0|
|20|20|80|
|80|13|13|
|20|80|20|
|80|20|80|
|20|80|80|
|80|20|20|
|53|53|53|
|26|26|26|
|33|33|60|
|60|26|26|
|33|60|33|
|60|33|60|
|33|60|60|
|60|60|33|
|80|80|80|

  7.7 Each palette value can be from 0 to 100.


8. Limitations

  8.1 Colors -  Most terminals in use today only support 16
                colors. The utility supports 256 colors.  If the
                pictures are to be viewed by a wide audience use a
                maximum of 16 colors.

  8.2 Resolution -  The VT340 supports 800 x 480 pixels, across
                    and down respectively.  The typical PC is 640
                    x 480.  Aspect ratios will not be exact.  Some
                    emulators will show a reduced size version
                    that is the 640 x 480 within an 800 x 480
                    emulated window, while others chose to show
                    the 640 x 480 as the entire screen.  A true
                    VT340 shows the PC picture as 640 x 480 within
                    the 800 x 480 window.

                    When creating the PCX file set the number of
                    pixels desired, draw, then convert.  Also try
                    using the /X /Y options for aspect ratios.

  8.3 VT330 - The VT330 is a monochrome terminal.  The terminal
              will adjust the color information into 4 shades of
              white.  Test color images on VT330 terminals.

  8.4 VT240 - The VT240 has less vertical pixels than the newer
              graphics terminals, therefore part of the image will
              not be on the screen.

  8.5 Speed - On a main frame system the drawing speed is limited
              by the speed of the terminal connection.  The faster
              the connection the faster the picture shows up.


9. Troubleshooting

    This section contains some common problems.

  9.1 Switch problems

    9.1.1 All command line switches must be in UPPER CASE.

    9.1.2 If the switch requires a number the number must be
          followed by a space.

  9.2 Invisible Colors

    9.2.1 Try converting into 16 colors using PAINT or PBRUSH from
          ZSoft Corporation.

    9.2.2 Try setting the palette colors manually using a .PAL
          file.

  9.3 File Transfer VAX/VMX Buffer overflow

    9.3.1 Transfer the file to VAX using ASCII(text) protocol not
          Binary.

  9.4 Blank Screen

    9.4.1 The terminal does not support graphics.  Switch to a
          VT330 or VT340.

    9.4.2 If using an emulator check the documentation to verify
          that it supports SIXEL GRAPHICS.  A VT320 for example
          will not support SIXEL or ReGis graphics.

(End)