
WELCOME 
Thanks for using the Whiskers Projection Mapping App.

Whiskers is a little different because you load assets and create content in the code.
We have set it up for you to be easy to do with the ZIM JavaScript Canvas Framework.
This gives the advantage of making content with the ZIM - see https://zimjs.com

In general, you put your videos and pictures in the assets folder.
You can also make ZIM content like animated shapes, emitters and much more.
You pass assets and content to a Perspective() to give it perspective and masking handles.
You pass the perspectives the ProjectionMap() to add them to the screen and control panel.

Then you can position, warp, custom crop, feather, and apply blend modes.
Perspectives can have their layers changed, be locked or hidden.
Changes are saved automatically, can be exported and imported.
And then a presentation mode can be set and toggled with the P key.
Crosshairs can be toggled with the C key.

// See Whisker vids on YouTube:
// Whiskers Intro: https://www.youtube.com/watch?v=EFwc1lecjTA
// Whiskers Details: https://www.youtube.com/watch?v=irP78OWedSA
// Whiskers ZIM: https://www.youtube.com/watch?v=ol_xBi3MCQI

INSTRUCTIONS

	1. RUNNING 
	2. LOCAL LOADING
	3. PANEL
	4. PRESENTATION + KEYS
	5. PROJECTS
	6. ASSETS
	7. CONTENT
	8. LOADING A PIC
	9. ZIM CONTENT
	10. PERSPECTIVES
	11. ID + RESTARTING
	12. PROJECTION MAP

1. RUNNING 
Unzip the whiskers zip file - which has an index.html, scripts and assets.
Generally, we want to open the index.html page in a browser like Chrome.
But, Whiskers will probably be loading local files like videos and pictures.
Loading local files onto the HTML Canvas causes security errors - so do either below:

A. Run the index.html page on a local server 
	The most common, free and easy (2 minutes) is to use the VS Code editor by Microsoft 
	Go to VS Code, download it and open it.  VS Code is great to code in too.
	Unzip the whiskers folder and drop the whiskers folder onto the VS Code icon 
	Or in VS Code choose File > Open Folder and select the whiskers folder
	On the left menu select Extensions (boxes) and search and install LiveServer
	Right click on the index.html page and choose Open with Live Server
	(Python can also set up a live server - just search it)

B. Or in a Chrome browser shortcut right click to properties 
	In the target field, after ...exe" add a space then --allow-file-access-from-files
	Close all Chrome browsers and open Chrome from short cut 
	Unzip the whiskers folder, find the whiskers/index.html and drop it on Chrome
	Just remember that any time you want to run whiskers,
	start the first Chrome you open from the modified shortcut.
	There are similar ways for Safari, Edge, Firefox, etc.


2. LOCAL LOADING
To run completely local without internet uncomment these two lines

import "./scripts/zim.js";
import {ProjectionMap} from "./scripts/whiskers.js";

And comment out the web imports below them

// import "https://zimjs.org/cdn/020/zim";
// import {ProjectionMap, makeApp} from "https://zimjs.com/whiskers/scripts/whiskers";


3. PANEL 
There is an interface panel that can be dragged and collapsed. 
Pressing a perspective on the screen will set it as the perspective in the panel 
If the perspective is locked or hidden, then you can get to it again with the top arrows
And you can use those at any time to change perspectives 
Setting CROP will crop non-warped content at the bounds of the perspective 
This acts like a passthrough and you can scale, rotate, and shift the content with the sliders 
Checking and selecting MASK will let you adjust a bezier mask with many features 
The mask is made from a standard ZIM Blob (there is also a similar Squiggle in ZIM)
	Each point has Bezier controls - drag the point or move its square handles
	You can add a point by pressing on the edge of the blob (CTRL Z undo)
	Remove a point by pressing and holding or SHIFT clicking (CTRL Z undo)
	Select the point (or CTRL select for multiple) or handles 
	and use key arrows to move a pixel (or SHIFT key arrows for 10 pixels)
	Double click the control to cycle through its bezier types:
		mirror - the control rectangles reflect one another about the point circle - lengths are kept even
		straight - the control rectangles keep a straight line through the point circle but length is independent
		free - the control rectangle moves independently from the other control rectangle
		none - there are no control rectangles (they are actually set at 0,0).  This makes a corner at the circle point.
		mirror - back to mirror, pull the purple handles sitting on the point
You can feather and set blend modes
And reset the perspective back to its creation parameter settings 
All changes to the perspectives will be saved automatically 
inside localStorage for the whiskers_yourID used in ProjectionMap(yourID)
You can also IMPORT data that comes from pressing the EXPORT button
to share with people or across computers 
The Whiskers logo brings up the splash screen - note the ICON with link to ZIM at bottom right


4. PRESENTATION + KEYS
Press the PRESENT button or the P key to hide the panel and controls 
Press ESC or the P key or DOUBLE CLICK to exit presentation mode 
Press the SPACE bar to fade everything to a black screen - press SPACE to fade back in
Press CTRL or ⌘ Z for undo and SHIFT CTRL or ⌘ Z for redo
Press C for crosshairs


5. PROJECTS
The tool has no GUI for different projects 
Instead, pick one of the options below for new projects

A. Duplicate Folder
	Duplicate the whiskers folder and call it rave_01
	inside the index.html change the id to "rave1"
	each project has its own folder and assets folder

B. Duplicate File
	Copy the index.html to rave_01.html 
	inside the rave_01.html change the id to "rave1"
	each project has its own file and shares the assets folder

	
6. ASSETS
The tool has no GUI for uploading videos and pictures
Instead, add them to the assets folder 
and add the file name to the Frame assets array ["whiskers.png", "vid.ext", "pic.ext", etc.] 
Then use a new Vid() or new Pic() - see examples below
Sprites and SVG are similar but use a Sprite() and SVG().


7. CONTENT
Content can be the assets like the vids, pics, sprites, emojis, and svg 
These get added to a perspectives object
Content can also be any ZIM object (see step 9 where we demonstrate ZIM)
Note: in the videos we made vid1 and then right under made per1 
you can certainly arrange your code that way too.


8. LOADING A PIC
Here we load a Pic 
For the example here, we just used the Whiskers logo, 
For your own images, you would need to put them in the assets/ folder 
and preload them in the Frame like: ["whiskers.png", "myImage.jpg", etc.] 
** also uncomment per4 for the Perspective and in the ProjectionMap()
Note: that it is a Pic and not a Vid and there are no extra parameters after the file name
const pic = new Pic("whiskers.png");


9. ZIM CONTENT 
In addition to Vid() and Pic(), you can also create ZIM objects
ZIM Shapes - Circle, Rectangle, Triangle, Poly, Blob, Squiggle, Line, and Container
components like Label, LabelLetters, LabelWords, LabelOnArc, LabelOnPath, Carousel
shaders - ZIM supports regular shaders and Shadertoy format shaders
controls (operate on multiple objects) like Tile, Beads, Pack, and Book
And appl animations and effects, such as:
animate any object's properties (on par with gSAP/Greensock)
shape animations and animating objects along paths (that can be animating)
wiggle objects, page through carousels, flip pages in books,
run particle emitters, sequence animations,
run physics simulations, animate effects like Pixel, Blur, Color, 
create sound frequency animations with SoundWave()
show live graphs, Ticker, Timeout, and Interval based animations
animate based on phsyical computing like Arduino 
animate based on gesturing at a web cam with integrated ML5 body tracking
	See https://zimjs.com for more on ZIM
	See https://zimjs.com/docs.html for all classes, methods, constants, and functions
	See https://zimjs.com/cheatsheet for a visual collection of objects (also see hamburger menus)
	See https://zimjs.com/art.html for examples of art made with ZIM


10. PERSPECTIVES
The content then gets added to a Perspective() object
which you will use one or more to project on a physical surface.
Perspectives have handles to morph the content, or with crop set, crop the content
The Perspectives have resolution, maskShape, feather settings
	resolution: 1.0 renders the texture at 1:1 pixel crispness 
		exact native image/video resolution
	resolution: 0.5 renders the texture at half dimensions 
		1/4 the total pixels and scales the raster up with bilinear filtering to fill the quad
		cuts the GPU fragment shader fill-rate workload by 75%
	resolution: 2.0 (or higher) renders at supersampled/Retina density
	The maskShape can be manually adjusted with the interface panel MASK button
	Use the maskShape to adjust the perspective to fit on your surface.
	A custom Blob can also be passed to the maskShape: new Blob({points:points}).sca(2)
	see https://zimjs.com/paths for points or use new Blob({points:SVGPath}) 
	see the Docs for info at https://zimjs.com/docs.html?item=Blob
		

11. ID + RESTARTING
change the id for each different project 
const id = "tutorial";

to start over again, uncomment this line below
remember to comment it again after restarting
localStorage.removeItem("whiskers_"+id);


12. PROJECTION MAP 
The ProjectionMap class has an id for your project 
Then an array that holds object literals with a perspective name and perspective object 
so new Perspective(id, [{name:"box", perspective:per1}, {name:"wall", perspective:per2}])
Each name shows up in the interface panel and the perspective shows up on the screen
the third parameter is defaultData in the format of the exported data.
the fourth parameter is to customize the crosshairs.
if you add the fourth parameter make sure there is the third parameter (if empty, put null)


Thanks for using Whiskers 
Get the most out of it by exploring ZIM at https://zimjs.com 
Donations appreciated https://zimjs.com/donate/ 
No donations if you are a student or don't have the means

Dr Abstract 
https://doctorabstract.com