README.md

@@ -1,9 +1,56 @@
-This addon adds some Lattice-based utilities to Blender.
+This addon adds some Lattice-based utilities to Blender. 
+
+Install like any other Blender addon: Download this repository as a .zip archive, then in Blender go to Edit->Preferences->Addons->Install Addon from File, and browse the zip you downloaded, and enable the checkbox for the addon.
+
+After that, you can find the Lattice Magic panel in the 3D Viewport's Sidebar, which you can bring up by pressing the N key.  
+![](docs/lattice_magic.png)
 
 # Tweak Lattice
 Tweak Lattice lets you create a lattice setup at the 3D cursor to make deformation adjustments to the selected objects.
 
+![](docs/tweak_lattice.gif)
+
+### Parenting
+This is meant to be possible to be used in conjunction with a character rig: Before pressing the "Create Tweak Lattice" button, simply select the desired parent rig object and bone in the UI.
+
+### Deletion
+If you want to delete a lattice, don't just delete the empty object that was created for you. This would leave behind a big mess of broken modifiers and drivers which will cause tremendous error printing spam in your console/terminal. Instead, use the "Delete Tweak Lattice" button.
+
+### Adding/Removing objects
+When creating a lattice, it will affect all mesh objects which were selected at the moment of its creation.  
+
+If you want more objects to be affected by a single lattice, you don't need to delete it and re-create it. Just select the objects you want to be affected, then finally select the lattice control. There will now be an "Add Selected Objects" button, which should do what it says. If a selected object was already affected by the lattice, it won't be affected.  
+
+Removing objects from being influenced works exactly the same way.
+
+### Going under the hood
+With the lattice control selected, you can see a "Helper Objects" section in the UI. This lists two objects which are taking care of things under the hood. If you want, you can enable them with the screen icon, which will let you mess with them. This should rarely be necessary though.
+
+
 # Camera Lattice
 Camera Lattice lets you create a lattice in a camera's view frame and deform a character (or any collection) with the lattice.
 
-Note: If you want to delete a lattice, make sure to do it through the addon's UI, which is in the sidebar. This will make sure to delete all modifiers, drivers and animation datablocks that were created along with the lattice.
+![](docs/tweak_lattice.gif)
+
+### Creation
+At first the Camera Lattice UI just shows an empty list. You can add an entry with the + icon. Each entry corresponds to deforming a single collection with a single lattice object from the perspective of a single camera.  
+
+You must select a collection and a camera, then hit Generate Lattice. Note that you cannot change the resolution after the fact, so find a resolution that you're happy with, as you will be locked into that.
+
+### Animation
+Animating the lattice is possible using shape keys. The addon provides some UI and helper operators for this, but at the end of the day it's up to you how you organize and keyframe these shape keys.
+The intended workflow is that a shape key should only be active for a single frame. To help with this, shape keys are named when they are added, according to the current frame. There are also some buttons above the list:
+- Zero All Shape Keys: Operator to set all shape key values to 0.0. This does not insert a keyframe!
+- Keyframe All Shape Keys: Operator to inserts a keyframe for all shape keys on the current frame with their current value.
+- Update Active Shape key: Toggle to automatically change the active shape key based on the current frame.
+
+
+### Deletion
+Similar to Tweak Lattice, never ever delete a lattice setup the usual way by simply pressing the X or Del keys, as this will leave behind a huge mess that Blender won't be happy about. Instead use the various ways of deletion in the addon's own UI: The "Delete Lattice" button, or the "-" (minus) button in the top list.
+
+Note: If you want to delete a lattice, make sure to do it through the addon's UI, which is in the sidebar. This will make sure to delete all modifiers, drivers and animation datablocks that were created along with the lattice.
+
+### TODO
+Some things not implemented yet:
+- Automatically inserting new shape key in the correct place in the list. Eg., when Frame 1 and Frame 10 already exist, creating a shape key on Frame 5 should insert it in between them.
+- Adding or removing objects to the influence of the lattice is not currently possible.