Atlas Tube Custom Diagrams - Calcs.com Documentation

This document provides insights into the development and architecture of the Atlas Tube custom diagrams, serving as a case study for advanced interactive diagram implementation.

This documentation is based on development learnings and may be updated as the implementation evolves.

Repository Information

Repository: custom-diagrams-library While named generically as “library,” this repository is specifically focused on Atlas Tube diagrams and serves as the primary example of complex custom diagram implementation.

Architecture Overview

Diagram Type Parameter

A key innovation in the Atlas Tube implementation is the introduction of a diagramType parameter, which allows one compiled ES module to include multiple diagram variations.

// Different diagram types within the same module
{
    diagramType: "splice_atlas",     // For tube splicing diagrams
    // ... splice-specific parameters
}

{
    diagramType: "bracket_atlas",    // For bracket connection diagrams  
    // ... bracket-specific parameters
}

Data Flow Architecture

The data flow is consistent for both interactive and static diagrams, and across all Atlas Tube diagram types:

Detailed Data Flow

1. Initialize Phase

File: src/interactive/interface.ts : initialize()

Sets up basic framework
Does minimal work but still required

2. Client Initialize Phase

File: src/interactive/interface.ts : clientInitialize()

Creates blank canvas
Switches to appropriate diagram type
Calls: src/spliceAtlas/ParamsInterface.ts : defaultParams
- Loads default parameters for the diagram
Calls: src/spliceAtlas/render.ts : update()
- Resizes canvas to fit
- Renders elements with default parameters
- Calls: src/spliceAtlas/getTransformations.ts: getTransformations()
  - Reformats original parameters into positioning data
  - Calculates anchor points for diagram elements
Returns to: src/spliceAtlas/render.ts : update()
- Transforms the calculated elements
- Draws text and leader lines

3. Render Phase

File: src/interactive/interface.ts : render()

Clears existing canvas
Switches to appropriate diagram type
Similar steps to clientInitialize() but with actual sheet parameters
Renders final diagram with real calculation data

Component Architecture

Shared Components

Shared Component Structure

SVG Extensions (/src/shared/svgjsExtensions/*.ts)

Custom Calcs.com SVG library elements
Reusable across any diagram implementation
Defined types in /src/svgjsExtensions.d.ts

Utility Functions (/src/shared/utils/*.ts)

Helper functions used by SVG extensions
Mathematical calculations and transformations
Data formatting and validation

Asset Library (/src/shared/assets/*.svg)

Complete SVG images for diagram sub-components
Standardized symbols and representations
Material and connection detail drawings

Testing and Development

Local Testing Setup

Critical Testing Requirements:The testing environment requires both processes running simultaneously:

Development Server: npm start
Test Runner: npm test

Both must be active for the tester to function properly.

Testing Configuration

// When testing, you must:
// 1. Select diagram type in dropdown
// 2. Pass diagramType in render call parameters

render({
    diagramType: "splice_atlas",
    tubeSize: "100x100x5",
    spliceLength: 500,
    // ... other parameters
})

It can take significant time to understand the testing setup requirements. The dual-process requirement and parameter passing are not immediately obvious from the documentation.

Alternative Approaches Discussion

Current Limitations

The current implementation raises questions about whether there might be more efficient approaches:

Potential Alternative Technologies

Native SVG with Parameters

SVG has native support for parametric variables
Could potentially eliminate JavaScript entirely
May become complex with arbitrary numbers of elements

Higher-Level Libraries

Current implementation uses low-level SVG.js and svgdom
Alternative libraries like Snap.svg or Maker.js might provide better abstractions
Could improve development speed and maintainability

CAD Integration

Engineers are already familiar with parametric drafting tools
DXF is a vector format that can convert to/from SVG
Might enable direct CAD-to-diagram workflows

Design Philosophy

Core Question: What are we actually doing?At its essence, we’re creating parametric technical drawings:

Copying shared components into project-specific details
Parameterizing placement of lines and labels
Generating vector drawings for web display

This is similar to existing CAD workflows that engineers already understand.

Implementation Best Practices

Parameter Management

interface DiagramParams {
    diagramType: string;
    // Geometric parameters
    dimensions: {
        length: number;
        width: number;
        thickness: number;
    };
    // Display parameters
    showDimensions: boolean;
    showLabels: boolean;
    // Material parameters
    material: string;
    finish: string;
}

Error Handling

function validateParams(params: DiagramParams): boolean {
    // Validate required parameters
    if (!params.diagramType) {
        console.error('diagramType is required');
        return false;
    }
    
    // Validate numeric ranges
    if (params.dimensions.length <= 0) {
        console.error('Length must be positive');
        return false;
    }
    
    return true;
}

Performance Optimization

// Optimize rendering for complex diagrams
function optimizedRender(elements: DiagramElement[]) {
    // Batch DOM updates
    const fragment = document.createDocumentFragment();
    
    // Render only visible elements
    const visibleElements = elements.filter(el => el.isVisible);
    
    // Use efficient SVG manipulation
    visibleElements.forEach(element => {
        const svgEl = createSVGElement(element);
        fragment.appendChild(svgEl);
    });
    
    // Single DOM update
    canvas.appendChild(fragment);
}

Future Considerations

Scalability

As more custom diagrams are developed, consider:

Shared Component Library: Expand reusable components
Template System: Create diagram templates for common patterns
Configuration Tools: GUI tools for non-developers to create diagrams
Performance Monitoring: Track rendering performance across diagram types

Integration Improvements

Real-time Preview: Live parameter updates during template editing
Validation Tools: Automatic parameter validation and error reporting
Documentation Generation: Auto-generate parameter documentation
Testing Automation: Automated visual regression testing

The Atlas Tube diagrams represent a sophisticated implementation of custom visualization. While complex, they demonstrate the power and flexibility available for specialized engineering diagrams.

Custom diagram development requires significant JavaScript/TypeScript expertise and ongoing maintenance commitment. Evaluate complexity against business requirements before undertaking similar implementations.

​Repository Information

​Architecture Overview

​Diagram Type Parameter

​Data Flow Architecture

​1. Initialize Phase

​2. Client Initialize Phase

​3. Render Phase

​Component Architecture

​Shared Components

​Testing and Development

​Local Testing Setup

​Testing Configuration

​Alternative Approaches Discussion

​Current Limitations

​Design Philosophy

​Implementation Best Practices

​Parameter Management

​Error Handling

​Performance Optimization

​Future Considerations

​Scalability

​Integration Improvements

Repository Information

Architecture Overview

Diagram Type Parameter

Data Flow Architecture

1. Initialize Phase

2. Client Initialize Phase

3. Render Phase

Component Architecture

Shared Components

Testing and Development

Local Testing Setup

Testing Configuration

Alternative Approaches Discussion

Current Limitations

Design Philosophy

Implementation Best Practices

Parameter Management

Error Handling

Performance Optimization

Future Considerations

Scalability

Integration Improvements