@naniteninja/trait-visual 1.0.1

package/README.md

@@ -0,0 +1,216 @@
+# @naniteninja/trait-visual
+
+An Angular library for visualizing trait-based relationships in 3D space using Three.js. This library provides a pure visualization component that can be integrated into any Angular application to display personality traits, preferences, and attributes as an interactive 3D visualization.
+
+## Installation
+
+```bash
+npm install @naniteninja/trait-visual
+```
+
+## Requirements
+
+- Angular 19.2.0 or higher
+- Three.js (included as dependency)
+- ml-pca (included as dependency)
+
+## Quick Start
+
+### 1. Import the Component
+
+```typescript
+import { TraitVisualComponent } from '@naniteninja/trait-visual';
+
+@Component({
+  selector: 'app-my-component',
+  standalone: true,
+  imports: [TraitVisualComponent],
+  template: `
+    <tv-trait-visual
+      [nodeData]="myNodeData"
+      [attributeWeights]="myAttributeWeights"
+      [preferenceWeights]="myPreferenceWeights"
+    ></tv-trait-visual>
+  `
+})
+export class MyComponent {
+  // Your component logic
+}
+```
+
+### 2. Prepare Your Data
+
+```typescript
+import { INodeData } from '@naniteninja/trait-visual';
+
+const myNodeData: INodeData[] = [
+  {
+    id: 1,
+    name: 'Central Node',
+    initialPosition: [0, 0, 0],
+    isSun: true,
+    color: '#C300FF',
+    attributes: { attr1: 50, attr2: 75, attr3: 25 },
+    preferences: { attr1: 100, attr2: 80, attr3: 60 }
+  },
+  {
+    id: 2,
+    name: 'Node 1',
+    initialPosition: [5, 0, 0],
+    isSun: false,
+    color: '#FF3366',
+    attributes: { attr1: 0, attr2: 50, attr3: 100 },
+    preferences: { attr1: 0, attr2: 0, attr3: 0 }
+  }
+  // ... more nodes
+];
+
+const myAttributeWeights = [1.0, 1.2, 0.8];
+const myPreferenceWeights = [1.0, 1.0, 1.0];
+```
+
+## API Reference
+
+### TraitVisualComponent
+
+The main visualization component.
+
+#### Inputs
+
+- `nodeData: INodeData[]` (required) - Array of node data to visualize
+- `attributeWeights?: number[]` - Weights for attribute calculations (optional)
+- `preferenceWeights?: number[]` - Weights for preference calculations (optional)
+- `attributeCount?: number` - Number of attributes per node (optional)
+- `preferenceCount?: number` - Number of preferences per node (optional)
+
+#### Usage
+
+```html
+<tv-trait-visual
+  [nodeData]="nodeData"
+  [attributeWeights]="attributeWeights"
+  [preferenceWeights]="preferenceWeights"
+></tv-trait-visual>
+```
+
+### Types
+
+#### INodeData
+
+```typescript
+interface INodeData {
+  id: number;
+  name: string;
+  initialPosition: [number, number, number];
+  isSun: boolean;
+  color: string;
+  attributes: IHumanAttributes;  // Record<string, number>
+  preferences: IHumanAttributes; // Record<string, number>
+}
+```
+
+#### IHumanAttributes
+
+```typescript
+interface IHumanAttributes {
+  [key: string]: number;
+}
+```
+
+### Configuration Utilities
+
+The library exports utility functions for working with node data:
+
+```typescript
+import { 
+  dynamicCounts, 
+  updateCounts, 
+  attributeWeights, 
+  nodeData 
+} from '@naniteninja/trait-visual';
+
+// Get current attribute/preference counts
+console.log(dynamicCounts.attributes); // 5
+console.log(dynamicCounts.preferences); // 5
+
+// Update counts
+updateCounts(7, 7);
+
+// Get computed attribute weights from PCA
+console.log(attributeWeights);
+
+// Get default node data (for reference)
+console.log(nodeData);
+```
+
+## Features
+
+- **3D Visualization**: Interactive Three.js-based 3D visualization
+- **PCA-based Positioning**: Nodes are positioned in 3D space using Principal Component Analysis
+- **Dynamic Updates**: Component reacts to input changes via Angular's change detection
+- **Customizable**: Full control over node data, weights, and attributes
+- **Standalone Component**: No additional module setup required
+
+## Example: Complete Integration
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { TraitVisualComponent, INodeData } from '@naniteninja/trait-visual';
+
+@Component({
+  selector: 'app-personality-visualizer',
+  standalone: true,
+  imports: [TraitVisualComponent],
+  template: `
+    <div style="width: 100vw; height: 100vh;">
+      <tv-trait-visual
+        [nodeData]="nodes"
+        [attributeWeights]="attrWeights"
+        [preferenceWeights]="prefWeights"
+      ></tv-trait-visual>
+    </div>
+  `
+})
+export class PersonalityVisualizerComponent implements OnInit {
+  nodes: INodeData[] = [];
+  attrWeights: number[] = [1, 1, 1, 1, 1];
+  prefWeights: number[] = [1, 1, 1, 1, 1];
+
+  ngOnInit() {
+    // Load or generate your node data
+    this.nodes = this.generateNodeData();
+  }
+
+  private generateNodeData(): INodeData[] {
+    // Your data generation logic
+    return [];
+  }
+}
+```
+
+## Styling
+
+The component uses minimal styling. You can style the wrapper element:
+
+```css
+tv-trait-visual {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+```
+
+The canvas will fill its container. Ensure the container has defined dimensions.
+
+## Browser Support
+
+- Modern browsers with WebGL support
+- Chrome, Firefox, Safari, Edge (latest versions)
+
+## License
+
+MIT
+
+## Author
+
+naniteninja