make new folder, subfolder of git, since images is too annoying to deal with

ConnectionManager.js

@@ -0,0 +1,230 @@
+/**
+ * ConnectionManager.js
+ * Manages connections (lines) between spheres
+ */
+
+class ConnectionManager {
+    constructor(scene) {
+        this.scene = scene;
+        this.connections = new Map();
+        this.connectionLines = new Map();
+        this.materials = new Map();
+    }
+
+    /**
+     * Create a connection between two spheres
+     * @param {string} id - Unique identifier for this connection
+     * @param {THREE.Vector3} startPos - Starting position
+     * @param {THREE.Vector3} endPos - Ending position
+     * @param {object} config - Configuration object
+     * @param {string} config.color - Hex color (default: '#00ff00')
+     * @param {number} config.lineWidth - Line width (default: 2)
+     * @param {string} config.fromSphere - Name of source sphere
+     * @param {string} config.toSphere - Name of target sphere
+     * @returns {THREE.Line} The created line object
+     */
+    addConnection(id, startPos, endPos, config = {}) {
+        // Prevent duplicate IDs
+        if (this.connections.has(id)) {
+            console.warn(`Connection "${id}" already exists.`);
+            return null;
+        }
+
+        const color = config.color || '#00ff00';
+        const lineWidth = config.lineWidth || 2;
+
+        // Create geometry
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute('position', new THREE.BufferAttribute(
+            new Float32Array([
+                startPos.x, startPos.y, startPos.z,
+                endPos.x, endPos.y, endPos.z
+            ]), 3
+        ));
+
+        // Create material
+        const material = new THREE.LineBasicMaterial({
+            color: new THREE.Color(color),
+            linewidth: lineWidth,
+            transparent: true,
+            opacity: 0.8
+        });
+
+        // Create line
+        const line = new THREE.Line(geometry, material);
+        line.name = id;
+        line.userData = {
+            connectionId: id,
+            fromSphere: config.fromSphere,
+            toSphere: config.toSphere,
+            color: color,
+            lineWidth: lineWidth,
+            startPos: startPos.clone(),
+            endPos: endPos.clone()
+        };
+
+        // Add to scene
+        this.scene.add(line);
+        this.connections.set(id, line.userData);
+        this.connectionLines.set(id, line);
+        this.materials.set(id, material);
+
+        // console.log(`✓ Connection added: ${id} (${config.fromSphere} -> ${config.toSphere})`);
+        return line;
+    }
+
+    /**
+     * Remove a connection
+     * @param {string} id - Connection ID
+     */
+    removeConnection(id) {
+        const line = this.connectionLines.get(id);
+        if (!line) {
+            console.warn(`Connection "${id}" not found.`);
+            return;
+        }
+
+        // Remove from scene
+        this.scene.remove(line);
+
+        // Clean up geometry and material
+        const geometry = line.geometry;
+        const material = this.materials.get(id);
+        if (geometry) geometry.dispose();
+        if (material) material.dispose();
+
+        // Remove from maps
+        this.connections.delete(id);
+        this.connectionLines.delete(id);
+        this.materials.delete(id);
+
+        // console.log(`✓ Connection removed: ${id}`);
+    }
+
+    /**
+     * Update connection position (useful for dynamic connections)
+     * @param {string} id - Connection ID
+     * @param {THREE.Vector3} startPos - New start position
+     * @param {THREE.Vector3} endPos - New end position
+     */
+    updateConnectionPositions(id, startPos, endPos) {
+        const line = this.connectionLines.get(id);
+        if (!line) return;
+
+        const positions = line.geometry.attributes.position.array;
+        positions[0] = startPos.x;
+        positions[1] = startPos.y;
+        positions[2] = startPos.z;
+        positions[3] = endPos.x;
+        positions[4] = endPos.y;
+        positions[5] = endPos.z;
+
+        line.geometry.attributes.position.needsUpdate = true;
+        line.userData.startPos = startPos.clone();
+        line.userData.endPos = endPos.clone();
+    }
+
+    /**
+     * Update connection color
+     * @param {string} id - Connection ID
+     * @param {string} newColor - New hex color
+     */
+    updateConnectionColor(id, newColor) {
+        const material = this.materials.get(id);
+        if (!material) return;
+
+        material.color.set(new THREE.Color(newColor));
+        this.connections.get(id).color = newColor;
+    }
+
+    /**
+     * Get connection by ID
+     * @param {string} id - Connection ID
+     * @returns {Object} Connection data
+     */
+    getConnection(id) {
+        return this.connections.get(id);
+    }
+
+    /**
+     * Get all connections
+     * @returns {Array} Array of all connections
+     */
+    getAllConnections() {
+        return Array.from(this.connections.entries()).map(([id, data]) => ({
+            id,
+            ...data,
+            line: this.connectionLines.get(id)
+        }));
+    }
+
+    /**
+     * Get connections for a specific sphere
+     * @param {string} sphereName - Name of the sphere
+     * @returns {Array} Connections connected to this sphere
+     */
+    getConnectionsForSphere(sphereName) {
+        return Array.from(this.connections.values()).filter(conn =>
+            conn.fromSphere === sphereName || conn.toSphere === sphereName
+        );
+    }
+
+    /**
+     * Remove all connections for a sphere (when sphere is deleted)
+     * @param {string} sphereName - Name of the sphere
+     */
+    removeConnectionsForSphere(sphereName) {
+        const connectionsToRemove = Array.from(this.connections.keys()).filter(id => {
+            const conn = this.connections.get(id);
+            return conn.fromSphere === sphereName || conn.toSphere === sphereName;
+        });
+
+        connectionsToRemove.forEach(id => this.removeConnection(id));
+    }
+
+    /**
+     * Add a pulse effect to a connection
+     * @param {string} id - Connection ID
+     * @param {number} duration - Duration of pulse in ms
+     */
+    pulseConnection(id, duration = 500) {
+        const material = this.materials.get(id);
+        if (!material) return;
+
+        const startOpacity = material.opacity;
+        const startTime = Date.now();
+
+        const animate = () => {
+            const elapsed = Date.now() - startTime;
+            const progress = (elapsed % duration) / duration;
+            const opacityPulse = Math.sin(progress * Math.PI * 2);
+
+            material.opacity = startOpacity + opacityPulse * 0.2;
+
+            if (elapsed < duration * 2) {
+                requestAnimationFrame(animate);
+            } else {
+                material.opacity = startOpacity;
+            }
+        };
+
+        animate();
+    }
+
+    /**
+     * Clear all connections
+     */
+    clearAll() {
+        const ids = Array.from(this.connections.keys());
+        ids.forEach(id => this.removeConnection(id));
+        console.log('✓ All connections cleared');
+    }
+
+    /**
+     * Get connection count
+     * @returns {number}
+     */
+    getCount() {
+        return this.connections.size;
+    }
+}

CustomNeuralNetwork.js

@@ -0,0 +1,234 @@
+/**
+ * Helper functions for Neural Network Math
+ */
+const sigmoid = (z) => {
+    // z can be a number or a matrix (array of arrays)
+    if (Array.isArray(z)) {
+        return z.map(row => row.map(val => 1.0 / (1.0 + Math.exp(-val))));
+    }
+    return 1.0 / (1.0 + Math.exp(-z));
+};
+
+const sigmoidDerivative = (z) => {
+    const s = sigmoid(z);
+    if (Array.isArray(s)) {
+        return s.map(row => row.map(val => val * (1 - val)));
+    }
+    return s * (1 - s);
+};
+
+/**
+ * Basic Matrix Operations (Numpy equivalents)
+ */
+const Matrix = {
+    // Dot product of two matrices
+    dot: (a, b) => {
+        let result = new Array(a.length).fill(0).map(() => new Array(b[0].length).fill(0));
+        return result.map((row, i) => {
+            return row.map((val, j) => {
+                return a[i].reduce((sum, elm, k) => sum + (elm * b[k][j]), 0);
+            });
+        });
+    },
+    // Element-wise addition
+    add: (a, b) => a.map((row, i) => row.map((val, j) => val + b[i][j])),
+    // Element-wise subtraction
+    subtract: (a, b) => a.map((row, i) => row.map((val, j) => val - b[i][j])),
+    // Element-wise multiplication (Hadamard product)
+    multiply: (a, b) => a.map((row, i) => row.map((val, j) => val * b[i][j])),
+    // Scalar multiplication
+    scale: (a, factor) => a.map(row => row.map(val => val * factor)),
+    // Transpose
+    transpose: (a) => a[0].map((col, i) => a.map(row => row[i])),
+    // Initialize with random Gaussian (standard normal)
+    random: (rows, cols) => {
+        return new Array(rows).fill(0).map(() => 
+            new Array(cols).fill(0).map(() => {
+                // Box-Muller transform for Gaussian distribution
+                let u = 0, v = 0;
+                while(u === 0) u = Math.random();
+                while(v === 0) v = Math.random();
+                return Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
+            })
+        );
+    },
+    zeros: (rows, cols) => new Array(rows).fill(0).map(() => new Array(cols).fill(0)),
+    argmax: (matrix) => {
+        let flat = matrix.map(row => row[0]);
+        return flat.indexOf(Math.max(...flat));
+    }
+};
+
+
+
+class Network {
+    constructor(neuronCounts) {
+        this.numLayers = neuronCounts.length;
+        this.neuronCounts = neuronCounts;
+        
+        // Biases for layers 1 to n (input layer 0 has no bias)
+        this.biases = neuronCounts.slice(1).map(count => Matrix.random(count, 1));
+        
+        // Weights for layer pairs
+        this.weights = [];
+        for (let i = 0; i < neuronCounts.length - 1; i++) {
+            this.weights.push(Matrix.random(neuronCounts[i+1], neuronCounts[i]));
+        }
+    }
+
+    feedforward(inputVector) {
+        let a = inputVector; // inputVector should be a 2D array: [[val], [val]]
+        for (let i = 0; i < this.weights.length; i++) {
+            const wa_plus_b = Matrix.add(Matrix.dot(this.weights[i], a), this.biases[i]);
+            a = sigmoid(wa_plus_b);
+        }
+        return a;
+    }
+
+    // SGD(trainingData, epochs, miniBatchSize, learningRate, testData = null) {
+    //     for (let j = 0; j < epochs; j++) {
+    //         // Shuffle training data
+    //         for (let i = trainingData.length - 1; i > 0; i--) {
+    //             const k = Math.floor(Math.random() * (i + 1));
+    //             [trainingData[i], trainingData[k]] = [trainingData[k], trainingData[i]];
+    //         }
+
+    //         // Create mini batches
+    //         for (let k = 0; k < trainingData.length; k += miniBatchSize) {
+    //             const miniBatch = trainingData.slice(k, k + miniBatchSize);
+    //             this.updateMiniBatch(miniBatch, learningRate);
+    //         }
+
+    //         if (testData) {
+    //             console.log(`Epoch ${j}: ${this.evaluate(testData)} / ${testData.length}`);
+    //         } else {
+    //             console.log(`Epoch ${j} complete`);
+    //         }
+    //     }
+    // }
+    async SGD_single_epoch(trainingData, miniBatchSize, learningRate, testData, visualizer_function) {
+        // Shuffle training data
+        for (let i = trainingData.length - 1; i > 0; i--) {
+            const k = Math.floor(Math.random() * (i + 1));
+            [trainingData[i], trainingData[k]] = [trainingData[k], trainingData[i]];
+        }
+
+        const minibatchCounterDiv = document.getElementById('minibatchCounter');
+        const totalMiniBatches = Math.ceil(trainingData.length / miniBatchSize);
+        let minibatchCounter = 0;
+
+        // Process mini batches asynchronously to allow UI updates
+        for (let k = 0; k < trainingData.length; k += miniBatchSize) {
+            const miniBatch = trainingData.slice(k, k + miniBatchSize);
+            this.updateMiniBatch(miniBatch, learningRate);
+
+            minibatchCounter++;
+            
+            // Update UI every 10 batches or on last batch
+            //if (minibatchCounter % 10 === 0 || k + miniBatchSize >= trainingData.length) {
+                //if (minibatchCounterDiv) {
+                    minibatchCounterDiv.textContent = `Mini-batch: ${minibatchCounter} / ${totalMiniBatches}`;
+                //}
+                // Allow UI to update
+                await new Promise(resolve => setTimeout(resolve, 0));
+            //}
+        }
+
+        // Update test data evaluation
+        const accuracy = this.evaluate(testData);
+        console.log(`Epoch complete: ${accuracy} / ${testData.length}`);
+        
+        const evalDiv = document.getElementById('accuracyValue');
+        if (evalDiv) {
+            evalDiv.textContent = `${accuracy} / ${testData.length} = ${(accuracy / testData.length * 100).toFixed(2)}%`;
+        }
+
+        // Reset minibatch counter display
+        if (minibatchCounterDiv) {
+            minibatchCounterDiv.textContent = `Ready`;
+        }
+
+        // Visualizer function call
+        visualizer_function(this.getParameters());
+    }
+
+    updateMiniBatch(miniBatch, learningRate) {
+        let accB = this.biases.map(b => Matrix.zeros(b.length, b[0].length));
+        let accW = this.weights.map(w => Matrix.zeros(w.length, w[0].length));
+
+        for (const [x, y] of miniBatch) {
+            const [deltaGradB, deltaGradW] = this.backpropagation(x, y);
+            accB = accB.map((b, i) => Matrix.add(b, deltaGradB[i]));
+            accW = accW.map((w, i) => Matrix.add(w, deltaGradW[i]));
+        }
+
+        const eta_m = learningRate / miniBatch.length;
+        this.weights = this.weights.map((w, i) => Matrix.subtract(w, Matrix.scale(accW[i], eta_m)));
+        this.biases = this.biases.map((b, i) => Matrix.subtract(b, Matrix.scale(accB[i], eta_m)));
+    }
+
+    backpropagation(x, y) {
+        let gradB = this.biases.map(b => Matrix.zeros(b.length, b[0].length));
+        let gradW = this.weights.map(w => Matrix.zeros(w.length, w[0].length));
+
+        // Feedforward
+        let activation = x;
+        let activations = [x];
+        let logits = [];
+
+        for (let i = 0; i < this.weights.length; i++) {
+            let z = Matrix.add(Matrix.dot(this.weights[i], activation), this.biases[i]);
+            logits.push(z);
+            activation = sigmoid(z);
+            activations.push(activation);
+        }
+
+        // Backward pass
+        // Output error
+        let delta = Matrix.multiply(
+            this.costDerivative(activations[activations.length - 1], y),
+            sigmoidDerivative(logits[logits.length - 1])
+        );
+        gradB[gradB.length - 1] = delta;
+        gradW[gradW.length - 1] = Matrix.dot(delta, Matrix.transpose(activations[activations.length - 2]));
+
+        // Propagate backwards through layers
+        for (let l = 2; l < this.numLayers; l++) {
+            const z = logits[logits.length - l];
+            const sp = sigmoidDerivative(z);
+            delta = Matrix.multiply(
+                Matrix.dot(Matrix.transpose(this.weights[this.weights.length - l + 1]), delta),
+                sp
+            );
+            gradB[gradB.length - l] = delta;
+            gradW[gradW.length - l] = Matrix.dot(delta, Matrix.transpose(activations[activations.length - l - 1]));
+        }
+
+        return [gradB, gradW];
+    }
+
+    evaluate(testData) {
+        let correctCount = 0;
+        for (const [x, y] of testData) {
+            const output = this.feedforward(x);
+            //console.log(`Output; ${Matrix.argmax(output)}, Expected: ${y}; ${y.indexOf(1)}; ${Matrix.argmax(y)}`);
+            //y is column vector one-hot encoded, so we use argmax to get the index. indexOf assume is 1D array, this is 2D array. 
+            if (Matrix.argmax(output) == Matrix.argmax(y)) {
+                correctCount++;
+            }
+        }
+        return correctCount;
+    }
+
+    costDerivative(outputActivations, y) {
+        return Matrix.subtract(outputActivations, y);
+    }
+
+
+    getParameters() {
+        return {
+            biases: this.biases,
+            weights: this.weights
+        };
+    }
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hongcheng Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MNIST_dataset.js

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * =============================================================================
+ */
+
+const IMAGE_SIZE = 784;
+const NUM_CLASSES = 10;
+const NUM_DATASET_ELEMENTS = 65000;
+
+const NUM_TRAIN_ELEMENTS = 55000;
+const NUM_TEST_ELEMENTS = NUM_DATASET_ELEMENTS - NUM_TRAIN_ELEMENTS;
+
+const MNIST_IMAGES_SPRITE_PATH =
+    'https://storage.googleapis.com/learnjs-data/model-builder/mnist_images.png';
+const MNIST_LABELS_PATH =
+    'https://storage.googleapis.com/learnjs-data/model-builder/mnist_labels_uint8';
+
+/**
+ * A class that fetches the sprited MNIST dataset and returns shuffled batches.
+ *
+ * NOTE: This will get much easier. For now, we do data fetching and
+ * manipulation manually.
+ */
+class MnistData {
+  constructor() {
+    this.shuffledTrainIndex = 0;
+    this.shuffledTestIndex = 0;
+  }
+
+  async load() {
+    // Make a request for the MNIST sprited image.
+    const img = new Image();
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    const imgRequest = new Promise((resolve, reject) => {
+      img.crossOrigin = '';
+      img.onload = () => {
+        img.width = img.naturalWidth;
+        img.height = img.naturalHeight;
+
+        const datasetBytesBuffer =
+            new ArrayBuffer(NUM_DATASET_ELEMENTS * IMAGE_SIZE * 4);
+
+        const chunkSize = 5000;
+        canvas.width = img.width;
+        canvas.height = chunkSize;
+
+        for (let i = 0; i < NUM_DATASET_ELEMENTS / chunkSize; i++) {
+          const datasetBytesView = new Float32Array(
+              datasetBytesBuffer, i * IMAGE_SIZE * chunkSize * 4,
+              IMAGE_SIZE * chunkSize);
+          ctx.drawImage(
+              img, 0, i * chunkSize, img.width, chunkSize, 0, 0, img.width,
+              chunkSize);
+
+          const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+
+          for (let j = 0; j < imageData.data.length / 4; j++) {
+            // All channels hold an equal value since the image is grayscale, so
+            // just read the red channel.
+            datasetBytesView[j] = imageData.data[j * 4] / 255;
+          }
+        }
+        this.datasetImages = new Float32Array(datasetBytesBuffer);
+
+        resolve();
+      };
+      img.src = MNIST_IMAGES_SPRITE_PATH;
+    });
+
+    const labelsRequest = fetch(MNIST_LABELS_PATH);
+    const [imgResponse, labelsResponse] =
+        await Promise.all([imgRequest, labelsRequest]);
+
+    this.datasetLabels = new Uint8Array(await labelsResponse.arrayBuffer());
+
+    // Create shuffled indices into the train/test set for when we select a
+    // random dataset element for training / validation.
+    this.trainIndices = tf.util.createShuffledIndices(NUM_TRAIN_ELEMENTS);
+    this.testIndices = tf.util.createShuffledIndices(NUM_TEST_ELEMENTS);
+
+    // Slice the the images and labels into train and test sets.
+    this.trainImages =
+        this.datasetImages.slice(0, IMAGE_SIZE * NUM_TRAIN_ELEMENTS);
+    this.testImages = this.datasetImages.slice(IMAGE_SIZE * NUM_TRAIN_ELEMENTS);
+    this.trainLabels =
+        this.datasetLabels.slice(0, NUM_CLASSES * NUM_TRAIN_ELEMENTS);
+    this.testLabels =
+        this.datasetLabels.slice(NUM_CLASSES * NUM_TRAIN_ELEMENTS);
+  }
+
+  nextTrainBatch(batchSize) {
+    return this.nextBatch(
+        batchSize, [this.trainImages, this.trainLabels], () => {
+          this.shuffledTrainIndex =
+              (this.shuffledTrainIndex + 1) % this.trainIndices.length;
+          return this.trainIndices[this.shuffledTrainIndex];
+        });
+  }
+
+  nextTestBatch(batchSize) {
+    return this.nextBatch(batchSize, [this.testImages, this.testLabels], () => {
+      this.shuffledTestIndex =
+          (this.shuffledTestIndex + 1) % this.testIndices.length;
+      return this.testIndices[this.shuffledTestIndex];
+    });
+  }
+
+  nextBatch(batchSize, data, index) {
+    const batchImagesArray = new Float32Array(batchSize * IMAGE_SIZE);
+    const batchLabelsArray = new Uint8Array(batchSize * NUM_CLASSES);
+
+    for (let i = 0; i < batchSize; i++) {
+      const idx = index();
+
+      const image =
+          data[0].slice(idx * IMAGE_SIZE, idx * IMAGE_SIZE + IMAGE_SIZE);
+      batchImagesArray.set(image, i * IMAGE_SIZE);
+
+      const label =
+          data[1].slice(idx * NUM_CLASSES, idx * NUM_CLASSES + NUM_CLASSES);
+      batchLabelsArray.set(label, i * NUM_CLASSES);
+    }
+
+    const xs = tf.tensor2d(batchImagesArray, [batchSize, IMAGE_SIZE]);
+    const labels = tf.tensor2d(batchLabelsArray, [batchSize, NUM_CLASSES]);
+
+    return {xs, labels};
+  }
+}

NetworkToDisplay.js

@@ -0,0 +1,191 @@
+/**
+ * NetworkToDisplay - Interface between neural network and 3D visualization
+ * Creates spheres and manages connections directly in the SceneManager.
+ */
+class NetworkToDisplay {
+    constructor(network, sceneManager, options = {}) {
+        this.network = network;
+        this.sceneManager = sceneManager;
+
+        const {
+            layerSpacing = 10,
+            neuronSpacing = 2,
+            neuronRadius = 0.5,
+            inputColor = '#ff6b6b',
+            hiddenColor = '#ffd93d',
+            outputColor = '#4ecdc4',
+            weightThreshold = 0.1,
+            lineWidth = 0.1,
+            opacity = 0.1
+        } = options;
+
+        this.layerSpacing = layerSpacing;
+        this.neuronSpacing = neuronSpacing;
+        this.neuronRadius = neuronRadius;
+        this.inputColor = inputColor;
+        this.hiddenColor = hiddenColor;
+        this.outputColor = outputColor;
+        this.weightThreshold = weightThreshold;
+        this.lineWidth = lineWidth;
+        this.opacity = opacity;
+    }
+
+    /**
+     * Create all neuron spheres and initial connections in the scene.
+     */
+    initialGeneration() {
+        const layers = this.network.neuronCounts;
+        const numLayers = layers.length;
+
+        for (let layerIdx = 0; layerIdx < numLayers; layerIdx++) {
+            const neuronCount = layers[layerIdx];
+            const x = layerIdx * this.layerSpacing - (numLayers - 1) * this.layerSpacing / 2;
+
+            let color = this.hiddenColor;
+            if (layerIdx === 0) color = this.inputColor;
+            else if (layerIdx === numLayers - 1) color = this.outputColor;
+
+            if (layerIdx === 0) {
+                const gridSize = Math.sqrt(neuronCount);
+                console.assert(
+                    Math.floor(gridSize) * Math.floor(gridSize) === neuronCount,
+                    `Input layer neuron count ${neuronCount} is not a perfect square`
+                );
+
+                const intGridSize = Math.floor(gridSize);
+                const halfSize = (intGridSize - 1) * this.neuronSpacing / 2;
+                let sphereCount = 0;
+
+                for (let row = 0; row < intGridSize; row++) {
+                    for (let col = 0; col < intGridSize; col++) {
+                        const y = row * this.neuronSpacing - halfSize;
+                        const z = col * this.neuronSpacing - halfSize;
+
+                        this.sceneManager.sphereManager.addSphere(`L${layerIdx}_N${sphereCount}`, {
+                            radius: this.neuronRadius,
+                            color: color,
+                            position: new THREE.Vector3(x, y, z),
+                            opacity: 1
+                        });
+                        sphereCount++;
+                    }
+                }
+
+                console.assert(
+                    sphereCount === neuronCount,
+                    `Generated ${sphereCount} spheres but expected ${neuronCount} neurons in input layer`
+                );
+            } else {
+                const verticalOffset = -(neuronCount - 1) * this.neuronSpacing / 2;
+
+                for (let neuronIdx = 0; neuronIdx < neuronCount; neuronIdx++) {
+                    const y = verticalOffset + neuronIdx * this.neuronSpacing;
+
+                    this.sceneManager.sphereManager.addSphere(`L${layerIdx}_N${neuronIdx}`, {
+                        radius: this.neuronRadius,
+                        color: color,
+                        position: new THREE.Vector3(x, y, 0),
+                        opacity: 1
+                    });
+                }
+            }
+        }
+
+        this.updateConnections();
+        console.log('✓ Initial generation complete');
+    }
+
+    /**
+     * Update/create/delete connections in the scene based on current weights.
+     */
+    updateConnections() {
+        const weightThreshold = this.weightThreshold;
+
+        for (let layerIdx = 0; layerIdx < this.network.weights.length; layerIdx++) {
+            const weightMatrix = this.network.weights[layerIdx];
+            const fromLayer = layerIdx;
+            const toLayer = layerIdx + 1;
+            const toNeuronCount = weightMatrix.length;
+            const fromNeuronCount = weightMatrix[0].length;
+
+            for (let toIdx = 0; toIdx < toNeuronCount; toIdx++) {
+                for (let fromIdx = 0; fromIdx < fromNeuronCount; fromIdx++) {
+                    const weight = weightMatrix[toIdx][fromIdx];
+                    const weightMagnitude = Math.abs(weight);
+                    const connectionId = `W_L${layerIdx}_F${fromIdx}_T${toIdx}`;
+                    const fromName = `L${fromLayer}_N${fromIdx}`;
+                    const toName = `L${toLayer}_N${toIdx}`;
+
+                    const existing = this.sceneManager.connectionManager.getConnection(connectionId);
+
+                    if (weightMagnitude < weightThreshold) {
+                        if (existing) {
+                            this.sceneManager.connectionManager.removeConnection(connectionId);
+                        }
+                        continue;
+                    }
+
+                    const connectionColorThis = NetworkToDisplay.weightToColor(weight);
+
+                    if (existing) {
+                        this.sceneManager.connectionManager.updateConnectionColor(connectionId, connectionColorThis);
+                    } else {
+                        const fromSphere = this.sceneManager.sphereManager.getSphere(fromName);
+                        const toSphere = this.sceneManager.sphereManager.getSphere(toName);
+
+                        if (fromSphere && toSphere) {
+                            this.sceneManager.connectionManager.addConnection(
+                                connectionId,
+                                fromSphere.position,
+                                toSphere.position,
+                                {
+                                    color: connectionColorThis,
+                                    lineWidth: this.lineWidth,
+                                    opacity: this.opacity,
+                                    fromSphere: fromName,
+                                    toSphere: toName,
+                                    weight: weight
+                                }
+                            );
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Highlight a specific neuron activation
+     * @param {number} layerIdx - Layer index
+     * @param {number} neuronIdx - Neuron index
+     * @param {number} activation - Activation value (0-1)
+     */
+    highlightNeuron(layerIdx, neuronIdx, activation) {
+        const sphereName = `L${layerIdx}_N${neuronIdx}`;
+        const sphere = this.sceneManager.sphereManager.getSphere(sphereName);
+
+        if (sphere) {
+            const scale = 1 + activation * 0.5;
+            sphere.scale.set(scale, scale, scale);
+        }
+    }
+
+    static weightToColor(weight) {
+        const positiveColor = { r: 0, g: 255, b: 0 }; // Green for positive weights
+        const neutralColor = { r: 255, g: 255, b: 255 }; // White for neutral weights
+        const negativeColor = { r: 255, g: 0, b: 0 }; // Red for negative weights
+
+        const magnitude = Math.min(1, Math.abs(weight) / 3); // Normalize weight magnitude
+
+        // Interpolate between neutral and sign-specific color
+        const target = weight >= 0 ? positiveColor : negativeColor;
+        const r = Math.round(neutralColor.r * (1 - magnitude) + target.r * magnitude);
+        const g = Math.round(neutralColor.g * (1 - magnitude) + target.g * magnitude);
+        const b = Math.round(neutralColor.b * (1 - magnitude) + target.b * magnitude);
+
+        return `#${((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1)}`;
+    }
+}
+
+// Expose globally for script-tag usage
+window.NetworkToDisplay = NetworkToDisplay;

README.md

@@ -1,11 +1,271 @@
----
-title: Simple Neural Network Visualizer
-emoji: 🐨
-colorFrom: yellow
-colorTo: red
-sdk: static
-pinned: false
-short_description: 'visualize a densely connected neural network with training. '
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Future Enhancements
+
+- [ ] Real-time training animation via epochs -> change in colors. 
+- [ ] Layer-specific zoom focus
+- [ ] Neuron activation heatmap
+- [ ] Weight magnitude visualization
+- [ ] input / output bars
+
+
+# Custom Neural Network Visualizer
+
+A 3D interactive visualization of a neural network trained on MNIST handwritten digit recognition. This project combines a custom-built neural network implementation with Three.js to create an immersive visualization of network architecture, weights, and connections.
+
+**Purpose:** Visualization of actual model architecture is often lacking in machine learning. This project demonstrates what real-time neural network training looks like in 3D space, with dynamic weight updates and color-coded connections.
+
+Stopped now: Entire simple model of sigmoid neural networks is in js. turns out people don't visualize this because it's a pain in the ass. so much pain. 
+
+demo: 
+![Demo image](Demo.png "demonstration image on UI")
+
+
+## Features
+
+- **Custom Neural Network**: Fully implemented backpropagation neural network from scratch in pure JavaScript (no ML frameworks)
+- **MNIST Training**: Load and preprocess MNIST dataset (55,000 training samples, 10,000 test samples)
+- **3D Visualization**: Interactive Three.js scene showing network architecture in 3D space
+- **Input Layer Grid**: Input layer (784 neurons) displayed as a 28×28 grid (matching MNIST image dimensions)
+- **Dynamic Weight Visualization**: Connections colored by weight sign and magnitude
+  - **Green**: Positive weights (excitatory connections)
+  - **Red**: Negative weights (inhibitory connections)  
+  - **White**: Neutral/weak weights
+- **Real-time Training Updates**: Weights update color dynamically as network trains
+- **Smart Connection Management**: Weak weights below threshold are automatically hidden; strong weights are shown/created dynamically
+- **Interactive HUD**: Top bar displays:
+  - Epoch counter (starts at 0)
+  - Mini-batch progress counter
+  - Real-time accuracy percentage
+  - Training control buttons
+- **Interactive Camera**: OrbitControls for smooth 3D navigation with reset button
+- **Async Training**: Non-blocking training with UI updates every 10 mini-batches
+
+## Project Structure
+
+```
+├── CustomNeuralNetwork.js      # Neural network implementation with backpropagation
+├── MNIST_dataset.js             # MNIST data loading from Google Cloud
+├── preprocessing.js             # Data preprocessing and reshaping
+├── NetworkToDisplay.js          # Converts network to 3D scene configuration
+├── SceneManager.js              # Three.js scene, camera, and lighting setup
+├── SphereManager.js             # Creates and manages neuron spheres
+├── ConnectionManager.js          # Creates and manages weight connections
+├── main.js                      # Entry point and training orchestration
+├── index.html                   # HTML page with canvas
+└── README.md                    # This file
+```
+
+## Architecture
+
+### Neural Network (CustomNeuralNetwork.js)
+
+Custom implementation featuring:
+- **Matrix operations**: Dot product, element-wise operations, transpose
+- **Activation functions**: Sigmoid activation with derivatives
+- **Training**: Stochastic Gradient Descent (SGD) with mini-batches
+- **Backpropagation**: Full backpropagation algorithm for weight updates
+- **Evaluation**: Accuracy testing on test data
+
+```javascript
+// Example usage
+const network = new Network([784, 16, 16, 10]); // Input, hidden, hidden, output
+network.SGD(trainingData, epochs, batchSize, learningRate, testData);
+```
+
+### Data Pipeline (preprocessing.js)
+
+Loads MNIST data and formats it for the network:
+1. Fetches image sprites and labels from Google Cloud Storage
+2. Reshapes flat 784-element arrays into column vectors `[[val], [val], ...]`
+3. Prepares one-hot encoded labels
+4. Returns `{trainingData, testData}` ready for training
+
+### Visualization (NetworkToDisplay.js)
+
+Instance-based class that creates and updates the 3D scene directly:
+- **Neurons**: Represented as spheres with layer-specific colors
+  - Red: Input layer (28×28 grid)
+  - Yellow: Hidden layers (vertical line)
+  - Cyan: Output layer (vertical line for 10 classes)
+- **Connections**: Dynamically managed based on weight magnitude
+  - **Color coding by weight sign:**
+    - Green: Positive weights (excitatory)
+    - Red: Negative weights (inhibitory)
+    - White: Neutral weights
+  - **Smart visibility:** Connections below `weightThreshold` (default 0.1) are automatically hidden
+  - **Dynamic updates:** `updateConnections()` creates new strong connections and removes weak ones in real-time
+
+### 3D Scene Management (SceneManager.js)
+
+Provides Three.js scene setup with:
+- Perspective camera with orbit controls
+- Ambient and directional lighting with atmospheric point lights
+- Fog effect for depth perception
+- Real-time rendering loop with connection position updates
+- Window resize handling
+- Camera reset functionality (removes momentum/velocity)
+
+## Usage
+
+### Basic Setup
+
+1. Open `index.html` in a modern web browser
+2. Wait for MNIST dataset to load (automatic)
+3. The initial network architecture [784, 16, 16, 10] will be visualized immediately
+4. Click **"Next Epoch"** button to train for one epoch
+5. Watch as:
+   - Mini-batch counter updates in real-time
+   - Connections change color based on weight updates
+   - Accuracy percentage updates after each epoch
+   - Epoch counter increments
+
+### Interactive Controls
+
+**Mouse Controls:**
+- **Left-click + drag**: Rotate view
+- **Right-click + drag**: Pan camera
+- **Mouse scroll**: Zoom in/out
+
+**HUD Controls:**
+- **Next Epoch button**: Train network for one epoch (async, non-blocking)
+- **Reset Camera button**: Return camera to initial position and stop momentum
+
+### Custom Network Configuration
+
+Edit `main.js` to modify network architecture and training parameters:
+
+```javascript
+// Change network architecture
+const network = new Network([784, 32, 32, 16, 10]);
+
+// Adjust visualization parameters
+const visualizer = new NetworkToDisplay(network, sceneManager, {
+    layerSpacing: 10,
+    neuronSpacing: 2,
+    neuronRadius: 0.5,
+    inputColor: '#ff6b6b',
+    hiddenColor: '#ffd93d',
+    outputColor: '#4ecdc4',
+    weightThreshold: 0.1,    // Hide connections below this weight magnitude
+    lineWidth: 0.1,
+    opacity: 0.1
+});
+
+// Modify training parameters in the button click handler
+network.SGD_single_epoch(trainingData, miniBatchSize=100, learningRate=0.5, testData, visualizer_function);
+```
+
+## Data Format
+
+### Training Data
+
+Each sample is a pair `[x, y]`:
+- `x`: Column vector of 784 pixel values (normalized 0-1)
+  ```
+  [[0.5], [0.3], [0.8], ...]  // 784 elements
+  ```
+- `y`: One-hot encoded label (10 elements for digits 0-9)
+  ```
+  [[0], [0], [1], [0], ...] // For digit 2
+  ```
+
+### Network Weights
+
+- `weights[i]`: 2D array from layer i to layer i+1
+  - Dimensions: `[numNeuronsInLayerI+1, numNeuronsInLayerI]`
+  - `weights[i][j][k]`: Weight from neuron k in layer i to neuron j in layer i+1
+
+## Class Reference
+
+### Network
+
+```javascript
+// Constructor
+new Network(neuronCounts)  // e.g., [784, 16, 16, 10]
+
+// Methods
+feedforward(inputVector)                                           // Get network prediction
+SGD_single_epoch(trainingData, miniBatchSize, lr, testData, cb)  // Train one epoch (async)
+evaluate(testData)                                                 // Count correct predictions
+backpropagation(x, y)                                             // Compute gradients
+```
+
+### SphereManager
+
+```javascript
+addSphere(name, config)           // Add neuron sphere
+removeSphere(name)                // Remove sphere
+updateSphere(name, config)        // Update sphere properties
+getSphere(name)                   // Get sphere mesh
+changeColorSmooth(name, color)    // Animate color change
+```
+
+### ConnectionManager
+
+```javascript
+addConnection(id, fromPos, toPos, config)  // Add weight connection
+removeConnection(id)                       // Remove connection
+updateConnectionPositions(id, from, to)   // Update endpoints
+```
+
+### NetworkToDisplay
+
+```javascript
+// Constructor (instance-based, not static)
+new NetworkToDisplay(network, sceneManager, options)
+
+// Methods
+initialGeneration()              // Create all spheres and initial connections in scene
+updateConnections()              // Update/create/delete connections based on current weights
+highlightNeuron(layer, neuron, activation)  // Highlight active neuron (instance method)
+```
+
+**Static Methods:**
+```javascript
+NetworkToDisplay.weightToColor(weight)  // Convert weight value to color (red/white/green gradient)
+```
+
+## Performance Considerations
+
+- **Input layer grid**: 28×28 = 784 neurons (no sampling)
+- **Dynamic connections**: Only connections with weights above threshold are rendered
+  - Initial: ~12,960 connections (784→16 + 16→16 + 16→10)
+  - Runtime: Varies based on weight magnitudes (weak connections hidden)
+- **Async training**: Mini-batches update UI every 10 iterations to prevent blocking
+- **Color updates**: Real-time weight-to-color conversion with interpolation
+- **Rendering**: Optimized for dynamic object creation/deletion with orbit controls
+
+
+## Dependencies
+
+- **Three.js r128**: 3D graphics library (loaded from CDN)
+- **OrbitControls**: Camera control extension for Three.js (loaded from CDN)
+- **TensorFlow.js 1.0.0**: Used only for MNIST data loading from Google Cloud Storage
+
+All dependencies are loaded via CDN - no installation required.
+
+## Future Enhancements
+
+- [ ] Layer-specific zoom focus
+- [ ] Neuron activation heatmap (color neurons by activation value during inference)
+- [ ] Input/output visualization bars showing sample images and predictions
+- [ ] Weight magnitude histogram
+- [ ] Training loss curve overlay
+- [ ] Export/import trained model weights
+- [ ] Multiple activation functions (ReLU, Tanh, etc.)
+- [ ] Adjustable learning rate during training
+
+
+
+## References
+
+- MNIST Dataset: [Yann LeCun's MNIST Database](http://yann.lecun.com/exdb/mnist/)
+- Three.js: [Three.js Documentation](https://threejs.org/docs/)
+- Neural Networks: [Neural Networks and Deep Learning](http://neuralnetworksanddeeplearning.com/)
+
+## License
+
+This is an educational project for learning machine learning and 3D visualization.
+
+## Author
+
+Created as part of a custom neural network learning project.

SceneManager.js

@@ -0,0 +1,212 @@
+
+class SceneManager {
+    constructor(config = {}) {
+        // Scene setup
+        this.scene = new THREE.Scene();
+        this.scene.background = new THREE.Color(config.backgroundColor || 0x0a0e27);
+        this.scene.fog = new THREE.Fog(config.backgroundColor || 0x0a0e27, 100, 1000);
+
+        // Camera setup
+        this.camera = new THREE.PerspectiveCamera(
+            75,
+            window.innerWidth / window.innerHeight,
+            0.1,
+            1000
+        );
+        this.camera.position.set(0, 0, config.cameraDistance || 15);
+
+        // Renderer setup
+        this.renderer = new THREE.WebGLRenderer({ 
+            canvas: document.getElementById('canvas'),
+            antialias: true,
+            alpha: true
+        });
+        this.renderer.setSize(window.innerWidth, window.innerHeight);
+        this.renderer.setPixelRatio(window.devicePixelRatio);
+        this.renderer.shadowMap.enabled = true;
+
+        // Lighting
+        this.setupLighting();
+
+        // Managers
+        this.sphereManager = new SphereManager(this.scene);
+        this.connectionManager = new ConnectionManager(this.scene);
+
+        // Controls
+        this.controls = new THREE.OrbitControls(this.camera, this.renderer.domElement);
+        this.controls.enableDamping = true;
+        this.controls.dampingFactor = 0.05;
+        this.controls.screenSpacePanning = false;
+        this.controls.minDistance = 5;
+        this.controls.maxDistance = 500;
+        this.controls.maxPolarAngle = Math.PI;
+
+        // Store initial camera state for reset
+        this.initialCameraPosition = this.camera.position.clone();
+        this.initialControlsTarget = new THREE.Vector3(0, 0, 0);
+
+        // Window resize listener
+        window.addEventListener('resize', () => this.onWindowResize());
+
+        // reset camera view button
+        const resetCameraButton = document.getElementById('resetCameraButton');
+        if (resetCameraButton) {
+            resetCameraButton.addEventListener('click', () => {
+                this.resetCameraView();
+            });
+        }
+
+        // Start animation loop
+        this.animate();
+
+        console.log('✓ Scene3D initialized');
+    }
+
+    /**
+     * Setup lighting for the scene
+     */
+    setupLighting() {
+        const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
+        this.scene.add(ambientLight);
+
+        // Directional light
+        const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
+        directionalLight.position.set(10, 10, 10);
+        directionalLight.castShadow = true;
+        directionalLight.shadow.mapSize.width = 2048;
+        directionalLight.shadow.mapSize.height = 2048;
+        this.scene.add(directionalLight);
+
+        // Point lights for atmosphere
+        const pointLight1 = new THREE.PointLight(0xff0080, 0.3, 100);
+        pointLight1.position.set(-10, 10, 10);
+        this.scene.add(pointLight1);
+
+        const pointLight2 = new THREE.PointLight(0x0080ff, 0.3, 100);
+        pointLight2.position.set(10, -10, 10);
+        this.scene.add(pointLight2);
+    }
+
+
+
+    /**
+     * Initialize scene from JSON configuration
+     * @param {Object} jsonConfig - Configuration with spheres and connections arrays
+     * 
+     * Example:
+     * {
+     *   spheres: [
+     *     { name: 'A', radius: 1, color: '#ff0000', position: { x: 0, y: 0, z: 0 } },
+     *     { name: 'B', radius: 1, color: '#00ff00', position: { x: 5, y: 0, z: 0 } }
+     *   ],
+     *   connections: [
+     *     { id: 'AB', from: 'A', to: 'B', color: '#ffff00', lineWidth: 2 }
+     *   ]
+     * }
+     */
+    loadFromJSON(jsonConfig) {
+        // Clear existing scene
+        this.sphereManager.clearAll();
+        this.connectionManager.clearAll();
+
+        // Add spheres
+        if (jsonConfig.spheres && Array.isArray(jsonConfig.spheres)) {
+            jsonConfig.spheres.forEach(sphereConfig => {
+                const position = new THREE.Vector3(
+                    sphereConfig.position?.x || 0,
+                    sphereConfig.position?.y || 0,
+                    sphereConfig.position?.z || 0
+                );
+
+                this.sphereManager.addSphere(sphereConfig.name, {
+                    radius: sphereConfig.radius || 1,
+                    color: sphereConfig.color || '#ff0000',
+                    position: position,
+                    opacity: sphereConfig.opacity || 1
+                });
+            });
+        }
+
+        // Add connections
+        if (jsonConfig.connections && Array.isArray(jsonConfig.connections)) {
+            jsonConfig.connections.forEach(connConfig => {
+                const fromSphere = this.sphereManager.getSphere(connConfig.from);
+                const toSphere = this.sphereManager.getSphere(connConfig.to);
+
+                if (fromSphere && toSphere) {
+                    this.connectionManager.addConnection(
+                        connConfig.id || `conn_${connConfig.from}_${connConfig.to}`,
+                        fromSphere.position,
+                        toSphere.position,
+                        {
+                            color: connConfig.color || '#00ff00',
+                            lineWidth: connConfig.lineWidth || 2,
+                            fromSphere: connConfig.from,
+                            toSphere: connConfig.to
+                        }
+                    );
+                } else {
+                    console.warn(`Connection ${connConfig.id}: sphere(s) not found`);
+                }
+            });
+        }
+
+        console.log('✓ Scene loaded from JSON');
+    }
+
+    /**
+     * Handle window resize
+     */
+    onWindowResize() {
+        this.camera.aspect = window.innerWidth / window.innerHeight;
+        this.camera.updateProjectionMatrix();
+        this.renderer.setSize(window.innerWidth, window.innerHeight);
+    }
+
+    resetCameraView() {
+        // Disable damping temporarily to stop momentum
+        const wasDamping = this.controls.enableDamping;
+        this.controls.enableDamping = false;
+
+        // Reset to initial positions
+        this.camera.position.copy(this.initialCameraPosition);
+        this.controls.target.copy(this.initialControlsTarget);
+
+        // Reset OrbitControls internal state (removes any stored rotations/pans)
+        this.controls.reset();
+
+        // Force immediate update without damping
+        this.controls.update();
+
+        // Re-enable damping
+        this.controls.enableDamping = wasDamping;
+
+        console.log('✓ Camera view reset');
+    }
+
+    /**
+     * Main animation loop
+     */
+    animate() {
+        requestAnimationFrame(() => this.animate());
+
+        // Update controls
+        this.controls.update();
+
+        // Update connection positions dynamically
+        this.connectionManager.getAllConnections().forEach(conn => {
+            const fromSphere = this.sphereManager.getSphere(conn.fromSphere);
+            const toSphere = this.sphereManager.getSphere(conn.toSphere);
+
+            if (fromSphere && toSphere) {
+                this.connectionManager.updateConnectionPositions(
+                    conn.id,
+                    fromSphere.position,
+                    toSphere.position
+                );
+            }
+        });
+
+        this.renderer.render(this.scene, this.camera);
+    }
+}

SphereManager.js

@@ -0,0 +1,225 @@
+/**
+ * SphereManager.js
+ * Manages the creation, deletion, and customization of spheres in the Three.js scene
+ */
+
+class SphereManager {
+    constructor(scene) {
+        this.scene = scene;
+        this.spheres = new Map();
+        this.sphereMeshes = new Map();
+        this.geometries = new Map();
+        this.materials = new Map();
+    }
+
+    /**
+     * Create and add a new sphere to the scene
+     * @param {string} name - Unique identifier for the sphere
+     * @param {object} config - Configuration object
+     * @param {number} config.radius - Sphere radius (default: 1)
+     * @param {string} config.color - Hex color (default: '#ff0000')
+     * @param {THREE.Vector3} config.position - Position vector (default: 0,0,0)
+     * @param {number} config.opacity - Opacity 0-1 (default: 1)
+     * @returns {THREE.Mesh} The created sphere mesh
+     */
+    addSphere(name, config = {}) {
+        // Prevent duplicate names
+        if (this.spheres.has(name)) {
+            console.warn(`Sphere with name "${name}" already exists. Skipping.`);
+            return null;
+        }
+
+        // Set defaults
+        const radius = config.radius || 1;
+        const color = config.color || '#ff0000';
+        const position = config.position || new THREE.Vector3(0, 0, 0);
+        const opacity = config.opacity !== undefined ? config.opacity : 1;
+
+        // Create geometry and material
+        const geometry = new THREE.SphereGeometry(radius, 32, 32);
+        const material = new THREE.MeshStandardMaterial({
+            color: new THREE.Color(color),
+            opacity: opacity,
+            transparent: opacity < 1,
+            emissive: new THREE.Color(color),
+            emissiveIntensity: 0.3,
+            metalness: 0.3,
+            roughness: 0.4
+        });
+
+        // Create mesh
+        const mesh = new THREE.Mesh(geometry, material);
+        mesh.position.copy(position);
+        mesh.name = name;
+        mesh.userData = {
+            sphereName: name,
+            radius: radius,
+            originalColor: color,
+            connections: []
+        };
+
+        // Store references
+        this.scene.add(mesh);
+        this.spheres.set(name, mesh.userData);
+        this.sphereMeshes.set(name, mesh);
+        this.geometries.set(name, geometry);
+        this.materials.set(name, material);
+
+        console.log(`✓ Sphere added: ${name}`, config);
+        return mesh;
+    }
+
+    /**
+     * Remove a sphere from the scene
+     * @param {string} name - Name of the sphere to remove
+     */
+    removeSphere(name) {
+        const mesh = this.sphereMeshes.get(name);
+        if (!mesh) {
+            console.warn(`Sphere "${name}" not found.`);
+            return;
+        }
+
+        // Remove from scene
+        this.scene.remove(mesh);
+
+        // Clean up geometry and material
+        const geometry = this.geometries.get(name);
+        const material = this.materials.get(name);
+        if (geometry) geometry.dispose();
+        if (material) material.dispose();
+
+        // Remove from maps
+        this.spheres.delete(name);
+        this.sphereMeshes.delete(name);
+        this.geometries.delete(name);
+        this.materials.delete(name);
+
+        console.log(`✓ Sphere removed: ${name}`);
+    }
+
+    /**
+     * Update sphere properties
+     * @param {string} name - Name of the sphere
+     * @param {object} config - Properties to update
+     */
+    updateSphere(name, config = {}) {
+        const mesh = this.sphereMeshes.get(name);
+        if (!mesh) {
+            console.warn(`Sphere "${name}" not found.`);
+            return;
+        }
+
+        // Update position
+        if (config.position) {
+            mesh.position.copy(config.position);
+        }
+
+        // Update color
+        if (config.color) {
+            const colorObj = new THREE.Color(config.color);
+            mesh.material.color.copy(colorObj);
+            mesh.material.emissive.copy(colorObj);
+            mesh.userData.originalColor = config.color;
+        }
+
+        // Update opacity
+        if (config.opacity !== undefined) {
+            mesh.material.opacity = config.opacity;
+            mesh.material.transparent = config.opacity < 1;
+        }
+
+        // Update scale (for size changes without recreating geometry)
+        if (config.scale !== undefined) {
+            mesh.scale.set(config.scale, config.scale, config.scale);
+        }
+
+        console.log(`✓ Sphere updated: ${name}`);
+    }
+
+    /**
+     * Get sphere mesh by name
+     * @param {string} name - Name of the sphere
+     * @returns {THREE.Mesh} The sphere mesh
+     */
+    getSphere(name) {
+        return this.sphereMeshes.get(name);
+    }
+
+    /**
+     * Get all spheres
+     * @returns {Array} Array of sphere data
+     */
+    getAllSpheres() {
+        return Array.from(this.spheres.entries()).map(([name, data]) => ({
+            name,
+            ...data,
+            mesh: this.sphereMeshes.get(name)
+        }));
+    }
+
+    /**
+     * Change sphere color with animation
+     * @param {string} name - Name of the sphere
+     * @param {string} newColor - New hex color
+     * @param {number} duration - Animation duration in ms
+     */
+    changeColorSmooth(name, newColor, duration = 500) {
+        const mesh = this.sphereMeshes.get(name);
+        if (!mesh) return;
+
+        const startColor = mesh.material.color.getHex();
+        const endColor = new THREE.Color(newColor).getHex();
+        const startTime = Date.now();
+
+        const animate = () => {
+            const elapsed = Date.now() - startTime;
+            const progress = Math.min(elapsed / duration, 1);
+
+            const currentColor = new THREE.Color().lerpHexColors(startColor, endColor, progress);
+            mesh.material.color.copy(currentColor);
+            mesh.material.emissive.copy(currentColor);
+
+            if (progress < 1) {
+                requestAnimationFrame(animate);
+            } else {
+                mesh.userData.originalColor = newColor;
+            }
+        };
+
+        animate();
+    }
+
+    /**
+     * Add a glow effect to a sphere
+     * @param {string} name - Name of the sphere
+     * @param {boolean} enable - Whether to enable glow
+     */
+    setGlow(name, enable = true) {
+        const mesh = this.sphereMeshes.get(name);
+        if (!mesh) return;
+
+        if (enable) {
+            mesh.material.emissiveIntensity = 0.8;
+        } else {
+            mesh.material.emissiveIntensity = 0.3;
+        }
+    }
+
+    /**
+     * Clear all spheres
+     */
+    clearAll() {
+        const names = Array.from(this.spheres.keys());
+        names.forEach(name => this.removeSphere(name));
+        console.log('✓ All spheres cleared');
+    }
+
+    /**
+     * Get sphere count
+     * @returns {number}
+     */
+    getCount() {
+        return this.spheres.size;
+    }
+}

index.html

@@ -1,19 +1,194 @@
-<!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Three.js Scene</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+            background-color: #1a1a1a;
+            color: #fff;
+            overflow: hidden;
+        }
+
+        #canvas {
+            display: block;
+            width: 100%;
+            height: 100vh;
+        }
+
+        .controls-info {
+            position: absolute;
+            top: 20px;
+            right: 20px;
+            background-color: rgba(0, 0, 0, 0.8);
+            padding: 15px;
+            border-radius: 10px;
+            border: 2px solid #00d4ff;
+            font-size: 12px;
+            max-width: 250px;
+        }
+
+        .controls-info h3 {
+            color: #00d4ff;
+            margin-bottom: 10px;
+        }
+
+        .control-item {
+            margin-bottom: 8px;
+        }
+
+        .control-item strong {
+            color: #00d4ff;
+        }
+
+        /* HUD Top Bar */
+        .hud-container {
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            height: 60px;
+            background: linear-gradient(135deg, rgba(10, 14, 39, 0.95) 0%, rgba(20, 25, 50, 0.95) 100%);
+            border-bottom: 2px solid #00d4ff;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            padding: 0 30px;
+            box-shadow: 0 4px 20px rgba(0, 212, 255, 0.2);
+            z-index: 1000;
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+        }
+
+        .hud-left {
+            display: flex;
+            align-items: center;
+            gap: 20px;
+        }
+
+        .hud-title {
+            font-size: 16px;
+            font-weight: bold;
+            color: #00d4ff;
+            letter-spacing: 1px;
+        }
+
+        .epoch-button {
+            background: linear-gradient(135deg, #00d4ff 0%, #0099cc 100%);
+            border: none;
+            color: #0a0e27;
+            padding: 8px 20px;
+            font-size: 14px;
+            font-weight: bold;
+            border-radius: 5px;
+            cursor: pointer;
+            transition: all 0.3s ease;
+            box-shadow: 0 4px 15px rgba(0, 212, 255, 0.4);
+        }
+
+        .epoch-button:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 6px 20px rgba(0, 212, 255, 0.6);
+        }
+
+        .epoch-button:active {
+            transform: translateY(0);
+            box-shadow: 0 2px 10px rgba(0, 212, 255, 0.4);
+        }
+
+        .hud-right {
+            display: flex;
+            align-items: center;
+            gap: 10px;
+        }
+
+        .accuracy-label {
+            font-size: 14px;
+            color: #ffd93d;
+            font-weight: 600;
+        }
+
+        .accuracy-value {
+            font-size: 16px;
+            color: #4ecdc4;
+            font-weight: bold;
+            min-width: 60px;
+            text-align: right;
+        }
+
+        #canvas {
+            display: block;
+            width: 100%;
+            height: 100vh;
+            margin-top: 0;
+        }
+    </style>
+</head>
+<body>
+    <canvas id="canvas"></canvas>
+
+    <!-- HUD Top Bar -->
+    <div class="hud-container">
+        <div class="hud-left">
+            <div class="hud-title">Neural Network Visualizer</div>
+            <button class="epoch-button" id="epochButton">Next Epoch</button>
+            <!-- epoch counter: -->
+            <div class="epoch-counter" id="epochCounter" style="color: #ffffff; font-weight: bold; margin-left: 15px;">Epoch: 0</div>
+
+            <!-- loading / minibatch counter: -->
+            <div class="minibatch-counter" id="minibatchCounter" style="color: #ffffff; font-weight: bold; margin-left: 15px;">Minibatch: 0</div>
+
+            <!-- reset camera view button-->
+            <button class="button" id="resetCameraButton" style="margin-left: 15px; background: linear-gradient(135deg, #ff6f61 0%, #d64541 100%);">Reset Camera</button>
+
+            <a href="https://github.com/richardhcli/neural_network_visualization" target="_blank" style="margin-left: 15px; color: #00d4ff; text-decoration: none; font-weight: bold;">GitHub Repo</a>
+        </div>
+         
+        <div class="hud-right">
+            <span class="accuracy-label">Accuracy:</span>
+            <span class="accuracy-value" id="accuracyValue">--</span>
+        </div>
+    </div>
+
+    <div class="controls-info">
+        <h3>Controls</h3>
+        <div class="control-item">
+            <strong>Left Click + Drag:</strong> Rotate
+        </div>
+        <div class="control-item">
+            <strong>Right Click + Drag:</strong> Pan
+        </div>
+        <div class="control-item">
+            <strong>Scroll Wheel:</strong> Zoom
+        </div>
+        <div class="control-item">
+            <strong>Double Click:</strong> Auto Focus
+        </div>
+    </div>
+
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/three@0.128.0/examples/js/controls/OrbitControls.js"></script>
+
+  <!-- Import TensorFlow.js -->
+  <script src="https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@1.0.0/dist/tf.min.js"></script>
+
+
+
+    <script src="SphereManager.js"></script>
+    <script src="ConnectionManager.js"></script>
+    <script src="MNIST_dataset.js"></script>
+    <script src="preprocessing.js"></script>
+    <script src="CustomNeuralNetwork.js"></script>
+
+    <script src="NetworkToDisplay.js"></script>
+    <script src="SceneManager.js"></script>
+    <script src="main.js"></script>
+</body>
 </html>

main.js

@@ -0,0 +1,86 @@
+/**
+ * main.js
+ * Minimalistic Three.js scene with JSON-based initialization
+ */
+
+
+// Initialize when DOM is loaded
+document.addEventListener('DOMContentLoaded', () => {
+    (async () => {
+        window.sceneManager = new SceneManager();
+
+        const figureOptions = {
+            layerSpacing: 10,
+            neuronSpacing: 2,
+            neuronRadius: 0.5,
+            inputColor: '#ff6b6b',
+            hiddenColor: '#ffd93d',
+            outputColor: '#4ecdc4',
+            weightThreshold: 0.1,
+            lineWidth: 0.1,
+            opacity: 0.1
+        };
+
+
+        // preprocess MNIST data
+        const { trainingData, testData } = await preprocessMNISTData();
+        console.log('✓ MNIST data preprocessed');
+        
+        //model: 
+
+        //create model network:
+        const network = new Network([784, 16, 16, 10]); // example architecture
+
+
+        // Train the network
+        //network.SGD(trainingData, 1, 10, 0.5, testData);
+
+        //testing:
+        // const network = new Network([784, 1, 1, 1]);
+
+        // Visualizer instance (non-static class)
+        const visualizer = new NetworkToDisplay(network, sceneManager, figureOptions);
+
+        // Build spheres and initial connections directly in the scene
+        visualizer.initialGeneration();
+
+        const visualizer_function = () => {
+            visualizer.updateConnections();
+            console.log('✓ Visualization updated');
+        };
+
+        // Initialize epoch counter
+        let epochCount = 0;
+
+        //attach epoch training to button
+        const trainEpochButton = document.getElementById('epochButton');
+        if (trainEpochButton) {
+            trainEpochButton.addEventListener('click', () => {
+                network.SGD_single_epoch(trainingData, 100, 0.5, testData, visualizer_function);
+                
+                // Increment and update epoch counter display
+                epochCount++;
+                const epochCounterDiv = document.getElementById('epochCounter');
+                if (epochCounterDiv) {
+                    epochCounterDiv.textContent = `Epoch: ${epochCount}`;
+                }
+            });
+        }
+
+
+    })();
+
+    // sceneManager.loadFromJSON({
+    //     spheres: [
+    //         { name: 'A', radius: 1.5, color: '#ff0000', position: { x: -5, y: 0, z: 0 } },
+    //         { name: 'B', radius: 1.5, color: '#00ff00', position: { x: 5, y: 0, z: 0 } }
+    //     ],
+    //     connections: [
+    //         { id: 'AB', from: 'A', to: 'B', color: '#ffffff', lineWidth: 2 }
+    //     ]
+    // });
+
+    // Example: Uncomment to add initial demo spheres
+    // sceneManager.addMultipleSpheres(5);
+    // sceneManager.connectSphereChain(['Sphere_0', 'Sphere_1', 'Sphere_2', 'Sphere_3', 'Sphere_4']);
+});

preprocessing.js

@@ -0,0 +1,65 @@
+// import { MnistData } from './MNIST_dataset.js';
+
+
+/**
+ * Loads and preprocesses MNIST dataset for neural network training
+ * Reshapes flat image arrays into column vectors and formats labels
+ * @returns {Promise<{trainingData: Array, testData: Array}>} Preprocessed training and test data
+ */
+async function preprocessMNISTData() {
+    
+const IMAGE_SIZE = 784;
+const NUM_CLASSES = 10;
+const NUM_TRAIN_ELEMENTS = 55000;
+const NUM_TEST_ELEMENTS = 10000;
+
+
+    // Load MNIST data from remote sources
+    const mnistData = new MnistData();
+    await mnistData.load();
+
+    // Convert training data to format expected by Network class
+    const trainingData = [];
+    for (let i = 0; i < NUM_TRAIN_ELEMENTS; i++) {
+        const imageStart = i * IMAGE_SIZE;
+        const labelStart = i * NUM_CLASSES;
+        
+        // Reshape image from flat array into column vector [[val], [val], ...]
+        const x = [];
+        for (let j = 0; j < IMAGE_SIZE; j++) {
+            x.push([mnistData.trainImages[imageStart + j]]);
+        }
+        
+        // Extract one-hot encoded label as column vector
+        const y = [];
+        for (let j = 0; j < NUM_CLASSES; j++) {
+            y.push([mnistData.trainLabels[labelStart + j]]);
+        }
+        
+        trainingData.push([x, y]);
+    }
+
+    // Convert test data to format expected by Network class
+    const testData = [];
+    for (let i = 0; i < NUM_TEST_ELEMENTS; i++) {
+        const imageStart = i * IMAGE_SIZE;
+        const labelStart = i * NUM_CLASSES;
+        
+        // Reshape image from flat array into column vector [[val], [val], ...]
+        const x = [];
+        for (let j = 0; j < IMAGE_SIZE; j++) {
+            x.push([mnistData.testImages[imageStart + j]]);
+        }
+        
+        // Extract one-hot encoded label as column vector
+        const y = [];
+        for (let j = 0; j < NUM_CLASSES; j++) {
+            y.push([mnistData.testLabels[labelStart + j]]);
+        }
+        
+        testData.push([x, y]);
+    }
+
+    return { trainingData, testData };
+}
+

style.css

@@ -1,28 +0,0 @@
-body {
-	padding: 2rem;
-	font-family: -apple-system, BlinkMacSystemFont, "Arial", sans-serif;
-}
-
-h1 {
-	font-size: 16px;
-	margin-top: 0;
-}
-
-p {
-	color: rgb(107, 114, 128);
-	font-size: 15px;
-	margin-bottom: 10px;
-	margin-top: 5px;
-}
-
-.card {
-	max-width: 620px;
-	margin: 0 auto;
-	padding: 16px;
-	border: 1px solid lightgray;
-	border-radius: 16px;
-}
-
-.card p:last-child {
-	margin-bottom: 0;
-}