README for KiNG
Author: Ian W. Davis

# README file for KiNG

## What is KiNG?

KiNG is a program for viewing and interacting with three-dimensional illustrations in "kinemage" format. This file describes how to run KiNG and serves as a guide to the other resources in this distribution.
More information on kinemage graphics and their uses in structural biology and in teaching 3-D literacy is available from the homepage of the Richardson laboratory at Duke University: http://kinemage.biochem.duke.edu/

## Running KiNG

To run KiNG, simply double-click on the file named `king.jar`. On most systems, this will launch the Java interpretter and run KiNG -- after a few seconds, the KiNG window(s) should appear on your screen.
If nothing happens, it probably means you don't have Java installed. Only Apple computers running Mac OS X come with Java "out of the box"; Windows and Linux users need to get Java from Sun and install it. Don't worry -- it's not hard and it doesn't cost anything. Just go to this page and you'll be up and running in no time: http://java.sun.com/getjava/index.html
KiNG works on any platform that provides a modern (1.3+) Java Virtual Machine; at the moment, that includes Windows, Apple's OS X, Linux (x86 only), and Solaris. Note that some tools and plugins, like the Backrub tool for refitting protein backbone, require Java 1.4 or later. YOU MUST HAVE JAVA INSTALLED IN ORDER FOR KING TO RUN!!! For more information on Java visit http://java.sun.com/ or http://www.java.com
Unix types may want to create a shell script to launch KiNG on their system; it should look something like this:
`#!/bin/sh
exec java -Xms32m -Xmx128m -jar /home/ian/bin/jars/king.jar "$@"
` Just enter those two lines into a text file named 'king' (change the path to point to your copy of king.jar, please), run the command 'chmod 755 king', and then move it to someplace that's on your PATH -- maybe '/usr/local/bin' or '~/bin'. The -Xms and -Xmx switches are optional; they are recommendations for initial and maximum memory allocations (respectively) that will handle almost any size kinemage. For very large kinemages, you might increase -Xmx to 256 MB or more.
Users of Apple's OS X may want to include two additional flags, immediately following the exec java part of the command (separated by spaces, of course). Adding -Dapple.awt.antialiasing=on will make the graphics much prettier, and helps offset the fact that the drawing primitives are broken (too large) in Apple's implementation. Adding -Dswing.defaultlaf=javax.swing.plaf.metal.MetalLookAndFeel will cause KiNG to use the standard Java Look & Feel instead of emulating a native Mac application. The native Mac version is somewhat buggy, so try this if you get unexplained crashes on OS X.

## Documentation and license terms

KiNG features a relatively complete user's guide that is accessible from the
Help menu. Individual tools in the Toolbox also have their own documentation.
For those who prefer hard copies, the `doc/` directory contains a PDF of the
manual and may contain other relevant documentation as well.
KiNG and most contents of this distribution are covered by the terms of the
license found in the LICENSE file. Other libraries and resources bundled
as part of the distribution are governed by their own terms as described
in the user manual.

Last updated 4 Mar 2004 by IWD for KiNG 1.22