{"id":19164697,"url":"https://github.com/publiclab/spectral-workbench.js","last_synced_at":"2025-04-15T06:56:14.398Z","repository":{"id":6884099,"uuid":"55530855","full_name":"publiclab/spectral-workbench.js","owner":"publiclab","description":"The JavaScript heart of Spectral Workbench; a Public Lab project to record, manipulate, and analyze spectrometric data.","archived":false,"fork":false,"pushed_at":"2023-02-27T09:59:28.000Z","size":8307,"stargazers_count":47,"open_issues_count":47,"forks_count":37,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-15T06:56:00.204Z","etag":null,"topics":["javascript","science","spectrometry"],"latest_commit_sha":null,"homepage":"https://spectralworkbench.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/publiclab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"Code_of_Conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-04-05T18:07:14.000Z","updated_at":"2025-04-01T01:52:06.000Z","dependencies_parsed_at":"2023-02-14T06:16:07.713Z","dependency_job_id":"5d3e5d4f-484d-4ba3-b7da-f802c7bfe8cc","html_url":"https://github.com/publiclab/spectral-workbench.js","commit_stats":{"total_commits":141,"total_committers":18,"mean_commits":7.833333333333333,"dds":0.4964539007092199,"last_synced_commit":"d5a9893ba762a3a6049ed6703d37f90eb750ed6f"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/publiclab%2Fspectral-workbench.js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/publiclab%2Fspectral-workbench.js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/publiclab%2Fspectral-workbench.js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/publiclab%2Fspectral-workbench.js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/publiclab","download_url":"https://codeload.github.com/publiclab/spectral-workbench.js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249023713,"owners_count":21199958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","science","spectrometry"],"created_at":"2024-11-09T09:23:34.213Z","updated_at":"2025-04-15T06:56:14.376Z","avatar_url":"https://github.com/publiclab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"spectral-workbench.js\n====\n\n[![Build Status](https://travis-ci.com/publiclab/spectral-workbench.js.svg?branch=master)](https://travis-ci.com/publiclab/spectral-workbench.js)\n[![npm](https://img.shields.io/npm/v/spectral-workbench.svg)](https://www.npmjs.com/package/spectral-workbench)\n[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/publiclab/spectral-workbench.js/)\n[![Join the chat at https://publiclab.org/chat](https://img.shields.io/badge/chat-in%20different%20ways-blue.svg)](https://publiclab.org/chat)\n[![Code of Conduct](https://img.shields.io/badge/code-of%20conduct-green.svg)](https://publiclab.org/conduct)\n\nThe JavaScript heart of Spectral Workbench; a Public Lab project to record, manipulate, and analyze spectrometric data. \n\nspectral-workbench.js is currently set up to run in a browser, but some parts may work headless, in a JavaScript console. We hope to further separate the views from the library logic so that headless or Node.js usage is easier.\n\nThis library is primarily used in the Spectral Workbench application, running at http://spectralworkbench.org, which is a Ruby on Rails project that is also [open source](https://github.com/publiclab/spectral-workbench). Read about how to build and use your own spectrometer with it here: http://publiclab.org/wiki/spectrometer\n\nSee static demo here: https://publiclab.github.io/spectral-workbench.js/examples/\n\nAnd static demo of capture interface: https://publiclab.github.io/spectral-workbench.js/examples/capture/\n\nTry a demo of the newly rewritten capture interface here: https://publiclab.github.io/spectral-workbench.js/examples/new-capture/\n\n****\n\n![screenshot](https://publiclab.org/i/42828.png)\n\n\n## Installation\n\n\n### In Node.js\n\nTo install spectral-workbench, run:\n\n    npm install spectral-workbench\n\nThe `SpectralWorkbench.Image` class uses the `node-canvas` package when run without a browser, so you'll need to install it by:\n\n* running (on Debian): `sudo apt-get install libcairo2-dev libjpeg8-dev libpango1.0-dev libgif-dev build-essential g++` See build instructions for [other platforms here](https://github.com/Automattic/node-canvas#installation).\n* running `npm install`\n\n### In a browser\n\nTo begin using spectral-workbench.js on a webpage, you'll need to include jQuery, and to use any HTML-based features (such as UI or graphing), you'll need to include its dependencies.\n\nFirst, run:\n\n    npm install\n\nthen:\n\n    bower install\n\nYour page should include:\n\n````html\n\u003cscript src=\"node_modules/jquery/dist/jquery.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"bower_components/d3/d3.js\" type=\"text/javascript\"\u003e\u003c/script\u003e                                                                              \n\u003cscript src=\"bower_components/nvd3/build/nv.d3.js\" type=\"text/javascript\"\u003e\u003c/script\u003e                                                                              \n\u003cscript src=\"bower_components/bootstrap-css/js/bootstrap.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"bower_components/moment/moment.js\"\u003e\u003c/script\u003e\n\u003clink href=\"bower_components/nvd3/build/nv.d3.css\" rel=\"stylesheet\"\u003e\n````\n\nThen include the library itself: \n \n````html\n\u003cscript src=\"dist/spectral-workbench.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n````\n\nTo see graphed output, you'll need a `\u003cdiv\u003e` with the `id` \"graph\", like so:\n\n````html\n\u003cdiv id=\"graph\"\u003e\u003c/div\u003e\n````\n\nA spectrum may be displayed in a [d3-based](http://d3js.org) graph with the Graph constructor: \n\n````js\n\njQuery(document).ready(function($) {\n  graph = new SpectralWorkbench.Graph({\n    spectrum_id: 1, // unique id \u003cint\u003e, typically a database primary key\n    selector: '#graph' // defaults to \"#graph\" using jQuery selector syntax\n  });\n});\n\n````\n\n****\n\n## Usage\n\n### Running\n\nIf you're using this locally, the best way to run it locally is to use the `http-server` npm module. Install it with:\n\n`npm install -g http-server`\n\nthen run the app with:\n\n`http-server` \n\nand it will open at the address: http://localhost:8080/\n\n\n### Inputting data\n\nYou can pass a nested array of `[wavelength, intensity]` data to the Spectrum constructor like this:\n\n````js\n\nvar data = [\n  [0, 24],\n  [1, 44],\n  [2, 42],\n  [3, 45],\n  [4, 20]\n];\n\nvar spectrum = new SpectralWorkbench.Spectrum(data);\n\nspectrum.getJSON();\n\n/*\n\n// Output:\n\n[ { average: 22.95, r: 22.95, g: 22.95, b: 22.95, pixel: 0 },\n  { average: 43.35, r: 43.35, g: 43.35, b: 43.35, pixel: 1 },\n  { average: 40.8,  r: 40.8,  g: 40.8,  b: 40.8,  pixel: 2 },\n  { average: 43.35, r: 43.35, g: 43.35, b: 43.35, pixel: 3 },\n  { average: 17.85, r: 17.85, g: 17.85, b: 17.85, pixel: 4 } ]\n\n*/\n\n// this is non-ideal, but will be expanded upon with a better calibrate API:\nspectrum.json.data.lines = spectrum.calibrate(400, 500, 0, 4);\nspectrum.load(); // calibrate does not save\n\nspectrum.getJSON();\n\n/*\n\n// Output:\n\n[ { average: 22.95, r: 22.95, g: 22.95, b: 22.95, wavelength: 400 },\n  { average: 43.35, r: 43.35, g: 43.35, b: 43.35, wavelength: 425 },\n  { average: 40.8,  r: 40.8,  g: 40.8,  b: 40.8,  wavelength: 450 },\n  { average: 43.35, r: 43.35, g: 43.35, b: 43.35, wavelength: 475 },\n  { average: 17.85, r: 17.85, g: 17.85, b: 17.85, wavelength: 500 } ]\n\n*/\n\n````\n\nThis assumes monochrome input with units `[nanometers, 0-255]`, although if you're using a [Public Lab webcam-based spectrometer](https://publiclab.org/wiki/spectrometer), you'll be dealing with RGB data. \n\nFor a working example of an array-based spectrum see: https://publiclab.github.io/spectral-workbench.js/examples/array.html\n\nYou can also use a string of comma-separated values (a CSV), where each line is `wavelength,intensity` (similarly to the array format above):\n\n````js\n\n// \\n instead of linebreaks here: \nvar string = \"400,24\\n410,44\\n420,42\\n430,45\\n440,20\";\n\nvar spectrum = new SpectralWorkbench.Spectrum(string);\n\n````\n\nTSVs (tab-separated values) are also supported as of v0.0.10.\n\nMost tests continue to use a legacy data format (that used by the SpectralWorkbench.org service) which we'd like to simplify, but for now, you can create a Spectrum object from JSON data in the following format, that does accept RGB pixel data:\n\n````js\n\nvar data = {\n  \"data\": { \n    \"name\": \"Test spectrum\",\n    \"lines\":[ // as many data points as you like may be entered here:\n      { \"average\":64.3333, \"r\":69, \"g\":46, \"b\":78, \"wavelength\":269.089 },\n      { \"average\":31,      \"r\":33, \"g\":19, \"b\":41, \"wavelength\":958.521 }\n    ]\n  }\n}\n\nvar spectrum = new SpectralWorkbench.Spectrum(data);\n\n````\n\nFor a working example, see: https://publiclab.github.io/spectral-workbench.js/examples/\n\n\n### In Node.js\n\nAn example node script is available in the `/examples/` directory, and some command line utilities are available in the `/scripts/` directory, including ones to upload from JSON files to https://spectralworkbench.org and to extract JSON from images. For example, you could extract data from an image with:\n\n    scripts/image-extract.js --file spec/javascripts/fixtures/test-spectrum-9.png --format json \u003e test.json\n\nThen upload the JSON data with (replacing XXXX with your API key):\n\n    scripts/upload.js --file test.json --token XXXXXXXXXXXXXX\n\nTo write a script in Node.js, you could create and run a file like this:\n\n````js\n\n#!/usr/bin/env node\n\nvar SpectralWorkbench = require('spectral-workbench').SpectralWorkbench;\n\nvar data = {\n  \"data\": { \n    \"name\": \"Test spectrum\",\n    \"lines\":[ // as many data points as you like may be entered here:\n      {\"average\":64.3333,\"r\":69,\"g\":46,\"b\":78,\"wavelength\":269.089},\n      {\"average\":63.3333,\"r\":71,\"g\":45,\"b\":74,\"wavelength\":277.718},\n      {\"average\":64,\"r\":71,\"g\":47,\"b\":74,\"wavelength\":291.524},\n      {\"average\":64,\"r\":68,\"g\":49,\"b\":75,\"wavelength\":303.604}\n    ]\n  }\n}\n\nvar spectrum = new SpectralWorkbench.Spectrum(data);\n\nconsole.log(spectrum.getIntensity(282));\n\n````\n\nAnd run it with `node yourscript.js`. If you make a useful one, submit a pull request and I'll pull it in!\n\n```js\n\nspectrum.upload(\n  'https://spectralworkbench.org/spectrums.json', \n  function callback(err, httpResponse, body) { console.log(body) }, \n  { token: \"31343338303237303934\" }\n);\n\n```\nNote that this direct upload feature is experimental. \n\n\n### Manipulating spectrum data\n\nOnce you've initialized a Spectrum, you can add Operations to it using the following syntax:\n\n````js\n\nvar spectrum = new SpectralWorkbench.Spectrum(data);\n\nspectrum.addAndParseTag('smooth:3');\n\n````\n\nOperations are a type of tag that are passed as strings in `operation:value` format, and there are a variety of operations available, including:\n\n* `smooth`\n* `subtract`\n* `transform`\n* `crossSection` (requires an image)\n* plus several more\n\nRead more at https://publiclab.org/wiki/spectral-workbench-operations\n\n****\n\nAn in-progress project to port the HTML capture interface to this library can be tested at:\n\nhttps://publiclab.github.io/spectral-workbench.js/examples/capture/\n\nFollow progress at https://github.com/publiclab/spectral-workbench.js/issues/56\n\n****\n\n\n## Contributing\n\nWe welcome community contributions to spectral-workbench.js! Learn more about contributing to Spectral Workbench or other Public Lab code projects on this page: http://publiclab.org/wiki/developers\n\n\n## Bug reports \u0026 troubleshooting\n\nIf you are submitting a bug, please include:\n\n* where/when you see the issue, so we can try to reproduce it\n* any relevant JavaScript console output\n* your browser (and version if possible!)\n* anything you can about the sequence of events which led to the bug \n\nThank you for your help!\n\n\n## Automated tests\n\n\nTo run Jasmine tests, open `test.html` in a browser. You can also run them on our Github Pages-hosted suite here: http://publiclab.github.io/spectral-workbench.js/test.\n\nAlternatively, if you have phantomjs installed, run: `grunt jasmine` to run tests from the command line.\n\n\n## Building\n\nspectral-workbench.js is built using a Grunt task from the source files in `/src/`, and the compiled file is saved to `/dist/spectral-workbench.js`. To build, run `grunt build`. To watch files for changes, and build whenever they occur, run `grunt`. You'll need the Grunt CLI -- `npm install -g grunt-cli`. \n\n\n****\n\nCopyright 2011-2015 Public Lab\npubliclab.org | spectralworkbench.org\n\n## License\n\nspectral-workbench.js is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nSpectral Workbench is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with Spectral Workbench.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpubliclab%2Fspectral-workbench.js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpubliclab%2Fspectral-workbench.js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpubliclab%2Fspectral-workbench.js/lists"}