Add scripts example.

Documentation.docc/8.Scripts.md

@@ -0,0 +1,81 @@
+# Scripts
+
+Scripts enhance the Draw Things experience by allowing users to create and run custom JavaScript snippets. The API is designed to be stable; scripts can specify an API version to ensure compatibility with future updates.
+
+## API Versioning
+
+Scripts should specify their API version to guarantee the proper API toolchain is used, even if API changes occur in future updates.
+
+## Available Global Objects
+
+Draw Things scripts provide access to three main global objects: `canvas`, `pipeline`, and `filesystem`.
+
+### `canvas`
+
+Manipulates the Draw Things interface's infinite canvas. The available methods include:
+
+- **`canvas.boundingBox`**: Returns the bounding box of images collectively on the canvas.
+- **`canvas.clear()`**: Removes all images, similar to tapping the "New Canvas" button.
+- **`canvas.createMask(width, height, value)`**: Creates a mask of specified size and value.
+- **`canvas.currentMask`**: Returns the current mask viewable on the canvas.
+- **`canvas.foregroundMask`** and **`canvas.backgroundMask`**: Return masks corresponding to the foreground and background, respectively, using built-in segmentation models.
+- **`canvas.loadImage(file)`**: Loads an image from a file.
+- **`canvas.loadImageSrc(src)`**: Loads an image from an src content string, similar to an HTML `<img>` tag.
+- **`canvas.moveCanvas(left, top)`** and **`canvas.moveCanvas(rect)`**: Move and zoom the canvas.
+- **`canvas.saveImage(file, visibleRegionOnly)`** and **`canvas.saveImageSrc(visibleRegionOnly)`**: Save the current canvas image to a file or src string.
+- **`canvas.canvasZoom`** and **`canvas.topLeftCorner`**: Control and report the canvas's zoom scale and top-left corner coordinates.
+- **`canvas.updateCanvasSize(configuration)`**: Adjusts the canvas size based on a configuration object.
+- **`canvas.loadMaskFromPhotos()`, `canvas.loadMaskFromFiles()`, `canvas.loadMaskFromSrc(srcContent)`**: Load masks from various sources.
+- **`canvas.detectFaces()`**: Detects and returns face positions within the canvas.
+
+### `pipeline`
+
+Manages the image generation pipeline with methods like:
+
+- **`pipeline.configuration`**: Extracts the current configuration.
+- **`pipeline.findControlByName(name)`** and **`pipeline.findLoRAByName(name)`**: Find specific controls or LoRAs by name.
+- **`pipeline.downloadBuiltins(names)`**: Downloads built-in models and components.
+- **`pipeline.prompts`**: Returns the current prompts on the screen.
+- **`pipeline.run(options)`**: Runs the image generation pipeline with optional prompts and masks.
+
+### `filesystem`
+
+Provides access to the file system, within sandbox limitations:
+
+- **`filesystem.pictures.path`**: Retrieves the path of the pictures directory.
+- **`filesystem.pictures.readEntries`** and **`filesystem.readEntries(directory)`**: Enumerate files in specific directories.
+
+### `requestFromUser`
+
+Creates a user interface for input via script configuration. Usage:
+
+```javascript
+const config = requestFromUser("This is the title", "Next Button", function() {
+  return [
+  	 this.section("This is a section", "Some details of this section.", [
+  	   this.slider(0.5, this.slider.percent, 0, 1, "a slider"),
+  	   this.size(960, 1280, 128, 2048)
+    ]),
+    this.plainText("Some plain text."),
+    this.textField("", "This is a placeholder", true, 94),
+    this.imageField(),
+    this.directory(),
+    this.image("data:image/png;base64,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")
+  ];
+});
+```
+
+Supported widgets include sliders, text fields, image and directory pickers, switches, segmented controls, menus, sections with details, plain text displays, and image displays. This function is blocking; it waits for user input before returning an array of selected values.
+
+- **`this.slider(value, valueType, minValue, maxValue, title)`**: a single slider. valueType can be `this.slider.percent`, `this.slider.fractional(k)` or `this.slider.scale`.
+- **`this.textField(value, placeholder, multiline, height)`**: a free-form text field for user input.
+- **`this.imageField(title, multiSelect)`**: a image picker.
+- **`this.directory()`**: a directory picker.
+- **`this.switch(isOn, title)`**: a on / off switch.
+- **`this.segmented(index, options)`**: a segmented control. options should be a list of strings.
+- **`this.menu(index, options)`**: a menu. options should be a list of strings.
+- **`this.section(title, detail, views)`**: a title + detail wrapper. views should be an array of these widgets again.
+- **`this.plainText(value)`**: show a text display.
+- **`this.image(src, height, selectable)`**: show a image display. src can be a string or an array of strings. Later is when selectable is true.
+
+This comprehensive API suite allows developers to create powerful custom functionalities within the Draw Things environment.