# Trait Art Generation Instruction

## Terminology
- **Trait**: A characteristic of the art.
- **Rarity**: The chance of having a trait appears in a trait art.
- **Trait Category**: A group of traits, e.g. "Background" can be a trait category, and there are traits: blue background, red background, etc. in this category.
- **Project**: A list of trait categories.
- **Trait Art**: A trait art is combined with a trait from each category in the project.

## How To Construct A Trait Art Project
To construct a trait art project, a number of things have to be defined.

### Project
First, a list of trait categories has to be defined. Take [Bored Ape Yacht Club](https://boredapeyachtclub.com/)(BAYC) as an example, it has 7 trait categories:
1. Background
2. Fur
3. Eyes
4. Mouth
5. Clothes
6. Earring
7. Hat


Every trait art will be composed of traits in these trait categories. **Note that the order of the trait categories matters.** The traits are stacked according to the order of the trait categories, so the trait that stacks earlier may be covered by the other traits.

### Trait Category
There should be at least one trait per category. Every trait in the same trait category is mutually exclusive in a trait art, i.e. a trait art can only have one trait from a category.

For example, there are 6 traits (Silver Stud, Gold Hoop, Gold Stud, Diamond Stud, Cross) in the "Earring" category of [BAYC](https://boredapeyachtclub.com/).

If the final generation does not generate all possible combinations, the rarity of the trait will come into play. The lower the rarity, the less chance the trait appears in a trait art. There are 3 rarity policies available:
- `EQUAL`: All traits in the category will have an equal chance to appear in a trait art.
- `RANDOM`: The chance of a trait appearing in a trait art is randomized before the generation.
- `CUSTOM`: The chance of a trait appearing in a trait art is customized manually.

Note that the final trait distribution may vary due to randomness, it may not be the same as the original rarity setting.

In addition, a trait category can be set to optional, i.e. the category can be absent in a trait art. There is also a `null_rarity` setting for the category, indicating the chance of not having any trait from this category.

### Trait
A trait has a name and a source image. **The source image must have the same dimension as the final output image.** For example, if the final output is a 1000x1000 pixel image, the source image should also have a dimension of 1000x1000 pixels.

**The system does not guarantee the traits in each category can align perfectly.** It only stacks the given traits into a trait art. The designer of the traits is responsible to make sure the traits will always align in different combinations.

Currently, only PNG image file is supported by the system.

## A Project Setting Examples
The project consists of 4 categories:
1. Background:
- Red background (Rarity: 1)
- Green background (Rarity: 1)
- Blue backGround (Rarity: 1)
2. Head:
- Head with long hair (Rarity: Random)
- Head with short hair (Rarity: Random)
3. Body:
- Muscular body (Rarity: 5)
- Normal body (Rarity: 3)
- Skinny body (Rarity: 1)
4. Hat: (optional, `null_rarity`: 8)
- Baseball cap (Rarity: 2)

In the above example, background is the bottom layer, followed by head and body. Hat is placed at last and hence it will cover part of the head.

The background has an equal rarity for each trait, which means the traits all have the same chance to appear in a trait art within the category. Head has a random rarity, so we will only know its traits distribution after the generation. In the meantime, the body category has different rarities for different traits, e.g. muscular body has the highest chance to appear in a trait art.

Background, head and body are compulsory categories (they must appear in every trait art), while hat is an optional category with a null rarity of 8, which means it is very unlikely for a trait art to have a hat.

With all the categories and traits, the total combination of this project is:
> 3 x 2 x 3 x (1+1) = 36