README.md 4.72 KB
Newer Older
inkhey's avatar
inkhey committed
1
# PiouPiou
2

inkhey's avatar
inkhey committed
3
![logo](pioupiou.png)
inkhey's avatar
inkhey committed
4

inkhey's avatar
inkhey committed
5 6 7
![pipeline_build_status](https://framagit.org/inkhey/pioupiou/badges/master/pipeline.svg)
![PyPI - License](https://img.shields.io/pypi/l/pioupiou)
![PyPI - Status](https://img.shields.io/pypi/status/pioupiou)
inkhey's avatar
inkhey committed
8 9 10
[![PyPI](https://img.shields.io/pypi/v/pioupiou) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pioupiou) ![PyPI](https://img.shields.io/pypi/dm/pioupiou)](https://pypi.org/project/pioupiou/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
![mypy](https://img.shields.io/badge/mypy-checked-blueviolet)
inkhey's avatar
inkhey committed
11

Raphaël Jakse's avatar
Raphaël Jakse committed
12
An avatar generator optimised for generating random avatars based on multiple image layers, able to return same image from a string "seed".
inkhey's avatar
inkhey committed
13 14
Heavily inspired by [David Revoy](http://www.peppercarrot.com)'s [cat avatar generator](https://framagit.org/Deevad/cat-avatar-generator/) and [MonsterID by Andreas Gohr's](https://www.splitbrain.org/blog/2007-01/20_monsterid_as_gravatar_fallback).

Raphaël Jakse's avatar
Raphaël Jakse committed
15
This generator relies on the Pillow library to do image processing.
inkhey's avatar
inkhey committed
16

Raphaël Jakse's avatar
Raphaël Jakse committed
17
See a [Demo](https://pioupiou.inkey-art.net/) (running [pioupiouweb from buxx](https://github.com/buxx/pioupiouweb)).
inkhey's avatar
inkhey committed
18

inkhey's avatar
inkhey committed
19 20 21 22
## Install

### From pypi

23
```sh
24
$ pip install pioupiou
25
```
inkhey's avatar
inkhey committed
26 27 28 29 30 31

### From source

- clone this repository
- `pip install -e "."`

inkhey's avatar
inkhey committed
32 33
## Usage

34 35 36 37
## High Level Api

The high level Api will help you choose avatar between multiples themes, according to installed themes.

38
```python
39
from pioupiou import AvatarGenerator
40

41 42
# check sample/example.py for code to build default sample themes
from sample.example import generate_default_themes
43

44 45 46 47 48 49
themes = generate_default_themes(sample_dir_path="./sample")
avatar_generator = AvatarGenerator(themes)
# note: you can override default theme list and/or theme chooser (mecanism to randomly choose a theme according to token)
avatar = avatar_generator.generate_avatar(token="just a random string")
avatar_generator.save_on_disk(avatar, path="/tmp/saved_file.png")
# note: you can choose a specific theme according to activate theme
50 51 52
avatar = avatar_generator.generate_avatar(
    theme_name="cat_revoy", token="just a random string"
)
53
avatar_generator.save_on_disk(avatar, path="/tmp/saved_file_2.png")
54
```
55 56

## Low Level Api (AvatarTheme)
57

Raphaël Jakse's avatar
Raphaël Jakse committed
58 59
The easy way to use it is to be based on FolderAvatarTheme. To do this, you should create many .png file of same image, all
with transparency. You should follow a similar naming pattern as in the following example.
inkhey's avatar
inkhey committed
60

Raphaël Jakse's avatar
Raphaël Jakse committed
61
To test it, you can, for instance, use a cat avatar [by David Revoy](http://www.peppercarrot.com):
inkhey's avatar
inkhey committed
62

63
```python
64
from pioupiou import FolderAvatarTheme
65 66 67 68 69

theme = FolderAvatarTheme(
    folder_path="sample/cat_revoy",
    layers_name=["body", "fur", "eyes", "mouth", "accessorie"],
)
70 71
avatar = theme.generate_avatar(token="just a random string")
theme.save_on_disk(avatar, path="/tmp/saved_file.png")
72
```
inkhey's avatar
inkhey committed
73

Raphaël Jakse's avatar
Raphaël Jakse committed
74
Or a bird avatar [by David Revoy](http://www.peppercarrot.com):
inkhey's avatar
inkhey committed
75

76
```python
77
from pioupiou import FolderAvatarTheme
78

79 80 81 82 83 84
theme = FolderAvatarTheme(
    "sample/bird_revoy",
    layers_name=["tail", "hoop", "body", "wing", "eyes", "bec", "accessorie"],
)
avatar = theme.generate_avatar(token="just a random string")
theme.save_on_disk(avatar, path="/tmp/saved_file.png")
85
```
inkhey's avatar
inkhey committed
86

Raphaël Jakse's avatar
Raphaël Jakse committed
87
Or a Monster avatar [by Andreas Gohr's](https://www.splitbrain.org/blog/2007-01/20_monsterid_as_gravatar_fallback):
inkhey's avatar
inkhey committed
88

89
```python
90
from pioupiou import FolderAvatarTheme
91

92 93 94 95 96 97
theme = FolderAvatarTheme(
    "sample/monster_id",
    layers_name=["legs", "hair", "arms", "body", "eyes", "mouth"],
)
avatar = theme.generate_avatar(token="just a random string")
theme.save_on_disk(avatar, path="/tmp/saved_file.png")
98
```
99 100 101

## Configure Chooser

Raphaël Jakse's avatar
Raphaël Jakse committed
102 103 104
To generate avatars, pioupiou provides tools to help you use the algorithm you want.
The default behaviour is to rely on `random.Random()`, but pioupiou is made to support any type of chooser.
To do this, you just need to configure the chooser with your `AvatarTheme`:
105

106
```python
107 108
from pioupiou import FolderAvatarTheme
from random import Random
109

110
theme = FolderAvatarTheme(
111 112 113
    folder_path="sample/cat_revoy",
    layers_name=["body", "fur", "eyes", "mouth", "accessorie"],
    chooser=Random(),  # same as default, don't change anything
114
)
115
```
116

Raphaël Jakse's avatar
Raphaël Jakse committed
117 118
You can use any hashlib algorithm you want from `hashlib`, using `pioupiou.chooser.HashLibChooser`.
It will make choices using a modulo.
119

120
```python
121 122 123
from pioupiou import FolderAvatarTheme
import hashlib
from pioupiou.chooser import HashLibChooser
124

125
theme = FolderAvatarTheme(
126 127 128 129 130
    folder_path="sample/cat_revoy",
    layers_name=["body", "fur", "eyes", "mouth", "accessorie"],
    chooser=HashLibChooser(
        hashlib.sha256()
    ),  # hashlib.sha256() is just an example, hashlib.md5() should also work for example.
131
)
132
```
133

inkhey's avatar
inkhey committed
134
You can also implement `pioupiou.chooser.Chooser` and use a custom chooser.