Welcome, this is a brief non-exhaustive user guide for RaphBuilt from Vasturiano‘s 3D Force Graph implementation of d3.js with Three.js: https://github.com/vasturiano/3d-force-graph, a 2D and 3D editor for custom small connected graphs made of nodes and links (also known as vertices and edges). This is a webapp with typical app functionality (loading, saving, copying, pasting etc) which works best with a mouse (with mouse wheel and two buttons) for more effective performance.
In particular you’ll find the right-click—which from here on will be referred to as Rclick, or Rdrag—and the wheel of most use: the wheel for zooming, changing property values, reshaping nodes, and adjusting link weights.
Rdrag and Rclick actions allow for marquee selection, panning (in conjunction with the Shift key), and activation of core menus, where the left mouse button Lclick enables view rotation through dragging, node or link selection, and menu option selection through clicking.
The core menus (Rclick or equivalent gesture on a trackpad) are context aware, which means activation on an empty space will provide graph wide options whereas activation on a node will provide options relevant to all selected nodes. This last point is especially important as, to affect one or more nodes, they must first be selected.
Node selections are made by left-clicking on a node to toggle its use (indicated by an orange circle), whilst using the Shift key will enable multiple nodes. Ctrl-A additionally toggles between selecting all and none.
All menu options are reflected as individual letters or characters, each of which can be activated directly via a keyboard as you become more familiar with editing workflows. In use on screen you will find hovering over any menu item should prompt a summary floating guide. Your playful curiosity should take care of the rest.
In creating and editing a new graph the following simple flow provides something like a serving suggestion:
The simplest of processes involves generating a randomly connected graph—Rclick followed by ‘G‘. Zoom in a little (mouse wheel) and Ldrag one node away from the bundle to encourage the remainder to spread out a little. Then try delete a link after carefully selecting it—Lclick on the link followed by Rclick then ‘–‘. Lclick on nodes in a similar manner to select before Rclick (on a node) to summon the node menu and then ‘–‘ to delete. Next try selecting a node and use the node menu to create a new connected node with the ‘+‘ option.
To add a new link select exactly two unconnected nodes and use the node menu to select the ‘~‘ option.
This outlines adding and deleting nodes and links.
Nodes have additional embedded data structured out of site as a list of editable parameters (key-value pairs) through which node colours, dimensions, labels and additional data can be altered. To edit node data we call on the node menu for the selected node we wish to amend and select the ‘e‘ option.
From here a new panel will appear to one side of the screen with a column of text boxes. Hovering over each text box will reveal the key type for each. The top box is always the node colour, then below you’ll find other parameters such as the label, scale, dimensions, and so on. The larger blue ‘+‘ character at the bottom will add new fields and once activated you’ll see a ‘–‘ character for removing new fields. Additional data fields are relevant for JSON and Machine Learning purposes but not otherwise picked up in the editor.
If more than one node is selected the text boxes will be hatched with a pattern. This indicates that any subsequent changes made to a field will affect all of the selected nodes. To modify all nodes you can use Ctrl+a on your keyboard to select all nodes. In this state of editing caution should be exercised to not modify the wrong fields and potentially flatten parts of your background data.
Text entered into the ‘label’ field of the editor will be displayed in the main graph view—replacing the circle or square currently in place at the selected node. To transform back to a shape use the word ‘node’, or any of the following; ‘false’, ‘null’, ‘blank’, ‘nolabel’, or ‘-‘.
A shortcut for editing node labels (without the node editor); select the nodes to relabel, then simply tap the Control (Ctrl) key to call a text editing dialogue box over one of the nodes. Enter the text and click elsewhere to update.
Advanced:
ML Feature Masks: Rclick on a text box to select fields for machine learning. This will create a parallel array in the JSON file called ‘masks’ as a list of key node features for modelling.
New fields: When creating new fields with data it is important to separate the field name (key) and it’s initial value with a colon without space before or after. So a new field called ‘temperature’ and a default value of ’22’ for example would be written as ‘temperature:22’ in the new text box after using the ‘+‘. Some fields, such as those created or needed by the graph renderer are hidden from view.
Rclick or select ‘e‘ to close the editor.
There are different methods to introduce images to Raph via the image gallery. Rclick on the background to call the core menu and select ‘i‘ for the gallery panel. From here some options to import are:
Lclick on images to select, and use the new mini menu to the upper corner of the panel to remove, open, save, or toggle select-all images. Additionally rename an image by selecting and typing into the filename to the top left. As usual press enter to confirm.
Applying images: After selecting one image, select a target node and the image should be applied. It may appear small at first but hover over it’s center with the mouse and try using the wheel to adjust its visible size. Alternatively you can change the ‘scale‘ field for its applied node directly in the node editor panel. To remove an image from a node, ensure that the node of interest is selected and no other images in the image gallery and then Rclick on the selected image for the node menu and select ‘–‘.
Applying a background image: After selecting one image, select the ‘b‘ option to the top right corner of the image gallery and the image will be duplicated to the background. With the same image selected in the gallery panel select ‘b’ again to remove it or a different image to replace. Whilst hovering over ‘b‘ use the mousewheel to adjust background image size, or use the option key+mousewheel whilst hovering to adjust opacity. Additionally, using the cursor keys will adjust the background image position—again, whilst hovering over ‘b‘.
This covers basic graph making and editing in the 3D space of Raph.
To switch between this and the 2D space use the ‘2‘ (or ‘3‘) option on the core menu. Alternatively typing ‘2‘ or ‘3‘or using the ‘Tab‘ key of the keyboard will also transition between both spaces.
This space is someone’s useful for editing less complex graphs with more control when exporting as vector based SVG drawings. Movements in this space correspond to the X and Y coordinates of the 3D space. Otherwise all options generally correspond to those of the 3D space.
The lowest option of the core menu (option ‘G‘) is more than a button. Use the mouse wheel whilst hovering over this option to change the number of nodes (size) of a newly generated random graph. Or Rclick again on this option to call a new input bar to the top of the screen, from within this textbox you can define list of node labels—separated by spaces—and optionally use a number immediately before an option define a limit to the number of times that label may be used. For example for a graph using room names it may be necessary to limit the use of the term ‘Kitchen’ to one instance, and the term ‘Bedroom’ to three, as such: ‘3Bedroom 1Kitchen 2Reception‘.
Calling on the core menu and selecting the ‘>‘ option activates a secondary menu with options for saving the current file with option ‘S‘, opening a new JSON file with option ‘O‘, or opening the floating extended toolbox with option ‘⸬‘ .
Saving [S]will create a JSON file in your browser’s set download folder. The default filename is called ‘raph_3D.json’ and can be changed before saving by clicking on the ‘–‘ to the lower right corner of the window and entering a new name. Alongside the JSON file Raph saves an additional .png image file of the 3D view, and a .svg file of the 2D view, however it is important to view and position the 2D view as suits before saving otherwise this file might be empty. Additionally, if the caps lock key is active during save an extra .obj 3D fileNote: 3D Text is not yet exported in this format will be saved with the other formats.
Loading [O] opens a file dialogue box to help locate a ‘.json‘ file. Raph JSON structure is composed of the following data structure:
The extended toolbox (option ‘⸬‘) opens to the top left area of your screen and contains both node relevant options, and general options as follows:
Additional: Copying and pasting are enacted through keyboard combinations Ctrl-C and Ctrl-V respectively as for other apps.
Hold the ‘option‘ key and Lclick on a node provide visible focus on the selected node and its immediate connected neighbours. Alternatively, double Lclick on a node to select the node and immediate neighbours.
This provides an overview of on-screen mouse tools and an overview of creating editing and viewing custom made connected graphs in Raph.