API Documentation

Visucodize Visualization API Documentation

Overview 📌

Welcome to the Visucodize Visualization API! This API allows you to create animated visualizations of data structures and algorithms by using special visualization classes that behave like their standard JavaScript counterparts but automatically generate visual representations.

Core Concept 📌

Instead of using standard JavaScript data structures, you use Vis (Visualization) classes that maintain the same behavior but add visualization capabilities:

// Standard JavaScript
let arr = [1, 2, 3];

// Visucodize Visualization  
let arr = new VisArray(1, 2, 3);

The visualization classes expose a visManager property that allows you to control the visualization appearance and behavior.

Quick Start 📌

function visMainFunction(index, backgroundColor) {
    // Create a visualized array with custom options
    let arr = new VisArray(5, 2, 8, 1, 9)
        .options({ 
            label: 'My Array',
            renderingStyle: RenderingStyle.BAR_CHART
        });
    
    // Style individual elements
    arr.makeVisManagerForIndex(0).addClass('highlighted');
    arr.makeVisManagerForIndex(index).setProp('backgroundColor', backgroundColor);
    
    // Perform operations - they work like normal arrays but visualized!
    arr.push(3);
    arr.sort((a, b) => a - b);
    
    return arr;
}

Visualization Lifecycle 📌

Automatic Visualization 📌

By default, visualization objects are automatically visualized when assigned to a variable:

const arr = new VisArray();  // Visualized until 'arr' either goes out of the scope where it was declared or is reassigned to another value
let nums = new VisArray(1, 2, 3);  // Visualized until 'nums' either goes out of the scope where it was declared or is reassigned

Scope-Based Destruction 📌

Visualizations are automatically destroyed based on the declaration location of the variable, not assignment location:

let arr;
{
    // Visualization for 'arr' begins here, but its lifetime is determined by the scope where 
    // 'arr' was declared—not by this assignment location.
    arr = new VisArray();  
}
// The visualization for 'arr' still exists here

let arr2 = new VisArray();
{
    // This assignment does NOT create a new visualization.
    // 'a' is just referencing to 'arr2', and when 'a' leaves its
    // declaration scope, it does NOT destroy the visualization of 'arr2'.
    let a = arr2;
}
// arr2 visualization still exists here

Controlling Visualization Creation 📌

Use .createVis(visPref) to control whether a visualization object should be visualized:

new VisArray();              // NOT visualized (no variable assignment)
new VisArray().createVis();  // Visualized (explicit creation) the default visualization preferance is true
new VisArray().createVis(true);   // Visualized, visualization preferance is true
new VisArray().createVis(false);  // NOT visualized, visualization preferance is false

const arr = new VisArray().createVis(false);  // arr is NOT visualized, visualization preferance is false

Important: The visualization preference can only be set once and it will be assumed to set to true if not set to false directly during the assignment:

const arr = new VisArray().createVis(false);
// This has NO effect — the visualization preference was already set.
// 'arr' remains NOT visualized.
arr.createVis(true);

const arr = [new VisArray()];
// This makes the VisArray instance at arr[0] visualized,
// because its visualization preference is being set for the first time.
arr[0].createVis(true);

const arr = new VisArray();
// This has NO effect — the visualization preference was already assumed to be true 
// at the time of assignment. 'arr' remains visualized.
// Use destroyVis() if you want to remove the visualization.
arr.createVis(false);

Manual Destruction 📌

Use .destroyVis() to destroy a visualization early:

const arr = new VisArray();
arr.destroyVis();  // Destroys visualization immediately
arr[0] = 1;        // Operations continue but without visualization

Reassignment Behavior 📌

Reassigning a variable destroys the previous visualization and may create a new one:

const arr = new VisArray();
arr = new VisArray(1, 2);  // Destroys first visualization, creates new one

const nums = new VisArray();
nums = null;  // Destroys visualization, no new visualization created

Label 📌

The display label used for visualized elements in Visucodize.

How the label is determined for datagroups 📌

  1. If .options({ label: '...' }) is provided
    → This explicitly becomes the datagroup’s label.

  2. If no explicit label is set but the datagroup is assigned to a variable
    → The variable name becomes the label (e.g., let arr = new VisArray() gives the label "arr").

  3. If neither condition applies
    → No label is rendered.

let myArray = new VisArray(1, 2, 3);  // Label automatically set to "myArray"
let arr = new VisArray(4, 5, 6).options({ label: 'Custom' });  // Label overridden to "Custom"

How the label is determined for datagroup elements 📌

Element labels follow this priority order:

  1. labelExtractionPolicy output (if NOT undefined)
    → Returned value becomes the element’s label.

  2. If labelExtractionPolicy returns undefined
    → Visucodize falls back to the UI’s built-in extraction logic:

    • If data is an ElementReference
      → Recursively use the referenced element’s label.
    • If data is a plain object
      → Label becomes an empty string ("").
    • Otherwise
      → Label becomes "" + data (string conversion).
    • If no meaningful label exists
      → The label becomes null and nothing is rendered.

Value 📌

The value associated with a visualized element in Visucodize.
This value may influence visualization behavior (e.g., bar heights in bar-chart arrays, ordering in heaps, etc.).

How the value is determined for datagroups 📌

Datagroups themselves do not have a single “value.”
Each element inside the datagroup is assigned its own extracted value (see below).

How the value is determined for datagroup elements 📌

Element values follow this priority order:

  1. valueExtractionPolicy output (if NOT undefined)
    → The returned value becomes the element’s value.

  2. If valueExtractionPolicy returns undefined)
    → Visucodize falls back to its built-in client-side extraction logic:

    • If the data is an ElementReference
      → Recursively use the referenced element’s value.

    • Otherwise
      → The element’s value becomes the underlying data itself.

    • If no meaningful value exists
      → The value becomes null.

Available Visualization Classes 📌

ClassDescriptionStandard Equivalent
VisArrayVisualized arrayArray
VisSetVisualized setSet
VisMapVisualized mapMap
VisObjectVisualized objectObject
VisBinaryTreeBinary tree structureCustom
VisTreeGeneral tree structureCustom
VisDictionaryTreeDictionary/trie structureCustom
VisGraphGraph structureCustom
VisNetworkGraphNetwork graphCustom
VisLinkedListLinked listCustom
VisQueueQueue structure (uses @datastructures-js/queue v4.2.3)Custom
VisPriorityQueuePriority queue (uses @datastructures-js/priority-queue v5.4.0)Custom
VisMinPriorityQueueMin priority queue (uses @datastructures-js/priority-queue v5.4.0)Custom
VisMaxPriorityQueueMax priority queue (uses @datastructures-js/priority-queue v5.4.0)Custom
VisArray2D2D array/matrix2D Array
VisVariableSingle visualized variableVariable

Documentation Structure 📌

  • Classes - Detailed documentation for all visualization classes
  • Vis Manager API - Methods for controlling visualization appearance
  • Global Functions - Utility functions available in the visualization context
  • Options - Configuration options for data structures

Key Features 📌

1. Automatic Visualization 📌

Operations on Vis classes are automatically visualized:

let list = new VisArray(1, 2, 3);
list.push(4);  // Push operation is visualized
list.pop();    // Pop operation is visualized

2. Element-Level Control 📌

Access and style individual elements:

let arr = new VisArray(10, 20, 30);

// Style a specific element
arr.makeVisManagerForIndex(1).addClass('current');
arr.makeVisManagerForIndex(1).setProp('label', 'Checking');

3. Custom Styling 📌

Apply visual properties:

arr.visManager.setProp('borderColor', 'red');
arr.visManager.setProp('backgroundColor', 'lightblue');
arr.visManager.addClass('highlighted');

Entry Point 📌

Your visualization code must be wrapped in a function named visMainFunction:

function visMainFunction(num1, num2) {
    let arr = new VisArray(num1, num2);
    arr.push(4);    
    return arr;
}

The provided inputs are retrieved by the entry method in order. For example, in the sample above, num1 corresponds to the first input and num2 to the second.

How It Works 📌

  1. Write Code: Use Vis classes in your visMainFunction function
  2. Run: The code executes in a sandboxed environment
  3. Visualize: Operations are captured and converted to visualization steps
  4. Animate: Steps are played back to create the animation

Next Steps 📌