https://github.com/googlecreativelab/quickdraw-component
Use any of the of the 50 million Quick, Draw! doodles in your web-based project with one line of markup
https://github.com/googlecreativelab/quickdraw-component
Last synced: 5 months ago
JSON representation
Use any of the of the 50 million Quick, Draw! doodles in your web-based project with one line of markup
- Host: GitHub
- URL: https://github.com/googlecreativelab/quickdraw-component
- Owner: googlecreativelab
- License: apache-2.0
- Created: 2018-11-15T15:59:12.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-11T00:30:47.000Z (over 1 year ago)
- Last Synced: 2025-03-29T11:10:03.354Z (12 months ago)
- Language: JavaScript
- Homepage: https://googlecreativelab.github.io/quickdraw-component
- Size: 2.05 MB
- Stars: 112
- Watchers: 14
- Forks: 35
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
This project is no longer actively maintained by the Google Creative Lab but remains here in a read-only Archive mode so that it can continue to assist developers that may find the examples helpful. We aren’t able to address all pull requests or bug reports but outstanding issues will remain in read-only mode for reference purposes. Also, please note that some of the dependencies may not be up to date and there hasn’t been any QA done in a while so your mileage may vary.
For more details on how Archiving affects Github repositories see this documentation .
We welcome users to fork this repository should there be more useful, community-driven efforts that can help continue what this project began.
## Quick, Draw! Polymer Component & API
Embed [Quick, Draw!](https://quickdraw.withgoogle.com/) drawings into your project using a web component, as easily as:
``````
This component is built using [Polymer3](https://www.polymer-project.org/) and is coupled with an API layer for accessing individual drawing data from the [open sourced data set](https://github.com/googlecreativelab/quickdraw-dataset). The drawings are drawn out to a canvas element, and provides you with options to customize it for your own web project. [Here's a demo of how it can be used in different ways.](https://googlecreativelab.github.io/quickdraw-component/demo/)
### Background
In October 2016 we released [Quick, Draw!](https://quickdraw.withgoogle.com), a game to test your ability to doodle and have a neural net guess what you're drawing. You can help teach it by adding your drawings to the world’s largest doodling data set, shared publicly to help with machine learning research.
Since the release, we've collected over 1 billion drawings across 345 categories. We've [released the data](https://github.com/googlecreativelab/quickdraw-dataset) in the form of [very large ndjson files](https://github.com/googlecreativelab/quickdraw-dataset/blob/master/examples/nodejs/ndjson.md) of moderated doodles. Now we are releasing a data API, a Polymer web component, and an option to self-host the 50 million files.
## Run example
With npm installed, in the root of this repo:
```
npm install
npm start
```
When this works, you'll see this simple demo of the component:
## Usage
Install as an NPM dependency to your project:
```
npm install --save quickdraw-component
```
Import it:
```
import 'quickdraw-component/quickdraw-component.js';
```
*You need to make sure that your app is using a tool like [Webpack](https://webpack.js.org/concepts/configuration/) or [Rollup](https://rollupjs.org/guide/en) to transpile and bundle the component into your app.*
The most basic usage of the component's properties is to include a static, random drawing of a category with an API Key:
``````
A list of all the available categories is [here](./categories.js).
### Getting a demo API Key
It is *highly encouraged* for any large project to not use the demo endpoint as a dependency - see [Self-Hosting](#self-hosting) below. In order to get an API key for the demo endpoint, you need to:
1. [Join the Quick Draw API Google Group](https://groups.google.com/forum/#!forum/quick-draw-data-api).
2. In your project on Google Cloud Platform, go to [APIs & Services > Library](https://console.developers.google.com/apis/library/quickdrawfiles.appspot.com) and search for "Quick, Draw! API"
3. Click into Quick, Draw! Data API and press "Enable"
4. If you haven't created an API Key yet for your project, go into [APIs & Services > Credentials](https://console.developers.google.com/apis/credentials) and create one. This is what you'll use in the `key` property of: ``
### Options
| Name | Description | Type | Default | Options / Examples|
| :----------- | :-----------:| :-----------:| :-----------:|---------:|
| `category` **required* | One of the [available categories](./categories.js) | String | null | ``````
| `key` **required* | API Key from Google Cloud Platform | String | null | ``````
| `host` | The host of your API | String | https://quickdrawfiles.appspot.com | ``````
| `index` | The drawing id within a category *(random unless specified)* | Number | -1 | ``````
| `animate` | Animate the drawing in the same time frame it was originally drawn| Boolean | *false* |``
| `time` | Sets the total time for the animation, preserving time proportions for each path (in milliseconds)| Number | null |``
| `paused` | When set to true, the component will only load the image data but not draw it. Listen for the data loaded event ```drawingData``` and then call ```drawImage()``` to control it manually| Number | null |``
| `strokeColor` | A hex value for the stroke color | String | #000000 |``
| `strokeWidth` | The width/thickness of the stroke | Number | 4|``
| `width` | The px width of the drawing. If provided, the drawing will scale proportionally to fit the space. | String | 'auto'|``
| `height` | The px height of the drawing. If provided, the drawing will scale proportionally to fit the space. | String | 'auto'|``
| `debug` | For testing purposes, will log output | Boolean | false|``
### Events
You can listen for the following custom events from the component:
| Name | Description | Return |
| ----------- | :-----------:| :-----------:|
| `drawingData` | When drawing data is received | `{detail: {index, category, data}}`
| `drawingComplete` | When drawing is completed | `{detail: {index, category, data}}`
An example of how to access the element to listen for events:
```
function ready() {
var el = document.querySelector('quick-draw');
el.addEventListener('drawingData', function(){
console.log('Drawing data loaded...');
});
el.addEventListener('drawingComplete', function(){
console.log('Drawing complete!');
});
}
document.addEventListener("DOMContentLoaded", ready);
```
### Methods
You can manually call the following methods on your element:
#### fetchImageData(category, index)
This method will load image data, where "category" is one of [these available categories](./categories.js) like "cat", or "apple", and index is the number of the drawing. If index isn't passed, then it will load in a random image. To find out exactly how many indices are available for a given category, use the ```/{category}/count``` API call below.
#### drawImage()
This method will simply draw the image out on the canvas with its current properties. This is especially useful when using the ```paused``` property (when you want to control exactly when it's drawn out).
## API / Middleware
This component has a server-side dependency, which can be reached from this endpoint:
```https://quickdrawfiles.appspot.com/drawing/{category}?id={id}&key={key}&isAnimated={isAnimated}&format={format}```
| Name | Description | Type | Default |
| :----------- | :-----------:| :-----------:| -----------:|
| `category` **required* | One of the [available categories](./categories.js) | String | null
| `id` **required* | ID (number) or "random" | String | null
| `key` **required* | API Key ([see above for instructions](#getting-a-demo-api-key)) | String | null
| `isAnimated` | Will return raw time-based data if true, otherwise simplified data | Boolean | false
| `format` | JSON or canvas drawing | String | "json"
You can also retrieve the total count of drawings within a category using:
```https://quickdrawfiles.appspot.com/drawing/{category}/count?key={key}```
## Self-Hosting
It's highly encouraged that you self-host for larger, more serious projects as the quota limits are subject to change with this one (and it's not guaranteed to be supported / maintained forever). View the [README.md](./api/README.md) in the API directory to learn more about how to self-host the files and the API.
## Contributing
1. Fork it!
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request :D
## License
The component & API fall under the Apache 2.0 license.