home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 2 / FFMCD02.bin / new / os30 / gfx / cpk / cpk.doc < prev    next >
Encoding:
Text File  |  1993-12-21  |  16.7 KB  |  494 lines
  1.  
  2.  
  3.  
  4.             CPK Program Documentation
  5.             -------------------------
  6.                   V 2.0 10/9/93
  7.  
  8.                   © 1993 Eric G. Suchanek, Ph.D.
  9.                    All Rights Reserved     
  10.  
  11.  
  12. Introduction
  13.  
  14.    CPK is a program to render a space-filling representation of atoms in
  15. molecules.  This is the type of representation one would find in the
  16. plastic 'CPK' (Corey, Pauling, Kendrew) models often used in organic
  17. chemistry. The program is AmigaDos V 3.x specific, and has no hard-coded
  18. constraints in the number of atoms it can process. Unlike many
  19. programs of a similar nature, CPK correctly handles intersecting
  20. 3-dimensional spheres by using the famous Bresenham circle algorithm
  21. in 3D. In order to keep the program simple and reasonably fast I do
  22. not supersample the spheres, so their resolution is essentially equal
  23. to the display screen you're using at the time.
  24.  
  25.    That's all well and good, but what does it really mean?? Well, simply
  26. put it means that the sphere's surface gets increasingly inaccurate
  27. as your resolution goes down. Don't be surprised to see the image
  28. quality degrade as the screen resolution drops. See the TIPS section
  29. below for a "workaround".
  30.  
  31.    The molecular format used is called Protein Data Bank (.pdb) format.
  32. This is one of the most prevalent formats used in modern chemistry.
  33. The entire Protein Data Bank consists of a few hundred protein and DNA
  34. molecular structures and can be obtained from the Brookhaven
  35. laboratories for a nominal fee (or from me if you know what you want).
  36.  
  37.  
  38. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39.  
  40. System Requirements:
  41.  
  42.   CPK should run on any Amiga with at least 1MB memory. It tries
  43.   to be reasonably tolerant of low memory conditions, and should
  44.   gracefully degrade if it can't get memory.
  45.  
  46.   This program was written for Version 3.X of the Amiga Operating 
  47.   System! It will no longer run under Version 2.X!
  48.  
  49.   This program also requires Nico Francois' reqtools.library, which is
  50.   available on many public BBS. I currently use reqtools.library V38.1042.
  51.  
  52. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53.  
  54. Dedication:
  55.  
  56. I dedicate this program to my late son George Kelly Suchanek. His life 
  57. was short, but while he was with us he showed me what is really important...
  58.  
  59. Requiescat in Pace.
  60.  
  61.  
  62. I also dedicate this program to the Gurus of the Public Domain who
  63. selflessly write good, solid code for the Amiga community. They are
  64. all, in large measure responsible for the continuing existence of this
  65. machine.  The quality of many public domain and shareware programs on the 
  66. Amiga rivals many commerical programs on the PC and MAC.
  67.  
  68.  
  69. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  70.  
  71. Disclaimer: 
  72.  
  73. It displays molecules. It does not crash my machine, nor do I get
  74. Enforcer or Mungwall hits with it. It does not "leak" memory.
  75. It will not solve the world's problems nor will it balance the federal
  76. budget. There are no warranties either expressed or implied. 
  77. Use at your own risk!
  78.  
  79. I consider this program to be CHARITYWARE: If you like it, please
  80. consider sending a donation to the National SIDS foundation. You can read
  81. more about SIDS in the About.SIDS document included in this distribution.
  82.  
  83. If you have any 3D solid modeling algorithms with shading I'd love to seem them,
  84. (especially some 3D cylinder shading routines).
  85.  
  86. I am unable to distribute the CPK source code except to licensed Amiga 
  87. developers, since the IFF routines are developer beta and can not be generally 
  88. distributed asorry :-(
  89.  
  90.  
  91. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  92.  
  93.  
  94. License:
  95.  
  96.    You may distribute this program freely as long as it is not "For Profit",
  97. and as long as all files in the distribution remain intact. Fred Fish 
  98. is expressly given permission to distribute this code in his disk 
  99. collection.
  100.  
  101.  
  102. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  103.  
  104. Installation
  105.  
  106. Drag the CPK drawer to some appropriate location on your system. Keep the
  107. directory hierarchy intact, though.
  108.  
  109. Double click on the icon appropriate for your machine:
  110.  
  111.     68000 - CPK.000
  112.     68030 - CPK.030, (with math coprocessor).
  113.     68040 - CPK.040, (with math coprocessor).
  114.  
  115.  
  116.  
  117. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  118.  
  119. DISTRIBUTION KIT:
  120.  
  121. The distribution should contain:
  122.  
  123.     cpk.000        - Generic version which should run on all Amigas.
  124.     cpk.030        - 68030 specific version.
  125.     cpk.040        - 68040 specific version.
  126.     changes.doc    - The program history with recent changes
  127.  
  128.     pdb/cube.pdb    - A small file to test scaling, aspect ratios, etc.
  129.     pdb/nati2.pdb    - An actual protein molecule. This protein is used 
  130.               in some modern detergents as an enzyme which 
  131.               digests proteinacious stains.
  132.  
  133.     pdb/hello.pdb    - A whimsical "molecule"
  134.  
  135.     pdb/heme.pdb    - The heme group from myoglobin.
  136.  
  137.     pdb/zna2b.pdb    - A Z-Dna molecule.
  138.  
  139.     pdb/lysozyme.pdb - The enzyme lysozyme.
  140.  
  141.     pdb/znf2.pdb    - A modeled zinc-finger domain from the aids 
  142.               virus.
  143.  
  144.     pdb/mbn4.pdb    - Myoglobin
  145.  
  146.     pdb/*.pdb    - More atomic files as I acquire them.
  147.  
  148.     prefs/*.prefs   - Various preference files of settings.
  149.  
  150.     cpk.doc         - What you're reading now.
  151.  
  152.     prefs/*.*       - Various preference files and palettes.
  153.  
  154.     test.cpk        - AREXX script to test the CPK AREXX
  155.                     interface.
  156.  
  157.     About.SIDS      - Information about SIDS.
  158.  
  159.  
  160. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  161.  
  162. Using CPK:
  163.  
  164.     Double click on the correct program icon to launch the program. You
  165.     will notice that it immediately starts rendering a "molecule". This
  166.     is because the program always reads the STARTUP file (see the section
  167.     on TOOLTYPES, below) upon invocation. This is a good way to get up
  168.     and running fast.
  169.  
  170.     The program opens in the display mode saved in the startup file, and 
  171.     opens two windows. The Image window is sizable, and all rendering 
  172.     is performed here. The program will automagically re-center the 
  173.     molecule upon re-sizing. 
  174.  
  175.     If the saved displaymode is not available you will be prompted to 
  176.     select a new one.  When you first get CPK it's likely that you'll
  177.     see this requestor, since most of my preference files are saved
  178.     with Picasso II screen modes.
  179.  
  180.     When a molecule is rendering, a progress window will appear. This 
  181.     window indicates the rendering percentage completed and
  182.     allows the user to abort the current rendering by selecting the
  183.     Abort gadget.
  184.  
  185.     The Control window allows the user to change the orientation 
  186.     and scale of the molecule, as well as load files by name. The 
  187.     gadgets perform as follows:
  188.  
  189.     Rotation Gadgets:
  190.  
  191.         XROT
  192.         YROT
  193.         ZROT
  194.  
  195.        These gadgets perform rotations about the X, Y, and Z axes, 
  196.      respectively. The plane of the screen is considered the X,Y plane.
  197.  
  198.     Scaling Gadget:
  199.     
  200.       This gadget adjusts the overall scale of the image, sizing the 
  201.       molecule up from 1.0 to 20.0 fold. This is a relative scaling,
  202.       not absolute.
  203.  
  204.     File Name Gadget:
  205.  
  206.       This gadget allows the user to type in the name of a file to 
  207.       read. You'll see the screen flash (DisplayBeep()) if the file 
  208.       can't be read.
  209.  
  210.     Reset Gadget:
  211.  
  212.       This gadget resets the rotation axes and scaling factor, and 
  213.       re-renders the current molecule.
  214.  
  215.     Load File Gadget:
  216.  
  217.      This gadget opens the file-requester to load a molecule file. 
  218.  
  219.      There are several molecules in the PDB directory (this is where 
  220.      the Open ASL requester opens by default).      
  221.  
  222.       Note that some of the molecules are quite large. The file
  223.      'nati2.pdb' is over 1900 atoms and requires approximately
  224.      282 KB to load. Also, the process of reading the atoms
  225.      can take a while (about 10 seconds on my 25MHZ 68040 A4000).
  226.      I have greatly improved the file I/O in Version 2.0 of the
  227.      program, so large molecules should load considerably faster
  228.      then V1.0.
  229.  
  230.     Auto Render Checkbox Gadget:
  231.  
  232.      This gadget turns the Auto Render feature on and
  233.      off. Normally any rotation or scaling gadget manipulation will
  234.      force a re-render of the current molecule. With auto render
  235.      turned off the user may play with multiple gadgets without
  236.      automatically re-rendering.
  237.  
  238.  
  239.     Render Gadget:
  240.  
  241.      This gadget forces a re-render of the current molecule. It is
  242.      normally used when Auto Render is turned off.
  243.  
  244.         
  245. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  246.  
  247. Menus:
  248.  
  249.  
  250.    File Menu
  251.  
  252.     Open...
  253.         Open a preference file. Try to Open one after launching
  254.         the program. Hello.prefs is interesting.
  255.  
  256.     Save
  257.         Save the current X,Y,Z rotations, scaling, window sizes
  258.         and positions to the currently named 'preferences' file.
  259.  
  260.     SaveAs...
  261.         Save the current X,Y,Z rotations, scaling, window sizes
  262.         to a named 'preferences' file.
  263.  
  264.     Print
  265.         Print the molecule window to the printer. Uses default WB 
  266.         prefs. No abort gadget yet. Print if you're serious about
  267.         it!
  268.  
  269.     Save Window as IFF
  270.         Save the Molecule Window to an IFF ILBM format file using
  271.         a user-specified name. (Right Amiga I).
  272.  
  273.     About... 
  274.         Informational window about the current release of CPK.
  275.  
  276.     Quit
  277.         Quit? Why would you want to quit this cool program?
  278.  
  279.  
  280.    Screen Menu
  281.  
  282.     Screen Format...
  283.          Brings up the ASL screen mode requester to select a screen
  284.         mode. You must select a display with at least 4 bitplanes
  285.         of color. I recommend a 1024x768x8 display if possible.
  286.         This mode is saved in the settings file as well as
  287.         window positions and sizes.
  288.  
  289.  
  290.     Color Mode
  291.         Check either color or grayscale rendering mode.
  292.  
  293.     Palette...
  294.         Opens the palette editor window. You currently cannot save color
  295.         palettes.
  296.  
  297.    Animation Menu
  298.  
  299.     Anim Setup...
  300.         This window allows the user to specify a frame 
  301.         sequence of IFF files for use with post-processing programs.
  302.         I use DPAINT IV to load the individual frames into an 
  303.         animation, and manipulate them from there. By using the 
  304.         images as an AnimBrush it's possible to create some nice 
  305.         animations. The gadgets are described below:
  306.  
  307.         Frame Prefix:
  308.           Specifies the complete path prefix for the anim frames.
  309.           It should end in a period. For example: ram:mol_anim.
  310.           The program will add a numerical suffix like 001 to this
  311.           prefix in creating the file name.
  312.  
  313.         Start Frame:
  314.           Frame number the program should use when starting the
  315.           animation. (Zero based).
  316.  
  317.         End Frame:
  318.           Frame number to use for the ending frame. (Exclusive).
  319.           See Below for more info.
  320.  
  321.         Total Rotation:
  322.           Total rotation in degrees for the animation.
  323.  
  324.         X, Y, Z boxes:
  325.           If checked, will rotate about this axis.
  326.  
  327.     NOTE:
  328.         This is set up for Loop style animations. That is, if
  329.         you have selected, start 0, end 10, 360 degrees    rotation set, 
  330.         the program will compute frames 000 - 009 but you'll only 
  331.         rotate 360 - 360/10 degrees. This means    that cyclic loop
  332.         animations will not hesitate on the first frame.
  333.         In essence, you're doing one less frame, since the frame
  334.         counter is 0 based.
  335.  
  336.    Misc Menu
  337.  
  338.         Annotations Window:
  339.           Brings up a window to show the various 'annotations'
  340.           which may be present in the PDB file. Things like
  341.             the compound name, structure author, journal references
  342.           and crystallographic parameters are shown. Just click
  343.           on the cycle gadget to browse the annotations. Most of
  344.           the files included don't have any annotations present.
  345.  
  346.         Light Window:
  347.           Brings up the light source positioning window. The
  348.           three sliders for X, Y and Z represent the
  349.           direction vectors for the light source. X and Y 
  350.           can vary from -100 to 100, Z from 0 to 100. The Z direction is
  351.           out of the plane of the screen in this program. These are
  352.           the direction vectors times 100 (or percentages). As an
  353.           example, if X were 0, Y were 0 and Z 100, the light source would
  354.           be pointing along the Z axis. Simply set the values you want and
  355.           hit the OK button. The program will normalize the values for
  356.           you and re-render the molecule. This works best when the
  357.           QuickRender flag is turned ON. Select QuickRender and try moving
  358.           the light source around. Click on the Done gadget to remove the
  359.           window.
  360.           
  361.         CPK Scaling:
  362.           This menu option brings up a window which lets you specify the
  363.           scaling factor. A factor of 1.0 gives the normal CPK style
  364.           rendering, while factors < 1.0 make smaller spheres. This can
  365.           be useful when rendering structures like DNA which have a 
  366.           regular internal structure. Factors > 1.0 make more of a
  367.           'VanderWalls' style rendering.
  368.  
  369.         Quick Render:
  370.           When set this menu option disables some of the specular highlight
  371.           calculations (which use the transcendental power function).
  372.           On unaccelerated machines this can have a noticeable effect
  373.           on rendering times. Unfortunately in Quick Render mode the
  374.           program suffers from pretty severe color banding.
  375.  
  376.         Save Icons:
  377.           When set, this menu option saves a nifty icon with IFF files.
  378.  
  379. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  380.  
  381. AREXX:
  382.     
  383.    CPK now supports AREXX! The port name is CPK1. Errors are returned in 
  384.    the CPK.LASTERROR variable.  The return code will be 0 for normal
  385.    returns.  In general the load and save functions require a complete 
  386.    pathname.  See the example test.cpk for a test of all the 
  387.    AREXX functions.
  388.  
  389.    The command set is listed below:
  390.  
  391.     Command       Arguments
  392.  
  393.     PORT            - Returns the port name in the CPK.LASTERROR 
  394.                     variable
  395.  
  396.     LOAD PREFS <filename>    - Loads the specified preference file. 
  397.  
  398.     LOAD PDB   <filename>    - Loads the specified molecule file.
  399.  
  400.     SAVE PREFS <filename>    - Saves the specified preference file.
  401.  
  402.     SAVE IFF   <filename>    - Saves the molecule window to an iff
  403.                   file.
  404.  
  405.     XROT       <angle>    - Set the X axis rotation to <angle> 
  406.                   degrees. Does NOT render.
  407.  
  408.     YROT       <angle>    - Set the Y axis rotation to <angle> 
  409.                   degrees. Does NOT render.
  410.  
  411.     ZROT       <angle>    - Set the Z axis rotation to <angle> 
  412.                   degrees. Does NOT render.
  413.  
  414.     SCALE      <amount>     - Sets the overall scale to <amount>.
  415.                   This can range from 1 to 20.
  416.                   Does NOT render.
  417.  
  418.     RESET      <NULL>       - Resets the rotations and scaling to
  419.                   default values. Does NOT render.
  420.  
  421.     RENDER     <NULL>    - Renders the molecule using the current
  422.                   settings.  
  423.  
  424.     QUIT       <NULL>    - Quits the program.
  425.  
  426. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  427.  
  428. Tooltypes:
  429.     
  430.    CPK supports the following tooltypes:
  431.  
  432.     TOOLPRI     - The priority of the program. I usually run at -1.
  433.  
  434.     SETTINGS     - The preference file to open upon startup. Default
  435.               is cpk.prefs.
  436.  
  437.  
  438. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  439.  
  440. Known Limitations/Quirks
  441.  
  442.     1) No abort from printing. Do it if you really mean it.
  443.     2) No stereo viewing (I'm working on this).
  444.     3) No wireframe viewing (I'm also working on this).
  445.     4) No launch from Tool icon.
  446.     5) No multi-project management.
  447.     6) One must bring the image window to the front before doing an
  448.        IFF save in order to avoid getting any other intersecting windows
  449.        in the picture.
  450.     
  451.  
  452. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  453.  
  454. TIPS:
  455.  
  456.      1) Be patient. The sphere intersection code is all integer math,
  457.     but it still takes a while to traverse the atom lists during the
  458.     course of rendering, especially on a 68000 machine.
  459.  
  460.      2) Try to run the program with a fairly large scale. The output looks
  461.     better with larger spheres.
  462.  
  463.      3) Run at the highest possible resolution.  
  464.  
  465.      4) A narrow rendering window narrow speeds up the calculations, since
  466.     the program builds a cliprect based on the window inner width and
  467.     only traverses that width on rendering.
  468.  
  469.      5) When saving IFF images, make sure the molecule image window is in
  470.     front of all other windows. Otherwise the IFF image might have
  471.     the other window regions saved as well.
  472.      
  473.  
  474. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  475.  
  476.     Drop me some E-Mail if you'd like to comment on the program
  477.     or share code.
  478.  
  479.  
  480.     Eric G. Suchanek, Ph.D.
  481.  
  482.     BIX:  esuchanek@bix.com
  483.     CIS:  76456,710
  484.     INET: procter!suchanek_eg@ms.uky.edu <-- preferred
  485.  
  486.     U.S. Snail:
  487.  
  488.         5785 Lake Michigan Drive
  489.         Fairfield, OH 45014-4421
  490.  
  491.  
  492. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  493.  
  494.