Merge pull request #226 from sbs20/staging

Documentation / language / batch modes and cancel

README.md

@@ -50,58 +50,14 @@ Copyright 2016-2021 [Sam Strachan](https://github.com/sbs20)
 
 * [Manual installation](docs/install.md)
 * [Docker installation](docs/docker.md)
+* [Scanner and SANE setup](docs/sane.md)
 * [Development notes](docs/development.md)
-* [Configuring the scanner and SANE](docs/sane.md)
 
 ## Configuration and device override
 
-If you want to override some specific configuration setting then you can do so
-within `./config/config.local.js`. Take a copy of `./config/config.default.js`
-and override the sections you want. Using docker you will need to map the volume
-using `-v /my/local/path:/app/config` then create a file in your directory
-called `config.local.js`. See [example source](./server/config/config.local.js)
-for more options.
-
-```javascript
-module.exports = {
-  /**
-   * @param {Configuration} config 
-   */
-  afterConfig(config) {
-    // Set default preview resolution
-    config.previewResolution = 150;
-
-    // Add a custom print pipeline
-    config.pipelines.push({
-      extension: 'pdf',
-      description: 'Print PDF',
-      commands: [
-        'convert @- -quality 92 tmp-%04d.jpg && ls tmp-*.jpg',
-        'convert @- scan-0000.pdf',
-        'lp -d MY_PRINTER scan-0000.pdf',
-        'ls scan-*.*'
-      ]
-    });
-  },
-
-  /**
-   * @param {ScanDevice[]} devices 
-   */
-  afterDevices(devices) {
-    // Override the defaults for plustek scanners
-    const device = devices.filter(d => d.id.startsWith('plustek'))[0];
-    if (device) {
-      device.features['--mode'].default = 'Color';
-      device.features['--resolution'].default = 150;
-      device.features['--resolution'].options = [75, 150, 300, 600];
-      device.features['--brightness'].default = 0;
-      device.features['--contrast'].default = 5;
-      device.features['-x'].default = 215;
-      device.features['-y'].default = 297;
-    }
-  }
-};
-```
+If you want to override some specific configuration settings then you can do so
+within `./config/config.local.js`. See [Configuration](docs/config.md) for more
+detail.
 
 ## Why?
 

docs/config.md

@@ -0,0 +1,165 @@
+# Configuration overrides
+
+Sometimes scanners don't return quite what you want them to. Likewise, perhaps
+scanservjs doesn't provide the defaults you want. Furtunately it's possible to
+override most things you might want to.
+
+The two things you can modify are:
+* `config`: These are the global settings which include things like:
+  * Server port
+  * Log level
+  * Preview resolution
+  * Output filename
+  * Pipelines (output format)
+* `devices`: The device definitions which are reported by SANE which include
+  scanner dimensions and geometry, modes, resolutions and sources.
+
+TL;DR; copy `./config/config.default.js` to `config/config.local.js` and
+override the sections you want.
+
+If you are using docker, then you will want to map the configuration directory
+e.g. `-v /my/local/path:/app/config`.
+
+## How it works
+
+scanservjs looks for a file called `config/config.local.js` and attempts to call
+two functions at different stages in the processing:
+* `afterConfig(config)`: whenever a config is read, the result is passed to this
+  function before being either used or sent down tot he browser.
+* `afterDevices(devices)`: whenever the devices are read, the result is passed
+  to this function before being used.
+* See [example source](../server/config/config.default.js) for more options.
+
+## Example file
+
+```javascript
+module.exports = {
+  /**
+   * @param {Configuration} config 
+   */
+  afterConfig(config) {
+    // Set default preview resolution
+    config.previewResolution = 150;
+
+    // Add a custom print pipeline
+    config.pipelines.push({
+      extension: 'pdf',
+      description: 'Print PDF',
+      commands: [
+        'convert @- -quality 92 tmp-%04d.jpg && ls tmp-*.jpg',
+        'convert @- scan-0000.pdf',
+        'lp -d MY_PRINTER scan-0000.pdf',
+        'ls scan-*.*'
+      ]
+    });
+  },
+
+  /**
+   * @param {ScanDevice[]} devices 
+   */
+  afterDevices(devices) {
+    // Override the defaults for plustek scanners
+    const device = devices.filter(d => d.id.startsWith('plustek'))[0];
+    if (device) {
+      device.features['--mode'].default = 'Color';
+      device.features['--resolution'].default = 150;
+      device.features['--resolution'].options = [75, 150, 300, 600];
+      device.features['--brightness'].default = 0;
+      device.features['--contrast'].default = 5;
+      device.features['-x'].default = 215;
+      device.features['-y'].default = 297;
+    }
+  }
+};
+```
+
+## Recipes
+
+### Override default width, height and resolution
+
+You have an old Canon flatbed but it returns daft default values for width and
+height. You also want to change the default resolution and limit the resolution
+options.
+
+```javascript
+  /**
+   * @param {ScanDevice[]} devices 
+   */
+  afterDevices(devices) {
+    // Override the defaults for plustek scanners
+    const device = devices.filter(d => d.id.startsWith('plustek'))[0];
+    if (device) {
+      device.features['--resolution'].default = 150;
+      device.features['--resolution'].options = [75, 150, 300, 600];
+      device.features['-x'].default = 215;
+      device.features['-y'].default = 297;
+    }
+  }
+```
+
+### Override scanner dimensions
+
+Some scanners (I'm looking at you, Brother) report their dimensions
+[incorrectly](https://github.com/sbs20/scanservjs/issues/103). This throws off
+the cropping logic because scanservjs incorrectly trusts the SANE output.
+
+```javascript
+  afterDevices(devices) {
+    const device = devices.filter(d => d.id.includes('brother'))[0];
+    if (device) {
+      device.features['-l'].limits = [0, 215];
+      device.features['-t'].limits = [0, 297];
+      device.features['-x'].default = 215;
+      device.features['-x'].limits = [0, 215];
+      device.features['-y'].default = 297;
+      device.features['-y'].limits = [0, 297];
+    }
+  }
+```
+
+### Insert your own pipelines
+
+You may wish to add your own custom pipelines. Pipelines are arrays of shell
+commands which run after scans. To learn more read the
+[example source](../server/config/config.default.js). This will insert your own
+pipelines at the top of the list.
+
+```javascript
+  afterConfig(config) {
+    const pipelines = [
+      {
+        extension: 'jpg',
+        description: 'TEST PIPELINE | Terrible quality',
+        commands: [
+          'convert @- -quality 20 scan-%04d.jpg',
+          'ls scan-*.*'
+        ]
+      },
+      {
+        extension: 'jpg',
+        description: 'TEST PIPELINE 2 | Silly quality',
+        commands: [
+          'convert @- -quality 99 scan-%04d.jpg',
+          'ls scan-*.*'
+        ]
+      }
+    ];
+
+    config.pipelines.splice(0, 0, ...pipelines);
+  },
+```
+
+### Change the log level and default scan filename
+
+```javascript
+const dayjs = require('dayjs');
+module.exports = {
+  afterConfig(config) {
+    config.filename = () => {
+      return `my_filestem_${dayjs().format('DD-MM-YYYY HH-mm-ss')}`;
+    };
+
+    config.log.level = 'DEBUG';
+  }
+}
+```

docs/docker.md

@@ -52,6 +52,10 @@ Depending on your setup you have a number of options.
   * Both translate to `/dev/bus/usb/001/003`.
   * The docker argument would be
     `--device=/dev/bus/usb/001/003:/dev/bus/usb/001/003`
+  * You may also need to adjust permissions on the USB port of the host e.g.
+    `chmod a+rw dev/bus/usb/001/003` - see
+    [this](https://github.com/sbs20/scanservjs/issues/221#issuecomment-828757430)
+    helpful answer for more.
 
 * If your scanner is driverless over the network, then
   [sane-airscan](https://github.com/alexpevzner/sane-airscan) should be able to

server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scanservjs-server",
-  "version": "2.11.0",
+  "version": "2.11.1",
   "description": "scanservjs is a simple web-based UI for SANE which allows you to share a scanner on a network without the need for drivers or complicated installation. scanserv does not do image conversion or manipulation (beyond the bare minimum necessary for the purposes of browser preview) or OCR.",
   "scripts": {
     "serve": "nodemon --exec 'vue-cli-service serve'",

server/src/config.js

@@ -1,5 +1,6 @@
 const dayjs = require('dayjs');
 const userOptions = require('./user-options');
+const Constants = require('./constants');
 const Package = require('../package.json');
 let instance = null;
 
@@ -54,6 +55,13 @@ class Config {
         ]
       },
 
+      batchModes: [
+        Constants.BATCH_NONE,
+        Constants.BATCH_MANUAL,
+        Constants.BATCH_AUTO,
+        Constants.BATCH_COLLATE_STANDARD
+      ],
+
       filters: [
         {
           description: 'filter.auto-level',

server/src/context.js

@@ -30,6 +30,9 @@ class Context {
 
     /** @type {PaperSize[]} */
     this.paperSizes = Config.paperSizes;
+
+    /** @type {string[]} */
+    this.batchModes = Config.batchModes;
   }
 
   /**

server/src/types.js

@@ -71,6 +71,7 @@
  * @property {Filter[]} filters
  * @property {Pipeline[]} pipelines
  * @property {PaperSize[]} paperSizes
+ * @property {string[]} batchModes
  */
 
 /**

webui/src/components/BatchDialog.vue

@@ -6,6 +6,7 @@
       </v-card-title>
       <v-card-text>
         <v-spacer></v-spacer>
+        <v-btn text @click.prevent="show = false">{{ $t('batch-dialog.btn-cancel') }}</v-btn>
         <v-btn v-if="onFinish" color="green" text @click.prevent="finish">{{ $t('batch-dialog.btn-finish') }}</v-btn>
         <v-btn v-if="onRescan" color="warning" text @click.prevent="rescan">{{ $t('batch-dialog.btn-rescan') }}</v-btn>
         <v-btn color="primary" text @click.prevent="next">{{ $t('batch-dialog.btn-next') }}</v-btn>

webui/src/components/Scan.vue

@@ -23,19 +23,12 @@
         <v-select v-if="'--disable-dynamic-lineart' in device.features"
           :label="$t('scan.dynamic-lineart')" v-model="request.params.mode"
           :items="[
-            { key: false, value: $t('scan.dynamic-lineart:disabled') },
-            { key: true, value: $t('scan.dynamic-lineart:enabled') }]"
-          item-value="key" item-text="value"></v-select>
+            { value: false, text: $t('scan.dynamic-lineart:disabled') },
+            { value: true, text: $t('scan.dynamic-lineart:enabled') }]"
+          item-value="value" item-text="text"></v-select>
 
         <v-select :label="$t('scan.batch')" v-model="request.batch"
-          :items="[
-            { key: 'none', value: $t('scan.batch:none') },
-            { key: 'manual', value: $t('scan.batch:manual') },
-            { key: 'auto', value: $t('scan.batch:auto') },
-            { key: 'auto-collate-standard', value: $t('scan.batch:auto-collate-standard') },
-            { key: 'auto-collate-reverse', value: $t('scan.batch:auto-collate-reverse') }
-          ]"
-          item-value="key" item-text="value"></v-select>
+          :items="batchModes" item-value="value" item-text="text"></v-select>
 
         <v-select
           v-model="request.filters"
@@ -155,6 +148,7 @@ export default {
         devices: [
           device
         ],
+        batchModes: [],
         filters: [],
         pipelines: [],
         paperSizes: [],
@@ -190,6 +184,17 @@ export default {
       };
     },
 
+    batchModes() {
+      return this.context.batchModes.map(mode => {
+        const key = `batch-mode.${sanitiseLocaleKey(mode)}`;
+        let translation = this.$t(key);
+        return {
+          text: translation === key ? mode : translation,
+          value: mode
+        };
+      });
+    },
+
     filters() {
       return this.context.filters.map(f => {
         return {
@@ -400,7 +405,7 @@ export default {
       // The cropper changes even when coordinates are set manually. This will
       // result in manually set values being overwritten because of rounding.
       // If someone is taking the trouble to set values manually then they
-      // should be preserved. We should only update the values if they breaach
+      // should be preserved. We should only update the values if they breach
       // a threshold or the scanner dimensions
       const scanner = this.deviceSize;
       const params = this.request.params;