Add initial documentation files

ml5js · Jul 8, 2024 · 60d565a · 60d565a
1 parent 94ba64b
commit 60d565a
Show file tree

Hide file tree

Showing 61 changed files with 6,733 additions and 0 deletions.
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,120 @@
+# ml5.js - Friendly Machine Learning for the Web
+
+Welcome to the ml5.js documentation. Here you'll find everything you need to get up and started with ml5.
+
+## Getting Started {docsify-ignore}
+
+
+Take a ride on the Coding Train to watch Dan Shiffman's ["A Beginner's Guide to Machine Learning with ml5.js"](https://www.youtube.com/watch?v=jmznx0Q1fP0). Here Dan explains what ml5.js is and where it all comes from.
+
+ml5.js is machine learning _for the web_ in your web browser. Through some clever and exciting advancements, the folks building [TensorFlow.js](https://www.tensorflow.org/js) figured out that it is possible to use the web browser's built in graphics processing unit (GPU) to do calculations that would otherwise run very slowly using central processing unit (CPU). A really nice explanation of what is happening with GPUs can be found [here - Why are shaders fast?](https://thebookofshaders.com/01/). ml5 strives to make all these new developments in machine learning on the web more approachable for everyone.
+
+
+### Quickstart
+
+The fastest way to get started exploring the creative possibilities of ml5.js are:
+
+1. If you're interested in using p5.js with ml5.js, you can [start with our boilerplate p5.js web editor sketch](https://editor.p5js.org/ml5/sketches/qqhYX2QmN) or [copy the p5.js + ml5.js boilerplate files from GitHub](https://github.com/ml5js/ml5-library/tree/main/examples/p5js/ml5Boilerplate/ml5Boilerplate_Version).
+2. If you're interested in using ml5.js without p5.js, [copy the ml5.js-only boilerplate files from GitHub](https://github.com/ml5js/ml5-library/tree/main/examples/javascript/ml5Boilerplate/ml5Boilerplate_Version). View [this boilerplate code live on our examples site](https://examples.ml5js.org/javascript/ml5Boilerplate/ml5Boilerplate_Version/) to see the expected output.
+3. Alternatively, you can copy and paste the CDN link to the ml5.js library:
+
+  ```html
+  <script src="https://unpkg.com/ml5@latest/dist/ml5.min.js"></script>
+  ```
+
+***
+#### Quickstart: Plain JavaScript
+
+Reference the [latest version](https://unpkg.com/ml5@latest/dist/ml5.min.js) of ml5.js using a script tag in an HTML file as below:
+
+
+In an **index.html** file, copy and paste the following and open up that file in your web browser.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Getting Started with ml5.js</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <script src="https://unpkg.com/ml5@latest/dist/ml5.min.js"></script>
+  </head>
+
+  <body>
+    <script>
+      // Your code will go here
+      // open up your console - if everything loaded properly you should see the correct version number
+      console.log('ml5 version:', ml5.version);
+    </script>
+  </body>
+</html>
+```
+
+***
+
+***
+#### Quickstart: Powered with p5.js
+
+If you're familiar with [p5.js](https://p5js.org/), ml5.js has been designed to play very nicely with p5. You can use the following boilerplate code to get started:
+
+
+In an **index.html** file, copy and paste the following and open up that file in your web browser.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Getting Started with ml5.js</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <!-- p5 -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.0.0/p5.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.0.0/addons/p5.sound.min.js"></script>
+    <!-- ml5 -->
+    <script src="https://unpkg.com/ml5@latest/dist/ml5.min.js"></script>
+  </head>
+
+  <body>
+    <script>
+      // Your code will go here
+      // open up your console - if everything loaded properly you should see the latest ml5 version
+      console.log('ml5 version:', ml5.version);
+
+      function setup() {
+        createCanvas(400, 400);
+      }
+
+      function draw() {
+        background(200);
+      }
+    </script>
+  </body>
+</html>
+```
+
+***
+
+<br/>
+
+
+
+## Join Our Community {docsify-ignore}
+
+We are on [Discord](https://discord.gg/3CVauZMSt7)
+
+
+## Contribute to ml5.js {docsify-ignore}
+
+ml5 is an open source project that values all contributions. ml5 contributions often take the shape of workshops, design contributions, helping to answer people's questions on Github, flagging bugs in code, fixing bugs, adding new features, and more.
+
+If you'd like to contribute, you're welcome to browse through the issues in our [Github](https://github.com/ml5js/ml5-library/issues) or create a new issue. If you're still unsure of where to start, feel free to ping us at [@ml5js on twitter](https://twitter.com/ml5js), <a href="mailto:[email protected]">[email protected]</a>, or join our [Discord](https://discord.gg/3CVauZMSt7)
+
+## Support {docsify-ignore}
+
+ml5 is always on the look out for grants and funding to support the maintenance and development of the ml5 project (including our educational and community based initiatives). If you are an educational institution, grant funding organization, or otherwise interested in funding the ml5 community of students, researchers, artists, educators, designers, and developers, we'd love to hear from you.
+
+Feel free to reach out at <a href="mailto:[email protected]">[email protected]</a>.
+
+## Acknowledgements {docsify-ignore}
+
+ml5.js is supported by the time and dedication of open source developers from all over the world. Funding and support is generously provided by a [Google Education grant](https://edu.google.com/why-google/our-commitment/?modal_active=none%2F) at [NYU's ITP/IMA program](https://itp.nyu.edu/).
+
+Many thanks [BrowserStack](https://www.browserstack.com/) for providing testing support.
diff --git a/docs/_media/GitHub-Mark-120px-plus.png b/docs/_media/GitHub-Mark-120px-plus.png
diff --git a/docs/_media/reference__header-bodypix.png b/docs/_media/reference__header-bodypix.png
diff --git a/docs/_media/reference__header-charrnn.png b/docs/_media/reference__header-charrnn.png
diff --git a/docs/_media/reference__header-dcgan.png b/docs/_media/reference__header-dcgan.png
diff --git a/docs/_media/reference__header-faceapi.png b/docs/_media/reference__header-faceapi.png
diff --git a/docs/_media/reference__header-facemesh.jpg b/docs/_media/reference__header-facemesh.jpg
diff --git a/docs/_media/reference__header-feature-extractor.png b/docs/_media/reference__header-feature-extractor.png
diff --git a/docs/_media/reference__header-handpose.gif b/docs/_media/reference__header-handpose.gif
diff --git a/docs/_media/reference__header-imageClassifier.png b/docs/_media/reference__header-imageClassifier.png
diff --git a/docs/_media/reference__header-kmeans.png b/docs/_media/reference__header-kmeans.png
diff --git a/docs/_media/reference__header-knn-classifier.png b/docs/_media/reference__header-knn-classifier.png
diff --git a/docs/_media/reference__header-neural-network.png b/docs/_media/reference__header-neural-network.png
diff --git a/docs/_media/reference__header-pitch-detection.png b/docs/_media/reference__header-pitch-detection.png
diff --git a/docs/_media/reference__header-pix2pix.png b/docs/_media/reference__header-pix2pix.png
diff --git a/docs/_media/reference__header-posenet.jpg b/docs/_media/reference__header-posenet.jpg
diff --git a/docs/_media/reference__header-sentiment.png b/docs/_media/reference__header-sentiment.png
diff --git a/docs/_media/reference__header-sketchrnn.png b/docs/_media/reference__header-sketchrnn.png
diff --git a/docs/_media/reference__header-sound-classifier.png b/docs/_media/reference__header-sound-classifier.png
diff --git a/docs/_media/reference__header-styletransfer.png b/docs/_media/reference__header-styletransfer.png
diff --git a/docs/_media/reference__header-unet.png b/docs/_media/reference__header-unet.png
diff --git a/docs/_media/reference__header-utils.png b/docs/_media/reference__header-utils.png
diff --git a/docs/_media/reference__header-word2vec.png b/docs/_media/reference__header-word2vec.png
diff --git a/docs/_media/reference__header-yolo.png b/docs/_media/reference__header-yolo.png
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,68 @@
+<style>
+.Sidebar__section-divider{
+  height:1px; 
+  width:90%; 
+  border-top:2px solid #A15FFB; 
+  display:block; 
+  margin:0 0px 0 -2px;
+  box-shadow: 1px 1px 4px rgba(0,0,0,0.2);
+}
+</style>
+
+* **Welcome** 🌈
+<div class="Sidebar__section-divider">&nbsp;</div>
+
+  * [Getting Started](/)
+  * [FAQ](/faq.md)
+
+
+
+* **Tutorials** 🧠
+<div class="Sidebar__section-divider">&nbsp;</div>
+
+  * [Introduction to ml5.js](/tutorials/hello-ml5.md)
+  * [Running a local web server](/tutorials/local-web-server)
+  * [Promises and Callbacks in ml5](/tutorials/promises-and-callbacks.md)
+
+* **Reference** 📝
+<div class="Sidebar__section-divider">&nbsp;</div>
+
+  * [Overview](/reference/index.md)
+  * **Helpers** ✨
+    * [NeuralNetwork](/reference/neural-network.md)
+    * [FeatureExtractor](/reference/feature-extractor.md)
+    * [KNNClassifier](/reference/knn-classifier.md)
+    * [kmeans](/reference/kmeans.md)
+  * **Image** 🖼
+    * [ImageClassifier](/reference/image-classifier.md)
+    * [PoseNet](/reference/posenet.md)
+    * [BodyPix](/reference/bodypix.md)
+    * [UNET](/reference/unet.md)
+    * [Handpose](/reference/handpose.md)
+    * [Facemesh](/reference/facemesh.md)
+    * [FaceApi](/reference/face-api.md)
+    * [StyleTransfer](/reference/style-transfer.md)
+    * [pix2pix](/reference/pix2pix.md)
+    * [CVAE](/reference/cvae.md)
+    * [DCGAN](/reference/dcgan.md)
+    * [SketchRNN](/reference/sketchrnn.md)
+    * [ObjectDetector](/reference/object-detector.md)
+  * **Sound** 📻
+    * [SoundClassification](/reference/sound-classifier.md)
+    * [PitchDetection](/reference/pitch-detection.md)
+  * **Text** 📕
+    * [CharRNN](/reference/charrnn.md)
+    * [Sentiment](/reference/sentiment.md)
+    * [Word2Vec](/reference/word2vec.md)
+  * **Utils** 🛠
+    * [utils](/reference/utils.md)
+
+* **Contributing** 🏗 
+<div class="Sidebar__section-divider">&nbsp;</div>
+
+  * [Contributor Notes](/styleguide/contributor-notes.md)
+  * [Maintenance Notes](/styleguide/maintenance-notes.md)
+  * Style Guide
+    * [Reference guidelines](/styleguide/reference-guidelines.md)
+    * [Development guidelines](/styleguide/development-guidelines.md)
+    * [Design guidelines](/styleguide/design-guidelines.md)
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,31 @@
+# Frequently Asked Questions (FAQ)
+
+### Can I use ml5.js in the [p5 web editor](https://editor.p5js.org)?
+
+Mostly.
+
+A number of the ml5 sketches don't currently work in the p5 web editor due to some of the ways that the editor handles data files and some of the network communication regarding making requests to external data (e.g. the big model files that allow ml5.js to run things like image detection, etc). 
+
+There are lots of developments in the p5 web editor as well as in ml5 to make sure these environments all play nicely together. If something doesn't work in the web editor, the best thing to do is to try and run things locally if possible. See [running a local web server tutorial](/tutorials/local-web-server.md).
+
+Thanks!
+
+### Can I use ml5.js with node.js?
+
+No. Not at the moment.
+
+ml5.js uses TensorFlow.js which uses the browser's GPU to run all the calculations. As a result, all of the ml5.js functionality is based around using the browser GPU. We hope to have ml5.js run in node-js sometime in the near future (especially now that [node support for TensorFlow is a thing](https://www.tensorflow.org/js/guide/nodejs) but the current ml5 setup does not support node.js. We hope to support this in the future.
+
+
+[For more discussion about node and ml5.js, visit this issue thread.](https://github.com/ml5js/ml5-library/issues/377)
+
+
+### Can I contribute?
+
+Yes! Absolutely. We welcome all forms of socially and technically driven contributions. No contribution is too small. 
+
+Please contact us at [@ml5js on twitter](https://twitter.com/ml5js), <a href="mailto:[email protected]">[email protected]</a>, or [Github](https://github.com/ml5js/ml5-library/issues).
+
+### How can I contribute?
+
+Please refer to the contributor documentation [on Github](https://github.com/ml5js/ml5-library/blob/main/CONTRIBUTING.md).
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,145 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<title>ml5 - A friendly machine learning library for the web.</title>
+		<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+		<meta
+			name="description"
+			content="A friendly machine learning library for the web."
+		/>
+		<meta
+			name="viewport"
+			content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
+		/>
+		<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" />
+		<!-- Edit on Github -->
+		<script src="//unpkg.com/docsify-edit-on-github/index.js"></script>
+		<!-- custom styles -->
+		<style>
+			.github-corner {
+				display: none;
+			}
+			.Menu__Top {
+				background: #ffffff;
+				color: black;
+				position: fixed;
+				top: 0px;
+				width: 100%;
+				height: 60px;
+				margin: 0px !important;
+				display: -webkit-box;
+				display: -moz-box;
+				display: -ms-flexbox;
+				display: -webkit-flex;
+				display: flex;
+				padding: 0rem 2rem;
+				align-items: center;
+				justify-content: space-between;
+				z-index: 1000;
+			}
+			.Menu__Top__LogoContainer {
+				display: flex;
+			}
+			.Menu__Top__LogoContainer_Logo {
+				height: 28px;
+			}
+
+			.sidebar {
+				margin: 80px 0 0 0;
+			}
+
+			.Menu__Top__Menu {
+				display: flex;
+				align-items: center;
+			}
+
+			.Menu__Top__Menu__Item:not(:last-child) {
+				margin-right: 2rem;
+			}
+
+			@media screen and (max-width: 600px) {
+				.Menu__Top__LogoContainer {
+					width: 300px !important;
+					flex: 3;
+				}
+				.Menu__Top__Menu {
+					flex: 1;
+				}
+				.Menu__Top__Menu__Item {
+					display: none !important;
+				}
+			}
+			@media screen and (min-width: 600px) {
+				.Menu__Top {
+					padding: 0 0.5em;
+				}
+			}
+		</style>
+	</head>
+	<body>
+		<nav class="Menu__Top">
+			<a href="https://archive.ml5js.org/" class="Menu__Top__LogoContainer">
+				<img
+					class="Menu__Top__LogoContainer_Logo"
+					src="https://archive.ml5js.org/static/ml5_logo_purple-88e082b8dc81d8729f95bcc092db90c5.png"
+					alt="ml5 Logo"
+				/>
+			</a>
+
+			<div class="Menu__Top__Menu">
+				<a class="Menu__Top__Menu__Item" href="./#/">Getting Started</a>
+				<a class="Menu__Top__Menu__Item" href="./#/reference/index"
+					>Reference</a
+				>
+				<a
+					class="Menu__Top__Menu__Item"
+					href="https://archive.ml5js.org/community/"
+					>Community</a
+				>
+				<a class="Menu__Top__Menu__Item" href="https://archive.ml5js.org/about/"
+					>About</a
+				>
+				<a
+					class="Menu__Top__Menu__Item"
+					href="https://github.com/ml5js/ml5-library"
+				>
+					<img
+						class="Menu__Top__LogoContainer_Logo"
+						src="_media/GitHub-Mark-120px-plus.png"
+						alt="github Logo"
+					/>
+				</a>
+			</div>
+		</nav>
+
+		<div id="app">loading...</div>
+		<script>
+			window.$docsify = {
+				name: 'ml5-archive-docs',
+				repo: 'https://github.com/ml5js/ml5-archive-docs',
+				loadSidebar: '_sidebar.md',
+				alias: {
+					'/.*/sidebar.md': '/./sidebar.md',
+				},
+				subMaxLevel: 2,
+				relativePath: true,
+				maxLevel: 2,
+				mergeNavbar: true,
+				auto2top: true,
+			};
+		</script>
+		<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+		<!-- Plugins -->
+		<!-- Search -->
+		<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
+		<!-- Emoji plugin -->
+		<script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
+		<!-- External JS -->
+		<script src="//unpkg.com/docsify/lib/plugins/external-script.min.js"></script>
+		<!-- Copy to clipboard -->
+		<script src="//unpkg.com/docsify-copy-code"></script>
+		<!-- Pagination -->
+		<script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
+	</body>
+</html>