{"id":23236668,"url":"https://github.com/gre/json2d","last_synced_at":"2025-08-19T23:30:44.318Z","repository":{"id":31093435,"uuid":"34652554","full_name":"gre/json2d","owner":"gre","description":"Express vectorial content in JSON using canvas2d directives","archived":false,"fork":false,"pushed_at":"2016-10-19T14:59:55.000Z","size":53,"stargazers_count":29,"open_issues_count":1,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-01T12:12:27.561Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-27T07:37:55.000Z","updated_at":"2024-11-13T06:56:40.000Z","dependencies_parsed_at":"2022-09-13T21:00:43.130Z","dependency_job_id":null,"html_url":"https://github.com/gre/json2d","commit_stats":null,"previous_names":["gre/slide2d"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gre%2Fjson2d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gre%2Fjson2d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gre%2Fjson2d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gre%2Fjson2d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gre","download_url":"https://codeload.github.com/gre/json2d/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230181547,"owners_count":18185937,"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":[],"created_at":"2024-12-19T04:11:58.636Z","updated_at":"2024-12-19T04:11:59.864Z","avatar_url":"https://github.com/gre.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"json2d\n=======\n\nExpress vectorial content in JSON using canvas2d directives\n\n## Goal\n\n**json2d** is a thin wrapper to expose canvas2d API in a JSON DSL.\nThe goal is to statically describe scalable content.\n\n## The API\n\n```\nvar json2d = require(\"json2d\");\nvar canvas = ...;\nvar ctx = canvas.getContext(\"2d\");\nvar json2d = json2d(ctx);\n\n// Now call the render method:\njson2d.render(data);\n```\n\n## The `data` format\n\n```js\n{\n  \"size\": [ Number, Number ],\n  \"background\": String,\n  \"draws\": Directive[]\n}\n```\n\n\u003e where `Directive` is either:\n- an `Object` defining all styles to set\n- an `Array` defining the draw atomic operation: the method to call followed by parameters\n- a sub `Directive[]`\n\n### `size`\n\nYou have to **define your viewport `size`** and the rendering will scale to the canvas size and will also keep your ratio (it will fit the biggest centered rectangle).\n\n### `background`\n\nThe full canvas will be filled with a **`background` color**.\n\n### `draws`\n\nYour **`draws` directives** will be used to fill and draw content. These directives are **direct mapping from [Canvas 2D context API](http://www.w3.org/TR/2dcontext/)**. Almost every possible shapes that canvas2d provides are supported with following DSL:\n\n**`draws` directives is an array where each element `E` is one of following:**\n- If `E` is an *object*, this object defines all styles to set: all values or this object will be set to the canvas context.\n- If `E` is an *array*, this defines an atomic drawing operation: the first element is the canvas2d context method name and the following elements are arguments to that method.\n- If `E` is an *array* and `E[0]` is also an array, E is a sub array of `draws` directives. It defines a group of operations. Such group is scoped: `ctx.save()` will be called at the start and `ctx.restore()` will be called at the end.\n\nAll draws that occurs will be scaled relatively to the `size` you have defined. That way, we can define scalable (vectorial) content.\n\n## Extension to the Canvas 2D API\n\nThere are some exceptions where the `draws` get extended.\n\n### drawImage\n\n`json2d` supports images drawing with `drawImage` but to define the image you can pass the URL (or a data64 URL) in the first argument.\n\n### Multi-line texts support\n\n`json2d` supports multi-line texts using the `\\n` character.\nTo do so, every texts will be split on `\\n` and result of multiple texts draws.\nNote that you still have to define where the new lines are.\n\nIn that context, you\n**MUST provide a 4th parameter** if you want that multi-line feature: **the lineHeight in pixels**.\n\n\u003e Note: the `maxWidth` that allows the [canvas2d specification](http://www.w3.org/TR/2dcontext/#drawing-text-to-the-canvas) is not supported by json2d.\n\n## Full Example:\n\n```js\nvar json = {\n  \"background\": \"#efd\",\n  \"size\": [ 800, 600 ],\n  \"draws\": [\n    [ \"drawImage\", \"http://i.imgur.com/N8a9CkZ.jpg\", 530, 700, 800, 200, 0, 400, 800, 200 ],\n    { \"font\": \"italic bold 20px monospace\", \"fillStyle\": \"#09f\", \"textBaseline\": \"top\", \"textAlign\": \"right\" },\n    [ \"fillText\", \"some texts...\\nLorem ipsum dolor sit amet,\\n consectetur adipiscing elit,\\n sed do eiusmod tempor incididunt ut labore\\net dolore magna aliqua.\", 780, 10, 20 ],\n    { \"font\": \"italic 40px sans-serif\", \"fillStyle\": \"#099\", \"textBaseline\": \"middle\", \"textAlign\": \"center\" },\n    [ \"fillText\", \"does support\\nmulti-line texts!\\n\\nusing the '\\\\n' character.\\n\\nand also supports images :)\", 400, 200, 48],\n    [ \"beginPath\" ],\n    { \"fillStyle\": \"#f00\" },\n    [ \"arc\", 40, 40, 20, 0, 7 ],\n    [ \"fill\" ],\n    [\n      [ \"beginPath\" ],\n      { \"fillStyle\": \"#f0f\", \"strokeStyle\": \"#909\", \"lineWidth\": 4 },\n      [ \"moveTo\", 100, 60 ],\n      [ \"lineTo\", 80, 20 ],\n      [ \"lineTo\", 120, 20 ],\n      [ \"fill\" ],\n      [ \"closePath\" ],\n      [ \"stroke\" ]\n    ],\n    [\n      [ \"rotate\", -1.5708 ],\n      { \"font\": \"normal 60px sans-serif\", \"fillStyle\": \"#f00\", \"textBaseline\": \"top\", \"textAlign\": \"right\" },\n      [ \"fillText\", \"Some shapes\", -80, 0 ]\n    ],\n    [\n      [ \"beginPath\" ],\n      { \"strokeStyle\": \"rgba(0,0,0,0.2)\", \"lineWidth\": 4 },\n      [ \"rect\", 2, 2, 796, 596 ],\n      [ \"stroke\" ]\n    ]\n  ]\n};\n\nfunction Canvas (w, h, r) {\n  var canvas = document.createElement(\"canvas\");\n  canvas.width = r * w;\n  canvas.height = r * h;\n  canvas.style.width = w + \"px\";\n  canvas.style.height = h + \"px\";\n  return canvas;\n}\n\nvar json2d = require(\"json2d\");\nvar canvas = Canvas(600, 300, window.devicePixelRatio || 1);\nvar ctx = canvas.getContext(\"2d\");\nvar json2d = json2d(ctx);\njson2d.render(json);\ndocument.body.appendChild(canvas);\n```\n\n![](http://i.imgur.com/hAPUzTb.png)\n\nNote in the example how the content is trying to take the biggest possible rectangle in the canvas viewport. For the sake of this example, we have drawn the biggest possible rectangle with a red stroke, but usually you just fill text and shapes in the middle to have a seamless rendering.\n\n## `json2d(context2d, **resolveImage**)`\n\nThe json2d constructor allows a second parameter:\nA function to resolve an `Image` by URL.\n\nThis allows to cache images yourself for instance\nto ensure that all images are loaded before calling `render`.\n\nBy default, `render()` will postpone other `render()` every time an image is loaded\n(like a web page will render images one by one after they loads).\n\n## `render(data, **visitor**)`\n\nThe render method allows a second parameter:\na visitor function called after each rendering steps.\n\nIt is called in **post order** for each draw *Directive*.\n\nThat function is called with 2 parameters:\n- the `path`: an array of indexes of the tree path of the current draw.\n- the `draw` object.\n\nThis function is used by `json2d-editor` implementation.\n\n## Used by...\n\n- [diaporama](https://github.com/gre/diaporama/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgre%2Fjson2d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgre%2Fjson2d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgre%2Fjson2d/lists"}