p5.beholder
Version:
A p5 library to facilitate using the Beholder system for Aruco marker detection.
35 lines (34 loc) • 18.5 kB
HTML
<html lang="en" style="font-size:16px"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Home</title><!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]--><script src="scripts/third-party/hljs.js" defer="defer"></script><script src="scripts/third-party/hljs-line-num.js" defer="defer"></script><script src="scripts/third-party/popper.js" defer="defer"></script><script src="scripts/third-party/tippy.js" defer="defer"></script><script src="scripts/third-party/tocbot.min.js"></script><script>var baseURL="/",locationPathname="",baseURL=(locationPathname=document.location.pathname).substr(0,locationPathname.lastIndexOf("/")+1)</script><link rel="stylesheet" href="styles/clean-jsdoc-theme.min.css"><svg aria-hidden="true" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="display:none"><defs><symbol id="copy-icon" viewbox="0 0 488.3 488.3"><g><path d="M314.25,85.4h-227c-21.3,0-38.6,17.3-38.6,38.6v325.7c0,21.3,17.3,38.6,38.6,38.6h227c21.3,0,38.6-17.3,38.6-38.6V124 C352.75,102.7,335.45,85.4,314.25,85.4z M325.75,449.6c0,6.4-5.2,11.6-11.6,11.6h-227c-6.4,0-11.6-5.2-11.6-11.6V124 c0-6.4,5.2-11.6,11.6-11.6h227c6.4,0,11.6,5.2,11.6,11.6V449.6z"/><path d="M401.05,0h-227c-21.3,0-38.6,17.3-38.6,38.6c0,7.5,6,13.5,13.5,13.5s13.5-6,13.5-13.5c0-6.4,5.2-11.6,11.6-11.6h227 c6.4,0,11.6,5.2,11.6,11.6v325.7c0,6.4-5.2,11.6-11.6,11.6c-7.5,0-13.5,6-13.5,13.5s6,13.5,13.5,13.5c21.3,0,38.6-17.3,38.6-38.6 V38.6C439.65,17.3,422.35,0,401.05,0z"/></g></symbol><symbol id="search-icon" viewBox="0 0 512 512"><g><g><path d="M225.474,0C101.151,0,0,101.151,0,225.474c0,124.33,101.151,225.474,225.474,225.474 c124.33,0,225.474-101.144,225.474-225.474C450.948,101.151,349.804,0,225.474,0z M225.474,409.323 c-101.373,0-183.848-82.475-183.848-183.848S124.101,41.626,225.474,41.626s183.848,82.475,183.848,183.848 S326.847,409.323,225.474,409.323z"/></g></g><g><g><path d="M505.902,476.472L386.574,357.144c-8.131-8.131-21.299-8.131-29.43,0c-8.131,8.124-8.131,21.306,0,29.43l119.328,119.328 c4.065,4.065,9.387,6.098,14.715,6.098c5.321,0,10.649-2.033,14.715-6.098C514.033,497.778,514.033,484.596,505.902,476.472z"/></g></g></symbol><symbol id="font-size-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M11.246 15H4.754l-2 5H.6L7 4h2l6.4 16h-2.154l-2-5zm-.8-2L8 6.885 5.554 13h4.892zM21 12.535V12h2v8h-2v-.535a4 4 0 1 1 0-6.93zM19 18a2 2 0 1 0 0-4 2 2 0 0 0 0 4z"/></symbol><symbol id="add-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M11 11V5h2v6h6v2h-6v6h-2v-6H5v-2z"/></symbol><symbol id="minus-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M5 11h14v2H5z"/></symbol><symbol id="dark-theme-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M10 7a7 7 0 0 0 12 4.9v.1c0 5.523-4.477 10-10 10S2 17.523 2 12 6.477 2 12 2h.1A6.979 6.979 0 0 0 10 7zm-6 5a8 8 0 0 0 15.062 3.762A9 9 0 0 1 8.238 4.938 7.999 7.999 0 0 0 4 12z"/></symbol><symbol id="light-theme-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M12 18a6 6 0 1 1 0-12 6 6 0 0 1 0 12zm0-2a4 4 0 1 0 0-8 4 4 0 0 0 0 8zM11 1h2v3h-2V1zm0 19h2v3h-2v-3zM3.515 4.929l1.414-1.414L7.05 5.636 5.636 7.05 3.515 4.93zM16.95 18.364l1.414-1.414 2.121 2.121-1.414 1.414-2.121-2.121zm2.121-14.85l1.414 1.415-2.121 2.121-1.414-1.414 2.121-2.121zM5.636 16.95l1.414 1.414-2.121 2.121-1.414-1.414 2.121-2.121zM23 11v2h-3v-2h3zM4 11v2H1v-2h3z"/></symbol><symbol id="reset-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M18.537 19.567A9.961 9.961 0 0 1 12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10c0 2.136-.67 4.116-1.81 5.74L17 12h3a8 8 0 1 0-2.46 5.772l.997 1.795z"/></symbol><symbol id="down-icon" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M12.7803 6.21967C13.0732 6.51256 13.0732 6.98744 12.7803 7.28033L8.53033 11.5303C8.23744 11.8232 7.76256 11.8232 7.46967 11.5303L3.21967 7.28033C2.92678 6.98744 2.92678 6.51256 3.21967 6.21967C3.51256 5.92678 3.98744 5.92678 4.28033 6.21967L8 9.93934L11.7197 6.21967C12.0126 5.92678 12.4874 5.92678 12.7803 6.21967Z"></path></symbol><symbol id="codepen-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M16.5 13.202L13 15.535v3.596L19.197 15 16.5 13.202zM14.697 12L12 10.202 9.303 12 12 13.798 14.697 12zM20 10.869L18.303 12 20 13.131V10.87zM19.197 9L13 4.869v3.596l3.5 2.333L19.197 9zM7.5 10.798L11 8.465V4.869L4.803 9 7.5 10.798zM4.803 15L11 19.131v-3.596l-3.5-2.333L4.803 15zM4 13.131L5.697 12 4 10.869v2.262zM2 9a1 1 0 0 1 .445-.832l9-6a1 1 0 0 1 1.11 0l9 6A1 1 0 0 1 22 9v6a1 1 0 0 1-.445.832l-9 6a1 1 0 0 1-1.11 0l-9-6A1 1 0 0 1 2 15V9z"/></symbol><symbol id="close-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M12 10.586l4.95-4.95 1.414 1.414-4.95 4.95 4.95 4.95-1.414 1.414-4.95-4.95-4.95 4.95-1.414-1.414 4.95-4.95-4.95-4.95L7.05 5.636z"/></symbol><symbol id="menu-icon" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0z"/><path d="M3 4h18v2H3V4zm0 7h18v2H3v-2zm0 7h18v2H3v-2z"/></symbol></defs></svg></head><body class="dark" data-theme="dark"><div class="sidebar-container"><div class="sidebar" id="sidebar"><a href="/" class="sidebar-title sidebar-title-anchor">p5.beholder</a><div class="sidebar-items-container"><div class="sidebar-section-title with-arrow" data-isopen="false" id="Lkq_Pw7loldzme-6DicJv"><div>Classes</div><svg><use xlink:href="#down-icon"></use></svg></div><div class="sidebar-section-children-container"><div class="sidebar-section-children"><a href="P5Beholder.html">P5Beholder</a></div></div><div class="sidebar-section-title with-arrow" data-isopen="false" id="lonO2ZpEFHAclK9q9bcyN"><div>Global</div><svg><use xlink:href="#down-icon"></use></svg></div><div class="sidebar-section-children-container"><div class="sidebar-section-children"><a href="global.html#p5beholder">p5beholder</a></div></div></div></div></div><div class="navbar-container" id="VuAckcnZhf"><nav class="navbar"><div class="navbar-left-items"><div class="github-link navbar-item"><a id="repository" href="https://github.com/enricllagostera/p5.beholder" target="_blank">GitHub</a></div><div class="navbar-item"><a id="" href="https://enric.llagostera.com.br/" target="_blank">Made by Enric Llagostera</a></div></div><div class="navbar-right-items"><div class="navbar-right-item"><button class="icon-button search-button" aria-label="open-search"><svg><use xlink:href="#search-icon"></use></svg></button></div><div class="navbar-right-item"><button class="icon-button theme-toggle" aria-label="toggle-theme"><svg><use class="theme-svg-use" xlink:href="#light-theme-icon"></use></svg></button></div><div class="navbar-right-item"><button class="icon-button font-size" aria-label="change-font-size"><svg><use xlink:href="#font-size-icon"></use></svg></button></div></div><nav></nav></nav></div><div class="toc-container"><div class="toc-content"><span class="bold">On this page</span><div id="eed4d2a0bfd64539bb9df78095dec881"></div></div></div><div class="body-wrapper"><div class="main-content"><div class="main-wrapper"><section class="readme"><article><h1>p5.beholder</h1><p>This is a library for the <a href="http://p5js.org">p5</a> creative coding tool. It facilitates using the <a href="https://github.com/project-beholder/beholder-detection">Beholder</a> system (not created by me) with p5.</p><h2>Introduction</h2><h3>What is Beholder?</h3><p><a href="https://github.com/project-beholder/beholder-detection">Beholder</a> is a great tool that lets users create JavaScript apps that can detect Aruco markers using a webcam. This becomes the basis to creating tangible systems like alternative game controllers without having to use a lot of electronics. You can print the markers and stick them to objects, and these can be tracked with the camera. Beholder is the basis for a variety of cool applications, and you can read more about them and the system in the papers below:</p><blockquote><p>Gyory, P. (2022). Creating Platforms to Support Craft and Creativity in Game Controller Design. Creativity and Cognition, 708–710. https://doi.org/10.1145/3527927.3533733</p></blockquote><blockquote><p>Gyory, P., Owens, P., Bethancourt, M., Banic, A., Zheng, C., & Do, E. Y.-L. (2022). Build Your Own Arcade Machine with Tinycade. Creativity and Cognition, 312–322. https://doi.org/10.1145/3527927.3533023</p></blockquote><blockquote><p>Zheng, C., Gyory, P., & Do, E. Y.-L. (2020). Tangible Interfaces with Printed Paper Markers. Proceedings of the 2020 ACM on Designing Interactive Systems Conference, 909–923. https://doi.org/10.1145/3357236.3395578</p></blockquote><p>You can also find more info about <a href="https://docs.opencv.org/3.2.0/d5/dae/tutorial_aruco_detection.html">Aruco markers here</a>.</p><h3>A quick example</h3><p>An example of the <strong>Beholder</strong> system in use is the game <a href="https://enric.llagostera.com.br/2022/07/04/de-volta/">DE VOLTA</a>, created for the <a href="https://tinycade.github.io/tinycade-homepage/">Tinycade</a> system.</p><p><img src="https://github.com/enricllagostera/p5.beholder/blob/main/docs/imgs/devolta.gif?raw=true" alt="DE VOLTA being played on a Tinycade at alt.ctrl.GDC 2022"><br><em>DE VOLTA being played on a Tinycade at alt.ctrl.GDC 2022.</em></p><h3>Why p5.beholder?</h3><p>My goal in making <strong>p5.beholder</strong> is to make experimentation with Beholder easier for p5 users. I like using p5 to try out ideas without having to worry much about setting up a lot of tools. I created p5.beholder to streamline the setup for my own prototyping needs, and it's basically a thin shell hooking into the amazing work of the Beholder creators!</p><h2>Installation</h2><h3>Template project</h3><p>There is a template ZIP file with an example project in the root folder of this repository, called <a href="https://github.com/enricllagostera/p5.beholder/blob/main/p5-beholder-template.zip"><code>p5-beholder-template.zip</code></a>. You can download it, extract and use it as a starting point for your project.</p><h3>Setup</h3><p>To use p5.beholder, include the <code>p5.beholder.js</code> (or the minified version <code>p5.beholder.min.js</code>) script in your HTML. You can include it directly from UNPKG:</p><pre class="prettyprint source lang-html"><code><script src="https://unpkg.com/p5.beholder@2.0.0/dist/p5.beholder.js"></script>
</code></pre><p>OR You can also download the file from <a href="https://raw.githubusercontent.com/enricllagostera/p5.beholder/main/dist/p5.beholder.js">here</a>. The compressed and non-compressed versions are in the <code>dist</code> folder of this package as well. Then, include the script in your HTML from your local project folder.</p><p>After either of the options above, the <code>p5beholder</code> object should be now ready to use from within your sketch.</p><h4>p5 web editor</h4><p>You can use p5.beholder directly in the p5 online editor. Go to the <code>index.html</code> file of your sketch and include the script from UNPKG: <code><script src="https://unpkg.com/p5.beholder@2.0.0/dist/p5.beholder.js"></script></code>. After that, you can use the <code>p5beholder</code> object in your <code>sketch.js</code> file.</p><h2>Use</h2><ol><li><strong>Make sure you are running your sketch from a <a href="https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts">secure context</a>.</strong> Browsers only allow access to cameras from sites in secure contexts, for security reasons. Sites served via <code>https://</code> or in a <code>localhost</code> are considered safe. The p5 online editor is on a secure context, so it should work out-of-the-box too.</li><li><strong>Add the <code>p5beholder.prepare()</code> call in the <code>setup</code> function of your sketch.</strong> This initializes Beholder with a default configuration. You can pass in a configuration object (<a href="https://github.com/project-beholder/beholder-detection#custom-config">more info here</a>) and a query selector to an HTML element to be Beholder's root (if the element does not exist, it will be appended as a child of the HTML <code><body></code>).</li><li><strong>Use the methods in the <code>p5beholder</code> from within your sketch.</strong></li></ol><p>You can use <a href="https://chev.me/arucogen/">this website</a> to generate and print Aruco markers (select the "Original Aruco" option on the dropdown).</p><h3>Quick sample</h3><pre class="prettyprint source lang-html"><code><!-- Your index.html file -->
<!DOCTYPE html>
<html lang="en">
<head>
<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.1/p5.js"></script>
<script src="https://unpkg.com/p5.beholder@2.0.0/dist/p5.beholder.min.js"></script>
<link rel="stylesheet" type="text/css" href="style.css" />
<meta charset="utf-8" />
</head>
<body>
<main></main>
<script src="sketch.js"></script>
</body>
</html>
</code></pre><pre class="prettyprint source lang-js"><code>/* Your sketch.js file */
function setup() {
createCanvas(640, 480);
p5beholder.prepare();
}
function draw() {
// Shows a black background if marker 0 is present
if (p5beholder.getMarker(0).present) {
background(0);
} else {
// Shows a white background if marker 0 is NOT present
background(255);
}
// Shows information about marker with ID 0
p5beholder.drawDebugMarker(0);
}
</code></pre><h2>Features</h2><p>With this library, you can use the functions of the Beholder library through the <code>p5beholder</code> object. It takes care of updating automatically, and initialization happens at in the <code>setup()</code> of your sketch.</p><p>Some features are:</p><ol><li><strong>Marker presence to keyboard events.</strong> See <a href="https://enricllagostera.github.io/p5.beholder/02_marker_presence_to_keyboard">demo</a></li><li><strong>Marker presence to mouse click.</strong> See <a href="https://enricllagostera.github.io/p5.beholder/demos/03_marker_presence_to_mouse_click/">demo</a>.</li><li><strong>Marker rotation within range.</strong> See <a href="docs/demos/04_rotation_detection_simple/">demo with raw values</a> and <a href="docs/demos/05_rotation_range_detection_with_lerp/">with interpolation</a>.</li><li><strong>Camera to canvas utility functions.</strong> These useful functions that map coordinates from the camera range to the sketch's canvas range. Example: <code>p5beholder.cameraHeight</code> : returns camera height in pixels; <code>p5beholder.cameraToCanvasXY(x, y)</code> returns an object with <code>x</code> and <code>y</code> values.</li><li><strong>Debug drawing of markers on the canvas.</strong> Using <code>p5beholder.debugDrawMarker(ID)</code> creates a canvas-adjusted visualization of a marker. See <a href="https://enricllagostera.github.io/p5.beholder/demos/01_basic_marker_detection/">demo</a>.</li></ol><h3>API</h3><p>You can see detailed information about the library functions on the <a href="https://enricllagostera.github.io/p5.beholder/P5Beholder.html">P5Beholder API documentation</a>.</p><h2>License</h2><p><strong>p5.beholder</strong> is licensed under the MIT License. You can check its contents <a href="https://github.com/enricllagostera/p5.beholder/blob/main/LICENSE">here</a>.</p></article></section></div></div></div><div class="search-container" id="PkfLWpAbet" style="display:none"><div class="wrapper" id="iCxFxjkHbP"><button class="icon-button search-close-button" id="VjLlGakifb" aria-label="close search"><svg><use xlink:href="#close-icon"></use></svg></button><div class="search-box-c"><svg><use xlink:href="#search-icon"></use></svg> <input type="text" id="vpcKVYIppa" class="search-input" placeholder="Search..." autofocus></div><div class="search-result-c" id="fWwVHRuDuN"><span class="search-result-c-text">Type anything to view search result</span></div></div></div><div class="mobile-menu-icon-container"><button class="icon-button" id="mobile-menu" data-isopen="false" aria-label="menu"><svg><use xlink:href="#menu-icon"></use></svg></button></div><div id="mobile-sidebar" class="mobile-sidebar-container"><div class="mobile-sidebar-wrapper"><a href="/" class="sidebar-title sidebar-title-anchor">p5.beholder</a><div class="mobile-nav-links"><div class="github-link navbar-item"><a id="repository-mobile" href="https://github.com/enricllagostera/p5.beholder" target="_blank">GitHub</a></div><div class="navbar-item"><a id="" href="https://enric.llagostera.com.br/" target="_blank">Made by Enric Llagostera</a></div></div><div class="mobile-sidebar-items-c"><div class="sidebar-section-title with-arrow" data-isopen="false" id="Lkq_Pw7loldzme-6DicJv"><div>Classes</div><svg><use xlink:href="#down-icon"></use></svg></div><div class="sidebar-section-children-container"><div class="sidebar-section-children"><a href="P5Beholder.html">P5Beholder</a></div></div><div class="sidebar-section-title with-arrow" data-isopen="false" id="lonO2ZpEFHAclK9q9bcyN"><div>Global</div><svg><use xlink:href="#down-icon"></use></svg></div><div class="sidebar-section-children-container"><div class="sidebar-section-children"><a href="global.html#p5beholder">p5beholder</a></div></div></div><div class="mobile-navbar-actions"><div class="navbar-right-item"><button class="icon-button search-button" aria-label="open-search"><svg><use xlink:href="#search-icon"></use></svg></button></div><div class="navbar-right-item"><button class="icon-button theme-toggle" aria-label="toggle-theme"><svg><use class="theme-svg-use" xlink:href="#light-theme-icon"></use></svg></button></div><div class="navbar-right-item"><button class="icon-button font-size" aria-label="change-font-size"><svg><use xlink:href="#font-size-icon"></use></svg></button></div></div></div></div><script type="text/javascript" src="scripts/core.min.js"></script><script src="scripts/search.min.js" defer="defer"></script><script src="scripts/third-party/fuse.js" defer="defer"></script><script type="text/javascript">var tocbotInstance=tocbot.init({tocSelector:"#eed4d2a0bfd64539bb9df78095dec881",contentSelector:".main-content",headingSelector:"h1, h2, h3",hasInnerContainers:!0,scrollContainer:".main-content",headingsOffset:130,onClick:bringLinkToView})</script></body></html>