Icon System

Icon System¶

Back to Home

The ByteBiota Procedural Icon System (DLIS) generates deterministic, hierarchical visual representations for classified organisms. Each organism automatically receives a unique icon reflecting its taxonomy, behavioral traits, and genome properties.

Overview {#overview}¶

The icon system serves as a visual identifier system for digital organisms, providing both aesthetic appeal and informational value in dashboards, reports, and species galleries. Icons are generated deterministically—identical genomes always produce identical icons—and maintain hierarchical consistency where related species share similar visual themes.

Design Goals {#design-goals}¶

Data Inputs {#data-inputs}¶

The icon generator consumes the standard classification output from TaxonomyClassifier.classify():

{
  "id": "organism_0",
  "lineage": {
    "domain": "ByteBiota",
    "kingdom": "Digitalis Anomalica",
    "phylum": "Polymorphid",
    "class": "Migrata",
    "order": "Linearis",
    "family": "Standardidae",
    "genus": "Replicatus",
    "species": "Replicatus vulgaris"
  },
  "traits": {
    "replication": true,
    "memory_allocation": true,
    "environment_interaction": true,
    "task_solving": true,
    "energy_harvesting": true
  },
  "genome": {
    "hash": "0bde9fec",
    "size_bytes": 64,
    "valid_opcodes": 39,
    "invalid_opcodes": 25
  },
  "dominant_family": "register_adjust"
}

Generation Pipeline {#generation-pipeline}¶

Step 1: Normalize Taxonomy {#normalize-taxonomy}¶

Convert lineage and traits into unified visual parameters. Each taxonomic level contributes specific attributes:

Step 2: Apply Visual Grammar {#visual-grammar}¶

Each organism is defined by a structured visual grammar:

icon = {
  shape: polygon (from kingdom),
  fill: gradient (from class),
  pattern: overlay (from phylum),
  outline: stroke (from family),
  symmetry: mode (from order),
  motif: internal symbol (from genus),
  seed: genome hash (for deterministic variation)
}

Step 3: Deterministic Randomization {#deterministic-randomization}¶

• Seeded from genome.hash (converted to integer)
• Drives minor randomness in:
• Color rotation within palette range
• Geometry jitter (vertex offset)
• Pattern density or noise frequency

Ensures distinct icons for different genomes of the same species without breaking species-level consistency.

Step 4: Rendering {#rendering}¶

Icons are output as SVG files (vector), optionally rasterized to PNG for thumbnails. The implementation uses:

• svgwrite for geometry
• noise for procedural jitter
• Pillow for rasterization

Visual Mapping Tables {#visual-mapping}¶

Kingdom → Base Shape {#kingdom-shapes}¶

Phylum → Pattern Overlay {#phylum-patterns}¶

Class → Primary Color Palette {#class-palettes}¶

Order → Symmetry {#order-symmetry}¶

Family → Outline Style {#family-outlines}¶

Genus → Internal Motif {#genus-motifs}¶

Traits → Overlays {#trait-overlays}¶

Example Generation {#example-generation}¶

Taxonomy Input:
- Kingdom: Digitalis Anomalica → irregular hexagon
- Phylum: Polymorphid → fractal mesh overlay
- Class: Migrata → blue/teal gradient
- Order: Linearis → bilateral symmetry
- Family: Standardidae → solid border
- Genus: Replicatus → mirrored ellipse motif
- Species: vulgaris → seed 0bde9fec

Traits: replication, memory, environment, task, energy
→ Adds central twin ring + grid + radiating halo.

Result:
A bilateral blue-teal hexagonal symbol with mirrored ellipses, faint fractal lines, and glowing edges.

Output Format {#output-format}¶

• Default: SVG (vector, 256×256)
• Optional: PNG (512×512 or 64×64 thumbnail)
• Metadata appended to filename: Replicatus_vulgaris_Digitalis_Anomalica.svg

Each icon embeds a metadata block:

<metadata>
  <lineage>
    <kingdom>Digitalis Anomalica</kingdom>
    <genus>Replicatus</genus>
    <species>Replicatus vulgaris</species>
  </lineage>
  <traits>
    <replication>true</replication>
    <task_solving>true</task_solving>
  </traits>
  <genome_hash>0bde9fec</genome_hash>
</metadata>

Implementation {#implementation}¶

The icon generator is implemented in src/bytebiota/ui/icon_generator.py and integrated into the server:

# @wiki: wiki/icon-system.md#server-integration
class DistributedServer:
    def __init__(self, config: ServerConfig):
        # Initialize icon generator
        self.icon_generator = ByteBiotaIconGenerator()

The server provides an API endpoint for icon generation:

```python

@wiki: wiki/icon-system.md#api-endpoint¶

@self.app.get("/api/organism/{organism_id}/icon")
async def get_organism_icon(organism_id: int):
"""Get organism icon path."""
organism_data = self.state_aggregator.get_organism_data(organism_id)
icon_path = self.icon_generator.generate_icon_for_classification(organism_data)
return {"icon_path": f"/static/icons/{icon_filename}"}
```

Implementation Notes {#implementation-notes}¶

• Use SHA256(genome_hash) to seed the RNG for color/pattern variations
• All geometry scaled to fit 200×200 coordinate space
• Palette hues are generated via HSL; lightness modulated by trait count
• Avoid pure black/white to preserve UI contrast
• Optionally export to a shared /assets/icons/ folder per kingdom

Extension Ideas {#extension-ideas}¶

• Phylogenetic color blending: Shared hue range within genus
• Animated variants: Subtle rotation or pulse to indicate active simulations
• Interactive web layer: Hover reveals lineage and dominant traits

Related files: src/bytebiota/ui/icon_generator.py, src/bytebiota/server/server.py.