{"id":22859959,"url":"https://github.com/reelyactive/cuttlefish","last_synced_at":"2025-08-11T09:31:42.287Z","repository":{"id":57178245,"uuid":"49687651","full_name":"reelyactive/cuttlefish","owner":"reelyactive","description":"Client-side utility for human-friendly HTML rendering of machine-friendly ambient data.  We believe in an open Internet of Things.","archived":false,"fork":false,"pushed_at":"2024-10-07T21:41:31.000Z","size":5045,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-03T21:15:39.808Z","etag":null,"topics":["client-side","digital-twins","dynamb","json-ld","pareto-anywhere","schema-org","semantic-web","statid","visualization"],"latest_commit_sha":null,"homepage":"https://reelyactive.github.io/cuttlefish/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reelyactive.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-15T01:42:20.000Z","updated_at":"2024-10-07T21:41:35.000Z","dependencies_parsed_at":"2023-10-12T01:08:00.652Z","dependency_job_id":"7770637d-49b5-4175-bde7-f82942dc9155","html_url":"https://github.com/reelyactive/cuttlefish","commit_stats":{"total_commits":89,"total_committers":2,"mean_commits":44.5,"dds":"0.011235955056179803","last_synced_commit":"1c9448e38a921b6328c7596edddc25629a85669d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fcuttlefish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fcuttlefish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fcuttlefish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fcuttlefish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reelyactive","download_url":"https://codeload.github.com/reelyactive/cuttlefish/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229517375,"owners_count":18085490,"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":["client-side","digital-twins","dynamb","json-ld","pareto-anywhere","schema-org","semantic-web","statid","visualization"],"created_at":"2024-12-13T09:08:31.990Z","updated_at":"2025-08-11T09:31:42.276Z","avatar_url":"https://github.com/reelyactive.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"cuttlefish\n==========\n\n__cuttlefish__ facilitates human-friendly HTML rendering of machine-friendly:\n- JSON-LD \u0026 Schema.org (\"story\" data)\n- [dynamb](https://reelyactive.github.io/diy/cheatsheet/#dynamb) (dynamic ambient data)\n- [spatem](https://reelyactive.github.io/diy/cheatsheet/#spatem) (spatial-temporal data)\n- statid (static identifier data)\n\n![Overview of cuttlefish.js](https://reelyactive.github.io/cuttlefish/images/overview.png)\n\n__cuttlefish__ is lightweight client-side JavaScript that runs in the browser.  See a live demo using the code in this repository at: [reelyactive.github.io/cuttlefish](https://reelyactive.github.io/cuttlefish)\n\n\nHello cuttlefish!\n-----------------\n\nInclude in an _index.html_ file the required __cuttlefish-x__ scripts, the Font Awesome 5 icon set, and divs in which each can render the data:\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv id=\"storyToRender\"\u003e\u003c/div\u003e\n    \u003cdiv id=\"dynambToRender\"\u003e\u003c/div\u003e\n    \u003cdiv id=\"spatemToRender\"\u003e\u003c/div\u003e\n    \u003cdiv id=\"statidToRender\"\u003e\u003c/div\u003e\n\n    \u003cscript defer src=\"js/fontawesome-reelyactive.min.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"js/cuttlefish-story.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"js/cuttlefish-dynamb.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"js/cuttlefish-spatem.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"js/cuttlefish-statid.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"js/app.js\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nInclude in a _js/app.js_ the code to render the given story, dynamb, spatem and/or statid data in the _xToRender_ divs:\n\n```javascript\nlet story = { /* Likely retrieved by cormorant.js */ };\nlet storyTarget = document.querySelector('#storyToRender');\nlet storyOptions = {};\n\ncuttlefishStory.render(story, storyTarget, storyOptions);\n\nlet dynamb = { /* Likely consumed from Pareto Anywhere */ };\nlet dynambTarget = document.querySelector('#dynambToRender');\nlet dynambOptions = {};\n\ncuttlefishDynamb.render(dynamb, dynambTarget, dynambOptions);\n\nlet spatem = { /* Likely consumed from Pareto Anywhere */ };\nlet spatemTarget = document.querySelector('#spatemToRender');\nlet spatemOptions = {};\n\ncuttlefishSpatem.render(spatem, spatemTarget, spatemOptions);\n\nlet statid = { /* Likely consumed from Pareto Anywhere */ };\nlet statidTarget = document.querySelector('#statidToRender');\nlet statidOptions = {};\n\ncuttlefishStatid.render(statid, statidTarget, statidOptions);\n```\n\nOpen the _index.html_ file in a web browser to see the story, dynamb, spatem and/or statid data rendered in a human-readable way.\n\n\nSupported functions\n-------------------\n\n### cuttlefish-story.js\n\n`cuttlefishStory.render(story, target, options);`\n\n`cuttlefishStory.determineImageUrl(story);`\n\n`cuttlefishStory.determineTitle(story);`\n\n### cuttlefish-dynamb.js\n\n`cuttlefishDynamb.render(dynamb, target, options);`\n\n`cuttlefishDynamb.renderIcon(property, target, options);`\n\n`cuttlefishDynamb.renderValue(property, data, target, options);`\n\n### cuttlefish-spatem.js\n\n`cuttlefishSpatem.render(statid, target, options);`\n\n### cuttlefish-statid.js\n\n`cuttlefishStatid.render(statid, target, options);`\n\n### cuttlefish-tables.js\n\nProvides a __ContinuousDataTable__ class which updates automatically once instantiated:\n\n```html\n\u003ctable id=\"continuousData\"\u003e\u003c/table\u003e\n```\n\n```javascript\nlet elementId = document.querySelector('#continuousData');\nlet devices = beaver.devices; // See beaver.js\nlet options = { updateMilliseconds: 15000,\n                numberOfSamples: 4,\n                propertiesToDisplay: [ 'temperature', 'relativeHumidity',\n                                       'illuminance', 'batteryPercentage' ]\n};\n\nlet continuousDataTable = new ContinuousDataTable(elementId, devices, options);\n```\n\nProvides a __DiscreteDataTable__ class which takes dynamb events via its _handleDynamb()_ function, and updates automatically once instantiated:\n\n```html\n\u003ctable id=\"discreteData\"\u003e\u003c/table\u003e\n```\n\n```javascript\nlet elementId = document.querySelector('#discreteData');\nlet options = { updateMilliseconds: 5000,\n                maxRows: 8,\n                isClockDisplayed: false,\n                digitalTwins: cormorant.digitalTwins, // See cormorant.js\n                propertiesToDisplay: [ 'isButtonPressed', 'isContactDetected',\n                                       'isMotionDetected', 'unicodeCodePoints' ]\n};\n\nlet discreteDataTable = new DiscreteDataTable(elementId, options);\n\n// See beaver.js\nbeaver.on('dynamb', (dynamb) =\u003e { discreteDataTable.handleDynamb(dynamb); });\n\n// To update the device name after fetching a digital twin with cormorant.js:\ndiscreteDataTable.updateDigitalTwin(deviceSignature, digitalTwin);\n```\n\nProvides a __DevicesTable__ class which displays devices filtered from an optional beaver instance, and/or inserted/removed via its _insertDevice()_ and _removeDevice()_ functions, and updates automatically once instantiated:\n\n```html\n\u003ctable id=\"devicesTable\"\u003e\u003c/table\u003e\n```\n\n```javascript\nlet elementId = document.querySelector('#devicesTable');\nlet options = { beaver: beaver, // See beaver.js\n                maxRows: 12,\n                isClockDisplayed: false,\n                digitalTwins: cormorant.digitalTwins, // See cormorant.js\n                isFilteredDevice: function(device) { return true; }\n};\n\nlet devicesTable = new DevicesTable(elementId, options);\n\n// To update the device name after fetching a digital twin with cormorant.js:\ndevicesTable.updateDigitalTwin(deviceSignature, digitalTwin);\n\n// To receive notification of a user selection of a device in the table:\ndevicesTable.on('selection', (deviceSignature) =\u003e { /* Selection handler */ });\n```\n\n\n![cuttlefish logo](https://reelyactive.github.io/cuttlefish/images/cuttlefish-bubble.png)\n\n\nWhat's in a name?\n-----------------\n\nThe cuttlefish isn't actually a fish, but rather a cephalopod, which is a class of marine animals remarkable for how quickly and diversely they can communicate visually.  [As per Wikipedia](https://en.wikipedia.org/wiki/Cuttlefish#Communication): \"flamboyant cuttlefish use between 42 and 75 chromatic, seven textural, 14 postural, and seven locomotor elements\" to communicate.\n\nGiven that cuttlefish.js communicates machine-readable data as human-readable visual information, that unprecedented natural vocabulary sets some serious expectations for UI/UX design!  Seriously.  Read [Jaron Lanier's 2006 article in Discover Magazine](http://discovermagazine.com/2006/apr/cephalopod-morphing/).\n\nIn its client-side habitat, cuttlefish.js will consume and render the JSON-LD fetched by [cormorant.js](https://github.com/reelyactive/cormorant).  And while you may suspect that cuttlefish and cormorants have nothing more in common than the fact that the pupil of the former resembles the distinct wing shape of the latter, check out [this video](https://youtu.be/OQq__WdJBMw?t=2m40s) we found on the Internets.  Yeah, if that skate were a [beaver](https://github.com/reelyactive/beaver)...\n\nSpeaking of videos, we'd be remiss not to share with you Ze Frank's [True Facts about the Cuttlefish](https://youtu.be/GDwOi7HpHtQ).  May we also suggest an images search for \"cute baby cuttlefish\".  You're welcome.\n\n\nProject History\n---------------\n\n__cuttlefish__ v2.0.0 was released in February 2023.\n\n__cuttlefish.js__ v1.0.0 was released in July 2019, superseding all earlier versions, the latest of which remains available in the [release-0.1 branch](https://github.com/reelyactive/cuttlefish/tree/release-0.1).\n\n\nModular Architecture\n--------------------\n\n__cuttlefish.js__ is easily combined with the following complementary client-side modules:\n- [beaver.js](https://github.com/reelyactive/beaver)\n- [cormorant.js](https://github.com/reelyactive/cormorant)\n- [charlotte.js](https://github.com/reelyactive/charlotte)\n\nLearn more about the [reelyActive Open Source Software packages](https://reelyactive.github.io/diy/oss-packages/), all of which are bundled together as [Pareto Anywhere](https://github.com/reelyactive/pareto-anywhere) open source IoT middleware.\n\n\nContributing\n------------\n\nDiscover [how to contribute](CONTRIBUTING.md) to this open source project which upholds a standard [code of conduct](CODE_OF_CONDUCT.md).\n\n\nSecurity\n--------\n\nConsult our [security policy](SECURITY.md) for best practices using this open source software and to report vulnerabilities.\n\n\nLicense\n-------\n\nMIT License\n\nCopyright (c) 2016-2025 [reelyActive](https://www.reelyactive.com)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freelyactive%2Fcuttlefish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freelyactive%2Fcuttlefish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freelyactive%2Fcuttlefish/lists"}