Skip to content

Use any of the of the 50 million Quick, Draw! doodles in your web-based project with one line of markup

License

Notifications You must be signed in to change notification settings

googlecreativelab/quickdraw-component

Repository files navigation

logos for Quick, Draw! and the Polymer Project and Google Cloud

Quick, Draw! Polymer Component & API

Embed Quick, Draw! drawings into your project using a web component, as easily as:

<quick-draw category="apple" key="API_KEY"></quick-draw>

This component is built using Polymer3 and is coupled with an API layer for accessing individual drawing data from the open sourced data set. 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.

Background

In October 2016 we released Quick, Draw!, 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 in the form of very large ndjson files 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:

demo image

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 or Rollup 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:

<quick-draw category="apple" key="AIzaSyC0U3yLy_m6u7aOMi9YJL2w1vWG4oI5mj0"></quick-draw>

A list of all the available categories is here.

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 below. In order to get an API key for the demo endpoint, you need to:

  1. Join the Quick Draw API Google Group.

  2. In your project on Google Cloud Platform, go to APIs & Services > Library 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 and create one. This is what you'll use in the key property of: <quick-draw key="YOUR_API_KEY"></quick-draw>

Options

Name Description Type Default Options / Examples
category *required One of the available categories String null <quick-draw category="apple"></quick-draw>
key *required API Key from Google Cloud Platform String null <quick-draw key="AIzaSyC0U3yLy_m6u7aOMi9YJL2w1vWG4oI5mj0"></quick-draw>
host The host of your API String https://quickdrawfiles.appspot.com <quick-draw host="https://quickdrawfiles.appspot.com"></quick-draw>
index The drawing id within a category (random unless specified) Number -1 <quick-draw category="apple" index="3927"></quick-draw>
animate Animate the drawing in the same time frame it was originally drawn Boolean false <quick-draw category="apple" animate></quick-draw>
time Sets the total time for the animation, preserving time proportions for each path (in milliseconds) Number null <quick-draw category="apple" time="1500" animate></quick-draw>
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 <quick-draw category="apple" paused animate></quick-draw>
strokeColor A hex value for the stroke color String #000000 <quick-draw category="apple" strokeColor="#4285f4"></quick-draw>
strokeWidth The width/thickness of the stroke Number 4 <quick-draw category="apple" strokeWidth="1"></quick-draw>
width The px width of the drawing. If provided, the drawing will scale proportionally to fit the space. String 'auto' <quick-draw category="apple" width="125"></quick-draw>
height The px height of the drawing. If provided, the drawing will scale proportionally to fit the space. String 'auto' <quick-draw category="apple" height="125"></quick-draw>
debug For testing purposes, will log output Boolean false <quick-draw category="apple" debug></quick-draw>

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 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 String null
id *required ID (number) or "random" String null
key *required API Key (see above for instructions) 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 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.

About

Use any of the of the 50 million Quick, Draw! doodles in your web-based project with one line of markup

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published