home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d8xx / d809 / cpk.lha / CPK / CPK.doc < prev    next >
Text File  |  1993-01-24  |  14KB  |  401 lines
  1.  
  2.  
  3.  
  4.             CPK Program Documentation
  5.             -------------------------
  6.                  V 1.0 1/3/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.    This program represents a small piece of a larger program called
  38. Proteus-C, the C version of the Proteus molecular modeling package I
  39. co-developed as a graduate student. The main Proteus kernel is
  40. device-independent and runs on VAX, Silicon Graphics, Trace/Multiflow,
  41. Sun, and Amiga platforms.  As I have time I'm writing molecular
  42. display front-ends on these systems (mostly Amiga and SGI, though).
  43. Since it took me six years to write this module, it will probably be a
  44. while before new ones are released :-)
  45.  
  46.  
  47. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  48.  
  49. System Requirements:
  50.  
  51.   CPK should run on any Amiga with at least 1MB memory. It tries
  52.   to be reasonably tolerant of low memory conditions, and should
  53.   hopefully gracefully degrade if it can't get memory.
  54.  
  55.   This program will run only under Version 3.X of the Amiga Operating 
  56.   System!
  57.  
  58.  
  59. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  60.  
  61. DEDICATION:
  62.  
  63. I dedicate this program to my late son George Kelly Suchanek. His life 
  64. was short, but while he was with us he showed me what is really important...
  65.  
  66. Requiescat in Pace.
  67.  
  68.  
  69. I also dedicate this program to the Gurus of the Public Domain who
  70. selflessly write good, solid code for the Amiga community. They are
  71. all, in large measure, responsible for the continuing existence of this
  72. machine and the excitement felt by her users. The folks in the Amiga
  73. CATS sections of BIX also deserve special praise, both for their
  74. professionalism and their ability to develop the best microcomputer in
  75. the world despite their management. I salute them!
  76.  
  77.  
  78. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79.  
  80. Disclaimer: 
  81.  
  82. It displays molecules. It does not crash my machine, nor do I get
  83. Enforcer or Mungwall hits with it. It does not "leak" memory.
  84. It will not solve the world's problems nor will it balance the federal
  85. budget. There are no warranties either expressed or implied. 
  86. Use at your own risk!
  87.  
  88. I consider this program to be CHARITYWARE: If you like it, please
  89. consider sending a donation to the National SIDS foundation. You can read
  90. more about SIDS in the About.SIDS document included in this distribution.
  91.  
  92. I'd also be interested in good 3D matrix manipulation algorithms in 680x0 
  93. Assembly. Also, 3D solid modeling algorithms with shading would be 
  94. GREATLY appreciated. 
  95.  
  96. I would distribute the CPK Source code with this release, but it is in
  97. a state of flux right now. Also some of the IFF routines are still
  98. developer beta, and I don't think I can release the source for them -
  99. sorry :-(
  100.  
  101.  
  102. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  103.  
  104.  
  105. License:
  106.  
  107.    You may distribute this program as long as it is not "For Profit",
  108. and as long as all files in the distribution remain intact. Fred Fish 
  109. is expressly given permission to distribute this code in his disk 
  110. collection.
  111.  
  112.  
  113. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  114.  
  115. Installation
  116.  
  117. Drag the CPK drawer to some appropriate location on your system. Keep the
  118. directory hierarchy intact, though.
  119.  
  120. Double click on the icon appropriate for your machine:
  121.  
  122.     68000 - CPK.000
  123.     68030 - CPK.030
  124.     68040 - CPK.040.
  125.  
  126.  
  127.  
  128. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  129.  
  130. DISTRIBUTION KIT:
  131.  
  132. The distribution should contain:
  133.  
  134.     cpk.000        - Generic version which should run on all Amigas.
  135.     cpk.030        - 68030 specific version.
  136.     cpk.040        - 68040 specific version.
  137.  
  138.     pdb/test.pdb    - A small molecular fragment.
  139.     pdb/cube.pdb    - A small file to test scaling, aspect ratios, etc.
  140.     pdb/nati2.pdb    - An actual protein molecule. This protein is used 
  141.               in some modern detergents as an enzyme which 
  142.               digests proteinacious stains.
  143.  
  144.     pdb/hello.pdb    - A whimsical "molecule"
  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.     About.SIDS      - Information about SIDS.
  153.  
  154.  
  155. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  156.  
  157. Using CPK:
  158.  
  159.     Double click on the correct program icon to launch the program. You
  160.     will notice that it immediately starts rendering a "molecule". This
  161.     is because the program always reads the STARTUP file (see the section
  162.     on TOOLTYPES, below) upon invocation. This is a good way to get up
  163.     and running fast.
  164.  
  165.     The program opens in interlaced, overscan mode, and opens two
  166.     windows. The Image window is sizable, and all rendering is performed
  167.     here. The program will automagically re-center the molecule upon 
  168.     re-sizing. 
  169.  
  170.     When a molecule is rendering, a progress window will appear. This 
  171.     window indicates the rendering percentage completed as well as
  172.     allowing the user to abort the current rendering by selecting the
  173.     Abort gadget.
  174.  
  175.     The Control window allows the user to change the orientation 
  176.     and scale of the molecule, as well as load files by name. The 
  177.     gadgets perform as follows:
  178.  
  179.     Rotation Gadgets:
  180.  
  181.         XROT
  182.         YROT
  183.         ZROT
  184.  
  185.        These gadgets perform rotations about the X, Y, and Z axes, 
  186.      respectively. The plane of the screen is considered the X,Y plane.
  187.  
  188.     Scaling Gadget:
  189.     
  190.       This gadget adjusts the overall scale of the image, sizing the 
  191.       molecule up from 1.0 to 10.0 fold. This is a relative scaling,
  192.       not absolute.
  193.  
  194.     File Name Gadget:
  195.  
  196.       This gadget allows the user to type in the name of a file to 
  197.       read. You'll see the screen flash (DisplayBeep()) if the file 
  198.       can't be read.
  199.  
  200.     Reset Gadget:
  201.  
  202.       This gadget resets the rotation axes and scaling factor, and 
  203.       re-renders the current molecule.
  204.  
  205.     Load File Gadget:
  206.  
  207.      This gadget opens the file-requester to load a molecule file. 
  208.  
  209.      There are several molecules in the PDB directory (this is where 
  210.      the Open ASL requester opens by default).      
  211.  
  212.       Note that some of the molecules are quite large. The file
  213.      'nati2.pdb' is over 1900 atoms and requires approximately
  214.      282 KB to load. Also, the process of reading the atoms
  215.      can take a while (about 30 seconds on my 25MHZ 68040 A3000).
  216.  
  217.     Auto Render Checkbox Gadget:
  218.  
  219.      This gadget turns the Auto Render feature on and
  220.      off. Normally any rotation or scaling gadget manipulation will
  221.      force a re-render of the current molecule. With auto render
  222.      turned off the user may play with multiple gadgets without
  223.      automatically re-rendering.
  224.  
  225.  
  226.     Render Gadget:
  227.  
  228.      This gadget forces a re-render of the current molecule. It is
  229.      normally used when Auto Render is turned off.
  230.  
  231.         
  232. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  233.  
  234. Menus:
  235.  
  236.  
  237.    File Menu
  238.  
  239.     Open...
  240.         Open a preference file. Try to Open one after launching
  241.         the program. Hello.prefs is interesting.
  242.  
  243.     Save
  244.         Save the current X,Y,Z rotations, scaling, window sizes
  245.         and positions to the currently named 'preferences' file.
  246.  
  247.     SaveAs...
  248.         Save the current X,Y,Z rotations, scaling, window sizes
  249.         to a named 'preferences' file.
  250.  
  251.     Print
  252.         Print the molecule window to the printer. Uses default WB 
  253.         prefs and currently does not have file notification setup. 
  254.         This means that if you change the printer prefs file 
  255.         using a Preference Editor, you should quit the program and 
  256.         restart.
  257.  
  258.     About... 
  259.         Informational window about the current release of CPK.
  260.  
  261.     Quit
  262.         Quit? Why would you want to quit this cool program?
  263.  
  264.  
  265.    Screen Menu
  266.  
  267.     Screen Format...
  268.         Allows the user to choose between a low-res or hi-res and
  269.         interlaced or non-interlaced display. NOTE: these
  270.         screens are opened in STDSCREENWIDTH STDSCREENHEIGHT 
  271.         overscan mode.
  272.  
  273.     Save Window as IFF
  274.         Save the Molecule Window to an IFF ILBM format file using
  275.         a user-specified name. (Right Amiga I).
  276.  
  277.     Save Icons?
  278.         Boolean value indicating whether or not to create icons for
  279.         the IFF window dumps. The default tool on these images is
  280.         Display.
  281.  
  282.    Animation Menu
  283.  
  284.     Anim Setup...
  285.         This window allows the user to specify a frame 
  286.         sequence of IFF files for use with post-processing programs.
  287.         I use DPAINT IV to load the individual frames into an 
  288.         animation, and manipulate them from there. By using the 
  289.         images as an AnimBrush it's possible to create some nice 
  290.         animations. The gadgets are described below:
  291.  
  292.         Frame Prefix:
  293.           Specifies the complete path prefix for the anim frames.
  294.           It should end in a period. For example: ram:mol_anim.
  295.           The program will add a numerical suffix like 001 to this
  296.           prefix in creating the file name.
  297.  
  298.         Start Frame:
  299.           Frame number the program should use when starting the
  300.           animation. (Zero based).
  301.  
  302.         End Frame:
  303.           Frame number to use for the ending frame. (Exclusive).
  304.           See Below for more info.
  305.  
  306.         Total Rotation:
  307.           Total rotation in degrees for the animation.
  308.  
  309.         X, Y, Z boxes:
  310.           If checked, will rotate about this axis.
  311.  
  312.     NOTE:
  313.         This is set up for Loop style animations. That is, if
  314.         you have selected, start 0, end 10, 360 degrees    rotation set, 
  315.         the program will compute frames 000 - 009 but you'll only 
  316.         rotate 360 - 360/10 degrees. This means    that cyclic loop
  317.         animations will not hesitate on the first frame.
  318.         In essence, you're doing one less frame, since the frame
  319.         counter is 0 based.
  320.  
  321.  
  322. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  323.  
  324. Tooltypes:
  325.     
  326.    CPK supports the following tooltypes:
  327.  
  328.     TOOLPRI     - The priority of the program. I usually run at -1.
  329.  
  330.     SETTINGS     - The preference file to open upon startup. Default
  331.               is cpk.prefs.
  332.  
  333.     PUBSCREEN    - < Not supported yet >
  334.  
  335.     SAVEICONS    - < Not supported yet >
  336.     
  337.  
  338. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  339.  
  340. Known Limitations/Quirks
  341.  
  342.     1) No abort from printing. Do it if you really mean it.
  343.     2) No stereo viewing (I'm working on this).
  344.     3) No wireframe viewing (I'm also working on this).
  345.     4) Need better Public Screen support.
  346.     5) No launch from Tool icon.
  347.     6) The ultra low-res modes aren't too good.
  348.     7) No multi-project management.
  349.     8) One must bring the image window to the front before doing an
  350.        IFF save in order to avoid getting any other intersecting windows
  351.        in the picture.
  352.     
  353.  
  354. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  355.  
  356. TIPS:
  357.  
  358.      1) Try to run this program in Interlaced mode because the pixel 
  359.     aspect ratio is closer to 1:1. In HighRes-Interlace you'll
  360.     only get 16 color gray scale screens. That was a tough decision
  361.     but there just aren't enough colors in 4 bitplane screens to get
  362.     good looking renderings. Perhaps when I get my A1200?
  363.  
  364.      2) Be patient. The sphere intersection code is all integer math,
  365.     but it still takes a while to traverse the atom lists during the
  366.     course of rendering, especially on a 68000 machine.
  367.  
  368.      3) Try to run the program with a fairly large scale. The output looks
  369.     better with larger spheres.
  370.  
  371.      4) Keeping the rendering window narrow speeds up the calculations, since
  372.     the program builds a cliprect based on the window inner width and
  373.     only traverses that width on rendering.
  374.  
  375.      5) When saving IFF images, make sure the molecule image window is in
  376.     front of all other windows. Otherwise the IFF image might have
  377.     the other window regions saved as well.
  378.      
  379.  
  380. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  381.  
  382.     Drop me some E-Mail if you'd like to comment on the program
  383.     or share code.
  384.  
  385.  
  386.  
  387.     Eric G. Suchanek, Ph.D.
  388.  
  389.     BIX:  esuchanek
  390.     CIS:  76456,710
  391.     INET: procter!suchanek_eg@ms.uky.edu
  392.  
  393.     U.S. Snail:
  394.  
  395.         5785 Lake Michigan Drive
  396.         Fairfield, OH 45014-4421
  397.  
  398.  
  399. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  400.  
  401.