From 2c2b88a6c612e2043aab040ba4bdf16f1a28cbe0 Mon Sep 17 00:00:00 2001
From: Ian Jauslin <ian.jauslin@rutgers.edu>
Date: Wed, 10 May 2023 15:03:28 -0400
Subject: [PATCH] Add README

---
 README | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 README

diff --git a/README b/README
new file mode 100644
index 0000000..b371f50
--- /dev/null
+++ b/README
@@ -0,0 +1,61 @@
+Jam is visualization software for hard-core lattice particle systems. It is
+designed to explore configurations of particles while enforcing that no two
+particles overlap.
+
+**Jam is a work in progress and is nowhere near ready for production.**
+
+
+# Basic usage
+
+Run with
+```bash
+  ./src/jam [configuration_file]
+```
+where `[configuration_file]` is an optional argument that specifies a file with
+a list of particle positions that will be loaded on initial execution.
+
+
+# User interface
+
+  * `<right-click>`: create a new particle under the mouse pointer (if the
+    particle fits)
+
+  * `<shift><left-click>`: select/unselect multiple particles
+
+  * `<left-click>` and drag: move selected particle(s).
+
+  * `backspace`: delete selected particle(s)
+
+
+# Commands
+
+Commands can be executed by typing `:` (similarly to vim).
+
+  * `:q`: exit
+
+  * `:w [path_to_file]`: Write particle configuration to file. This will not
+    overwrite existing files; use `:w!` to overwrite.
+
+  * `:e <path_to_file>`: edit file.
+
+  * `:export <path_to_file>`: Export configuration to LaTeX (using TikZ)
+
+  * `:set color <color_spec>`: Set color of selected particles to
+    `<color_spec>`. The supported format for `<color_spec>` is either `r,g,b`
+    with `r`, `g`, and `b` in [0,1], or one of
+    `red|green|blue|brown|lime|orange|pink|purple|teal|violet|cyan|magenta|yellow|olive|black|darkgray|gray|lightgray|white`.
+
+  * `:set zoom <zoom_level>`: Scale all particles by `<zoom_level>`.
+
+  * `:set grid [on|off]`: Add a visual grid centered on one of the selected
+    particles. The size of the mesh can be specified by passing
+    `:set grid <size_of_mesh>`.
+
+
+# Current developments
+
+So far, Jam only supports cross-shaped particles, but work is in progress to
+support arbitrary shapes consisting of rectangles, circle arcs and triangles
+(check out the `dev` branch to follow the progress).
+
+Support for lattice configurations is also ongoing.