Git Product home page Git Product logo

multiavatar's Introduction

Multiavatar

Multiavatar is a multicultural avatar maker.

Multiavatar represents people from multiple races, multiple cultures, multiple age groups, multiple worldviews and walks of life.

In total, it is possible to generate 12,230,590,464 unique avatars.

Installation and usage

Include the script and pass any string to the 'multiavatar' function. It will return the SVG code for the avatar.

Using npm:

npm i @multiavatar/multiavatar

CommonJS:

const multiavatar = require('@multiavatar/multiavatar')
let svgCode = multiavatar('Binx Bond')

ES Module:

import multiavatar from '@multiavatar/multiavatar/esm'
let svgCode = multiavatar('Binx Bond')

Using the script tag:

<script src="multiavatar.min.js"></script>

<script>
  var avatarId = 'Binx Bond';
  var svgCode = multiavatar(avatarId);
</script>

Include from CDN:

<script src="https://cdn.jsdelivr.net/npm/@multiavatar/multiavatar/multiavatar.min.js"></script>

Info

The initial unique 48 (16x3) avatar characters are designed to work as the source from which all 12 billion avatars are generated.

You can find them in the svg folder. These initial characters can be edited with a vector drawing program, such as Inkscape. They are in grayscale, since the color is applied later by the script, and grayscale is better for shapes design.

Every avatar consists of 6 parts:

  • Environment
  • Clothes
  • Head
  • Mouth
  • Eyes
  • Top

Also, there are different versions of different parts. In some final avatars, additional parts are hidden with transparency (none for the color) to create different shapes by re-using the same code. Also, each avatar has 3 unique color themes that are defined in the script. In total, there are: 16 characters x 3 versions/themes = 48 initial unique avatars. You can see them all by opening the svg/index.html file in your browser.

To create new avatars, the Multiavatar script mixes different parts of different avatars, and different color themes.

The total number of unique avatars: 48^6 = 12,230,590,464

One of the main Multiavatar functions is to work as an identicon. Every unique avatar can be identified by the unique string of characters, associated with the avatar.

The string of characters is also the input for the Multiavatar script, which converts the provided string into a 6 double-digit numbers (range 00-47), each representing an individual part of the final avatar.

000000000000 - this string of numbers represents the very first avatar + its A theme. You can also read it like this: 00 00 00 00 00 00.

474747474747 - this is the 12,230,590,464th avatar (or the 16th initial avatar + its "C" color theme).

More info can be found in the multiavatar.js file comments.

Development

Multiavatar is coded in vanilla JavaScript. Only a single library (SHA-256) is used, integrated into the script. The initial character designs in SVG are also integrated into the script. So there is a single dependency-free JavaScript file that has everything in it (minified 68 KB).

To test different parts manually, you can uncomment them in the code.

Also, the Multiavatar script accepts the following three paramenters: string, sansEnv, ver.

string - The text string that will be converted into the avatar. This parameter is required, the other two are optional.

sansEnv - If this is true, the script returns the final avatar without the circle background (environment part).

ver - Pass an object to force a specific initial version, for example: multiavatar('test', false, {'part': '01', 'theme': 'A'});

While the algorithm generates 12 billion unique avatars, some parts (eyes, mouth) are still similar, so it means that currently there are less than 12 billion unique avatars. It is trivial to make all avatars unique by slightly changing the color, but visually that would not make a difference. That's why instead of forcing a formal solution, some parts are left unfinished intentionally.

The design of shapes, and the multicultural balance of avatars are also open for further polishing, optimization, creative ideas and improvements.

Design

The final SVG files are saved (Inkscape 1.0 as "Optimized SVG") with the _final suffix in the svg folder.

After editing the SVG files with a vector program, overwrite the existing _final.svg files with your new versions. Then run the _build.php script to automatically update the multiavatar-dev.js script with the new SVG code from your _final.svg files.

API

To get an avatar as SVG code, add the avatar's ID to the URL:

https://api.multiavatar.com/Binx Bond

JavaScript API call example to get SVG code:

let avatarId = 'Binx Bond'
fetch('https://api.multiavatar.com/'
+JSON.stringify(avatarId))
  .then(res => res.text())
  .then(svg => console.log(svg))

To get an avatar as SVG file, add .svg to the end of the URL:

https://api.multiavatar.com/Binx Bond.svg

To get an avatar as PNG file, add .png to the end of the URL:

https://api.multiavatar.com/Binx Bond.png

License

You can use Multiavatar for free, as long as the conditions described in the LICENSE are followed.

Screenshots

More info

For additional information and extended functionality, visit the multiavatar.com web-app.

The app is based on static html for the home page, and on Laravel 8 + Vue.js for extended functionality, including the web store.

The product mockup generator for the Merch Maker is based on the ImageMagick library.

multiavatar's People

Contributors

bengry avatar giekaton avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

multiavatar's Issues

Generating new new characters

Hi there !
First of all this is really awesome :) thank you for making this awesome ability!
I've managed to run locally and get images generated :D
Now starting to study up on svgs and how to make them, would like to draw my own art style and have it generate a new set of results

Was wondering if you could suggest how you made your images, which program you used, and if there's any specific formatting needed to have it work with the app , like having exactly 6 sections, etc

Thanks a lot ! Have a good one !

Hoping add generating square shape avatar feature

Hi @giekaton your project is excellent, but in some websites and Apps, the avatar is a square shape, so It would be better if the Multiavatar can support generating square shape avatar.

It seems changing the avatar's shape and spread the background color to the edge can do it, but this change may
cost a lot, even rebuild the project.

So an easier way is adding an option discard background , without the circle background, the avatar can fit not only circle shape but the square shape.

Thank you very much!

PHP support

I have just finished rewriting Multiavatar in PHP.

It is now being used for the https://api.multiavatar.com, which became much faster, because before it was a mix of PHP and Node.js, and now just PHP.

Further on, I'm planning to build avatar images "on the fly". On user request, the image will be generated and saved on the server. It will be possible to generate and access it directly just by adding .png or .svg at the end of the URL, e.g. https://multiavatar.com/Starcrasher.png

Additionally, this PHP script will be used in the Multiavatar WordPress plugin, which is planned for the near future.

For more details, please refer to the PHP repository here: https://github.com/multiavatar/multiavatar-php

Feature request

Is there any way users on my website could choose from selected options without leaving the site.
It would be great if options are only 16 or 48 instead of 12 billion.
Need an api which I call to get full list, get avatar characters or generate random avatar.

How to use the API Access Key?

Thanks for your fantastic work! I just created an account on your website. I am just wondering how can I use the API Access Keys shown in my account page.

Publish on NPM

Are you thinking about publishing the API on NPM in a format like CommonJS, UMD, or ES?

Typescript support

Hi,
Any plans to provide types and to rewrite the library in typescript?

Support UMD and ES modules

More and more people are using ES modules because of their static nature. It would be great if Multiavatar supported that. Support for UMD would also be great so then users of AMD and people who just read off the global object could also use it. There a couple different ways this could be implemented, the most organized being a rollup build setup or something, the least being copy and pasting the same code into different files for different formats.

Gender filter (feature request)

Congrats on the new repo! I love it!

It would be handy to be able to add a gender filter, or a filter that creates gender-neutral avatars (say, no mustache for female and gender-neutral avatars).

SVG as inline datauri

Hello @giekaton !

Abstract

I am building a web with users and didn't want to use the "default_user.svg" since it is boring. Found this package and fell in love with it immediately.

Problem

So I went ahead integrated it with my React project and since I don't want to "unsafely render svg text" on my web, I tried inline SVG like the following:

// React Component
const Avatar = () => {
  const svgString = useMemo(() => {
    return multiavatar("hello world!", false)
  }, [])

  return (
    <img src={`data:image/svg+xml,${svgString}`} alt="avatar" />
  )
}

The above did not render because # is included in the svgString.

Solution

So I tried encoding the string as such:

// from "https://github.com/tigt/mini-svg-data-uri"
// "modified" a bit
const REGEX = {
    whitespace: /\s+/g,
    urlHexPairs: /%[\dA-F]{2}/g,
    quotes: /"/g,
}

function specialHexEncode(match: string) {
    switch (match) {
        case '%20': return ' ';
        case '%3D': return '=';
        case '%3A': return ':';
        case '%2F': return '/';
        default: return match.toLowerCase();
    }
}

export const toDataURI = (string: string) =>
    encodeURIComponent(string)
        .trim()
        .replace(REGEX.whitespace, ' ')
        .replace(REGEX.quotes, "'")
        .replace(REGEX.urlHexPairs, specialHexEncode)

The above code was used as return toDataURI(multiavatar("hello world!", false)) and what do you know, it renders!

Advantages

For developers using multiavatar on the client side can easily render the avatars with img tag.

Request

multiavatar function to include optional parameter asDataURI?: boolean (defaults to false)

Real Life Usage

// React Component
const Avatar = () => {
  const svgString = useMemo(() => {
    // May also support options object?
    // return multiavatar("hello world", {
    //   asDataURI: true,
    //   sansEnv: false,
    // })
    
    // expecting `data:image/svg+xml,{encodedSVGstring}`
    return multiavatar("hello world", false, , true);
  }, [])

  return (
    <img src={svgString} alt="avatar" />
  )
}

Edit:

  • Mentioned @giekaton because I wanted to say hello ✋
  • Added expectation returned from multiavatar @ Real Life Usage

API

Hello, Thank you for providing such an excellent project。 How long will this API be used?

Feature request: Age filter

It's an excellent library for generating a unique avatar and it's serving a great purpose.
I think it will gain perfection with an age and gender filter. Since we already have an issue with the gender filter. This issue is a similar request to add an age filter.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.