Avatar Generation Pipeline

The @nextorders/avatar package provides a pipeline to deterministically generate SVG avatars based on a seed string and a set of options. The generation process is based on the "Open Peeps" design set. The pipeline is initiated by a single function call, which orchestrates option validation, component selection, SVG construction, and final transformations to produce a complete SVG string.

The core architecture separates the generic avatar creation logic from the specific style implementation (e.g., Open Peeps). This allows for a modular system where different avatar styles could potentially be used with the same core engine. The entire process is deterministic, meaning the same input options will always produce the same avatar.

Sources: README.md, packages/avatar/src/index.ts, packages/avatar/src/core/index.ts

High-Level Generation Flow

The following diagram illustrates the end-to-end process of generating an avatar, from the initial user call to the final SVG output.

This diagram shows the main stages of the avatar generation pipeline.
Sources: packages/avatar/src/index.ts:15-17, packages/avatar/src/core/index.ts:10-69

Detailed Breakdown

1. Entry Point and Validation

The generation process begins with a call to the createAvatar function. This function serves as the public API for the package.

Sources: packages/avatar/src/index.ts:15

createAvatar(options: AvatarOptions)

This is the main entry point. It accepts an options object and returns the final SVG as a string.

| Parameter | Type | Description - |
| seed | string | Required. A string used to seed the random number generator for deterministic output. - |

• gender | 'male' | 'female' | Optional. Influences the selection of certain avatar features. - |
• clothing | 'amber' | 'green' | 'blue' | 'teal' | 'pink' | 'violet' | Optional. Sets a specific color for the clothing. - |
• emotion | 1 to 10 | Optional. Selects a specific facial expression. - |

Sources: packages/avatar/src/types.ts:3-9, README.md:19-25

The first step within createAvatar is to call validateAvatarOptions. This function performs basic checks on the provided options:

• It ensures the seed property is present, as it is required for deterministic generation.
• It verifies that emotion, if provided, is a number between 1 and 10.
• It checks that gender, if provided, is either 'male' or 'female'.

If any of these checks fail, an Error is thrown.

Sources: packages/avatar/src/utils/validation.ts:3-13, test/unit/index.test.ts:18-24

2. Options Building

After validation, the buildOptions function is called to transform the user-friendly AvatarOptions into a more detailed configuration object required by the core generation engine.

This function:

1. Merges in default SVG and avatar configurations (SVG_CONFIG, AVATAR_CONFIG).
2. Uses selectors (selectGenderConfig, selectFaceEmotion, selectClothingColor) to map the simple user inputs (like gender: 'female' or emotion: 5) to specific component names or color arrays that the Open Peeps style understands.
3. Passes the seed through.
4. The result is a comprehensive options object that will drive the rest of the generation process.

The following diagram shows how buildOptions constructs the final options object.

3. Core Avatar Creation

The createBaseAvatar function (an alias for createAvatar in core/index.ts) is the generic engine. It is style-agnostic and orchestrates the SVG generation using a provided style object and the builtOptions.

The sequence of operations is as follows:

1. PRNG Initialization: A pseudo-random number generator (PRNG) is created using the seed from the options. This ensures that all subsequent "random" choices (like picking components or colors) are deterministic.
2. Style Creation: It calls the create method on the passed style object (in this case, openPeeps.create). This method is responsible for generating the main body of the SVG, including all avatar parts.
3. Background Generation: It determines the background type (solid or gradientLinear) and colors.
4. SVG Transformations: It applies a series of transformations to the generated SVG body. These are applied in a specific order, wrapping the SVG content in <g> tags with transform attributes. The available transformations include scale, flip, rotate, and translate.
5. Masking & Final Assembly: It can apply a radius for rounded corners via an SVG mask. Finally, it constructs the <svg> root element with all its attributes and combines it with the transformed body.

The following sequence diagram shows the interaction between the main createAvatar function and the core engine.

4. The "Open Peeps" Style

The open-peeps directory contains the specific implementation for the Open Peeps avatar style. The main logic is in packages/avatar/src/open-peeps/index.ts.

Style Creation Logic

The create function in this file is the concrete implementation of style.create. It performs the following steps:

1. Calls getComponents to randomly select the SVG code for each part of the avatar (head, face, facial hair, accessories) using the PRNG.
2. Calls getColors to randomly select colors for skin, clothing, etc., also using the PRNG.
3. Assembles the selected SVG components into a single SVG body. Each component is placed and transformed using a <g> tag.

The structure of the returned SVG body is:

<g fill-rule="evenodd" clip-rule="evenodd">
  <!-- Base body and clothing paths -->
  <path d="..." fill="[skinColor]"/>
  <path d="..." fill="[clothingColor]"/>
  <path d="..." fill="#000"/>
</g>
<g transform="matrix(.99789 0 0 1 156 62)">
  <!-- Head Component SVG -->
</g>
<g transform="translate(315 248)">
  <!-- Face Component SVG -->
</g>
<g transform="translate(279 400)">
  <!-- Facial Hair Component SVG -->
</g>
<g transform="translate(203 303)">
  <!-- Accessories Component SVG -->
</g>

Sources: packages/avatar/src/open-peeps/index.ts:14-41

Avatar Components

The avatar is composed of several optional parts. The selection is determined by the PRNG and options like facialHairProbability.

| Component | Description " |
| head | Contains the hair or headwear for the avatar. - |
| face | Defines the facial expression (eyes, mouth). A specific emotion can be requested. - |
| facialHair | Optional facial hair, with a facialHairProbability of 10% by default for male avatars. - |
| accessories | Optional accessories like glasses or an eyepatch, with an accessoriesProbability of 20% by default. - |

Sources: packages/avatar/src/open-peeps/index.ts:15-41, packages/avatar/src/open-peeps/schema.ts

5. SVG Post-Processing and Finalization

After the main SVG body is created by the style, the core engine performs several post-processing steps using functions from packages/avatar/src/core/utils/svg.ts. These steps modify the SVG by wrapping it in transformation groups.

The order of transformations is important:

1. Scale: Zooms the avatar in or out.
2. Flip: Flips the avatar horizontally.
3. Rotate: Rotates the avatar around its center.
4. Translate: Moves the avatar horizontally or vertically.
5. Background: Adds a solid or gradient background layer behind the avatar.
6. Viewbox Mask: Applies a clipping mask to create rounded corners (radius).

This layering of transformations is illustrated below:

This diagram shows how SVG utility functions sequentially wrap the initial SVG body with various transformations.
Sources: packages/avatar/src/core/index.ts:31-59, packages/avatar/src/core/utils/svg.ts

Finally, the createAttrString function assembles the attributes for the root <svg> element (e.g., xmlns, viewBox, width, height), and the complete SVG string is constructed and returned. The result object also contains methods to get a JSON representation with extra metadata (toJson) or a Data URI (toDataUri).

Sources: packages/avatar/src/core/index.ts:61-78, packages/avatar/src/core/utils/svg.ts:133-143

Summary

The avatar generation pipeline is a modular and deterministic process that transforms a simple set of user options into a complete, stylized SVG avatar. It leverages a core, style-agnostic engine that handles SVG transformations and assembly, combined with a specific style implementation (Open Peeps) that provides the visual components. The use of a seeded PRNG ensures that every avatar is reproducible, which is a key feature of the library.