Drawing Diagrams

Create interactive diagrams using the Konva canvas-based drawing tools

Mas Agua includes a powerful diagram editor built on Konva canvas that allows you to create interactive diagrams with images, lines, text, and live data from InfluxDB variables.

Overview

The diagram editor provides:

• Drawing tools: lines, polylines, text, and images
• Image library with pre-loaded equipment icons
• Live variable integration with tooltips
• Layer management (bring to front/send to back)
• Zoom and pan capabilities
• Save/load functionality

Accessing the Diagram Editor

1. Navigate to Diagrams List

   Go to /config/diagram to view all existing diagrams.

2. Create New Diagram

   Click the create button to navigate to /newDiagram for a blank canvas.

3. Edit Existing Diagram

   From the list, click edit on any diagram to open it at /newDiagram/{id}.

Understanding the Interface

The diagram editor (src/modules/DrawDiagram/views/DrawDiagram.jsx) consists of:

Top Navbar

Controls for diagram-level actions:

• Clear: Remove all elements from canvas
• Save: Save diagram to database
• Undo: Remove last added element
• Send to Back: Move selected element behind others
• Bring to Front: Move selected element to top layer
• Zoom In/Out: Adjust canvas zoom level
• Pan Mode: Toggle panning mode

Left Sidebar

Drawing tools and options:

• Image: Add images from library
• Line: Draw straight lines
• Polyline: Draw multi-segment lines
• Text: Add text labels
• Floating Variable: Add variable display
• Delete: Remove selected element

Main Canvas

The interactive drawing area where you create your diagram.

Right Panels

Context-sensitive panels that appear based on selection:

• Image Selector: Choose from image library
• Line Style Panel: Configure line appearance
• Text Styler: Format text properties
• Tooltip Position Panel: Configure variable display

Drawing Lines

1. Select Line Tool

   Click the line tool button in the left sidebar. The line style panel opens automatically.

2. Configure Line Style

   In the Line Style Panel:

   • Color: Choose line color using color picker
   • Stroke Width: Set line thickness (pixels)
   • Dash Pattern: Select solid or dashed style
3. Draw the Line

   • Click on the canvas at the starting point
   • Move mouse to endpoint (you’ll see a preview)
   • Click again to complete the line
4. Edit Line Style

   Select the line to modify its color, width, or dash pattern in the panel.

Press Escape to cancel line drawing mode at any time.

Drawing Polylines

Polylines allow multi-segment paths:

1. Select Polyline Tool

   Click the polyline tool in the sidebar.

2. Configure Style

   Set color, width, and dash pattern in the Line Style Panel.

3. Draw Multiple Segments

   • Click to place first point
   • Click additional points to create segments
   • Each click adds a new vertex
   • Press Enter to finish, or Right-click to complete

Polylines require at least 2 vertices (4 points in the points array) to be saved. Press Escape to cancel if you haven’t placed enough points.

Adding Images

1. Open Image Selector

   Click the image tool in the sidebar. The image selector panel opens with available images.

2. Browse Image Library

   The library (src/modules/DrawDiagram/utils/js/ListImg.js) contains equipment icons organized by category:

   • Pumps and motors
   • Valves and controls
   • Tanks and vessels
   • Sensors and instruments
3. Select Image

   Click on an image to add it to the canvas. It appears at position (150, 150) by default.

4. Position the Image

   Drag the image to its desired location on the canvas.

5. Resize if Needed

   Select the image to show transformation handles. Drag corners to resize while maintaining aspect ratio.

Adding Text Labels

1. Select Text Tool

   Click the text tool in the sidebar.

2. Click Placement Position

   Click where you want the text to appear. A text input field opens.

3. Enter Text Content

   Type your text in the input field.

4. Format Text (Optional)

   Click the text styler button to configure:

   • Font Size: Size in pixels
   • Fill Color: Text color
   • Font Style: Normal, bold, or italic
5. Save the Text

   Click the save button or press Enter to place the text on canvas.

You can edit existing text by selecting it and clicking the text tool again. The text editor reopens with current content.

Associating Variables with Elements

Adding Variable to Image

1. Select Image Element

   Click on an image on the canvas.

2. Open Variable Selector

   Click the variable assignment button in the sidebar.

3. Choose Variable

   Select an InfluxDB variable from the list. The variable will display near the image.

4. Configure Tooltip Position

   The Tooltip Position Panel opens. Configure:

   • Position: Centro, Arriba, Abajo, Izquierda, Derecha
   • Show/Hide: Toggle variable visibility
   • Max Value: Set scale maximum (for gauges)
   • Boolean Colors: Configure colors for true/false states
   • Binary Bit: Specify bit position for binary variables

Adding Floating Variable

1. Select Floating Variable Tool

   Click the floating variable tool in sidebar.

2. Choose Variable

   Select a variable from the list.

3. Position Variable Display

   The variable appears with a default image. Drag it to the desired location.

Element Manipulation

Selecting Elements

• Click any element to select it
• Selected elements show transformation handles
• Selection enables context-specific panels

Moving Elements

1. Select Element

   Click the element you want to move.

2. Drag to New Position

   Click and drag the element to its new location.

Deleting Elements

1. Select Element

   Click the element you want to delete.

2. Press Delete Key

   Press the Delete key on your keyboard, or click the delete tool in the sidebar.

Layer Management

1. Select Element

   Click the element you want to reorder.

2. Change Layer

   Click:

   • Send to Back: Move element behind all others
   • Bring to Front: Move element above all others

Zoom and Pan

Zooming

1. Use Zoom Controls

   Click the Zoom In or Zoom Out buttons in the top navbar.

Zoom is controlled by a scale factor:

• Zoom In: Multiplies scale by 1.05
• Zoom Out: Divides scale by 1.05

Panning

1. Enable Pan Mode

   Click the pan toggle button in the top navbar to activate panning.

2. Pan the Canvas

   Click and drag anywhere on the canvas to move the view.

3. Disable Pan Mode

   Click the pan toggle again to return to normal editing mode.

Saving Diagrams

1. Click Save Button

   Click the Save button in the top navbar.

2. Enter Diagram Name

   A dialog prompts for the diagram name. Enter a descriptive name.

3. Confirm Save

   Click Guardar to save the diagram to the database.

What Gets Saved

The save operation (src/modules/DrawDiagram/views/DrawDiagram.jsx:192-250) stores:

{
  elements: [],        // All canvas elements (images, lines, text)
  circles: [],         // Circle shapes (if any)
  diagramMetadata: {   // Diagram properties
    title: "Diagram Name",
    backgroundColor: "#ffffff",
    backgroundImg: ""
  },
  deleted: {          // Tracking for edit mode
    lines: [],
    texts: [],
    images: [],
    polylines: []
  }
}

When editing existing diagrams, only new elements have their IDs cleared before saving. Existing elements retain their IDs to enable proper updates.

Viewing Diagrams

1. Navigate to View Mode

   From the diagrams list at /config/diagram, click the view button to open /viewDiagram/{id}.

2. Interact with Live Data

   In view mode:

   • Variables display real-time values from InfluxDB
   • Hover over elements to see tooltips
   • Elements are not editable

Keyboard Shortcuts

Efficient diagram creation with keyboard shortcuts:

Shortcut	Action
Escape	Cancel current tool / Close panels
Delete	Delete selected element
Enter	Finish polyline / Save text
Right-click	Finish polyline

Best Practices

Diagram Organization

Save frequently to avoid losing work. The undo function only removes the last element added.

• Use layers strategically (backgrounds behind, important elements in front)
• Group related elements visually
• Use consistent colors for similar element types
• Label important components with text

Variable Integration

• Position variable tooltips to avoid overlapping elements
• Use meaningful positions (e.g., above for overhead displays)
• Configure boolean colors to match standard conventions (green=on, red=off)
• Set appropriate max values for gauge-style displays

Performance

• Limit the number of elements in complex diagrams (< 100 recommended)
• Use simple images when possible (smaller file sizes)
• Avoid excessive polyline vertices

Naming

• Use descriptive diagram names that indicate the system or area
• Include version numbers if maintaining multiple iterations
• Document what the diagram represents in the name

Troubleshooting

Element not appearing

• Check that element is not hidden behind others (use Bring to Front)
• Verify element is within visible canvas area
• Check zoom level - element may be very small or large

Cannot delete element

• Ensure element is selected (shows transformation handles)
• Try selecting by clicking the element directly
• Press Delete key rather than using menu

Polyline won’t finish

• Ensure you have at least 2 vertices placed
• Press Enter or right-click to complete
• Press Escape to cancel if needed

Variable not displaying data

• Verify variable exists in InfluxDB
• Check that variable is receiving data
• Ensure variable visibility is enabled in Tooltip Position Panel

Diagram won’t save

• Ensure you’ve entered a diagram name
• Check browser console for errors
• Verify backend API connectivity

Lost work after browser crash

• Diagrams are only saved when you click Save
• No auto-save functionality exists
• Save frequently during creation

Advanced Features

Background Configuration

Diagrams support:

• Background Color: Set via diagramMetadata.backgroundColor
• Background Image: Set via diagramMetadata.backgroundImg

Element Data Structure

Each element type has specific properties:

Line:

{
  id: "unique-id",
  type: "line",
  points: [x1, y1, x2, y2],
  stroke: "#3b82f6",
  strokeWidth: 5,
  dash: []
}

Image:

{
  id: "unique-id",
  type: "image",
  src: "/path/to/image.png",
  x: 150,
  y: 150,
  width: 100,
  height: 100,
  draggable: true,
  dataInflux: { /* variable data */ }
}

Text:

{
  id: "unique-id",
  type: "text",
  text: "Label",
  x: 100,
  y: 100,
  fontSize: 16,
  fill: "#000000",
  fontStyle: "normal"
}