Table of contents > Loading your nodes
Here we'll present different scenarios where you'll be loading nodes into your Nodezator files. By the way, the file extension for Nodezator files is .ndz. For instance, my_node_layout.ndz.
A common task when editing node layouts in your .ndz files is to load nodes so that you can instantiate them in your file.
In the chapter about creating our first node, we learn that nodes are created and organized within folders that we call node packs and how to create such node packs.
The act of loading nodes actually boils down to selecting the node pack(s) we want to use. The same way you write an import statement in a Python script only once, you also only need to do this once in your .ndz file, and the nodes will be available there for you every time you open that file.
In order to load nodes, we need to know 02 things:
If you ever encounter any kind of problem, with those or any other task you are trying to perform in Nodezator, don't hesitate to seek help on the discord server.
Without further ado, let's learn how to do those things.
Node packs can be obtained from 03 different ways:
Such ways to obtain node packs are further explained in the following subsections. There are actually 02 different kinds of node packs: local node packs and installable/installed node packs. The difference between them is quite simple, as summarized in the table below:
| - | Local node pack | Installed node pack |
|---|---|---|
| Node pack is installed via pip | No | Yes |
Let's now see the different methods to obtain node packs of both kinds.
The easiest way to obtain a node pack is to install it directly from PyPI (the Python Package Index) with the pip command. It is the easiest because you just need a single command to install it and then it is readily available to be loaded in any .ndz file.
For instance, there is an example node pack called mynodepack that you can install from PyPI with the following command:
pip install mynodepackOnce you install it, the nodes from the mynodepack pack are available for you to load on your .ndz files.
Node packs that can be installed from pip are called installed node packs or installable node packs. So mynodepack is an installable node pack.
If you want, you too can upload your node packs to PyPI for others to download them. The process is explained in the chapter about distributing node packs.
Since the node packs are just folders containing Python scripts defining nodes, you can just copy the folder representing the node pack anywhere in your system, by downloading them from the internet, or by copying them from a pen drive.
For instance, my profile on github contains an example node pack with generic nodes with the purpose of demonstrating different widgets. It is called examples_node_pack. You can download it from this github link: https://github.com/KennedyRichard/examples_node_pack. Just download and unzip the repository and that's it, the folder is a node pack that you can load into your .ndz files.
Node packs that you don't install with pip are called local node packs. Hence, the examples_node_pack is a local node pack.
Another way to obtain a node pack is to create one yourself, as described in the chapter about creating our first node.
A node pack that you create is also called a local node pack, since you didn't install it with pip.
Of course, if you desire, you can also upload it to PyPI for others to install, as described in this chapter. If you do that, when you or others install your node pack from PyPI, it will also be considered an installed/installable node pack.
We just explained how to obtain node packs, but how do we find them? Well, node packs are created individually by Nodezator users, so the users need to share them with us on PyPI or over the web for us to be able to access them. However, to make it easier to find node packs, I created a website to gather links to them and to allow them to be searched using various criteria.
The address is https://gallery.nodezator.com.
The website already lists some node packs created by me to demonstrate the usage of Nodezator in different areas like image editing and data vizualization. You'll also find instructions to share your own node packs there, regardless of whether you'll just make them available for download or upload them for installation with the pip command.
Now that we learned the different ways to obtain node packs and the 02 kinds of node packs that exist, we are finally going to learn how to load them.
Loading nodes consists in referencing node packs in the .ndz file where you want to use them. That is, you just need to tell Nodezator where to find the node packs you want and they are automatically referenced in the .ndz file and their nodes are loaded. Any .ndz file can reference one or more node packs of any kind (or no node pack at all).
The first thing to do is to create a .ndz file. Just click the New file action in the splash screen or click the menubar command File > New. The <Ctrl+N> keyboard shortcut also does it. A new untitled empty file will be automatically created and opened for you, so you can start working right away.
Right-clicking the screen will bring the popup menu into view, where you'll be able to instantiate nodes. However, only app-defined nodes will be available, that is, the ones already included in Nodezator. This is so because you didn't load any node packs yet.
To load or remove node packs in any .ndz file, just click the menubar command Graph > Load nodes. You'll be presented with a form to load or remove node packs from the .ndz file. The form is similar to the one in the image below:
The form presents several controls. In the previous image, I numbered them from 1 to 4 to make it easier to refer to them.
You can freely edit the form without worrying about doing anything wrong because the changes only take effect after you click the "Apply changes" button in the bottom right corner. If you regret any changes made, just click the "Cancel" button beside it.
The controls from 1 to 3 are used to add node packs to your .ndz file.
The control number 4 is a panel that shows which node packs are currently loaded in your .ndz file and the ones that you added using the other controls, the ones that will be loaded once you press the "Apply changes" button. In this panel, the "x" button to the left of each node pack listed is used to remove the node pack from the file (again, the change will only take effect after/if you press "Apply changes").
The form presents 03 different ways to add node packs. First, you can use the control 1, which is an option menu listing known node packs, that is, node packs you have successfuly loaded before. Both local and installed node packs are listed there.
Second, to add local node packs, you can use control 2. clicking the folder icon button and selecting the node pack folders you want in the file manager dialog that opens.
Finally, you can also add installed node packs, using control 3. Just type the name of the node pack (or multiple node packs separated by commas) in the entry and click the '+' (plus) button beside it.
You can add node packs using the ways described above multiple times. Every time you add node pack(s), the panel (control 4) is updated. It can be scrolled further if you add more node packs than can be seen in the panel. Once you are satisfied with your selection of node packs, press the Apply changes button.
If everything goes well, after clicking Apply Changes all the selected nodes should be loaded. You can test this by right-clicking the screen and checking whether their categories are now visible in the popup menu that appears. Don't forget to save the file so the changes persist. You can do it at this point or later after you finish working on it, just make sure to do it before you quit.
Another important thing to keep in mind: if you attempt to remove node packs when there are nodes from any of those packs that are currently instantiated in your graph the operation will be aborted. If you want node packs to be removed you must first make sure that none of their nodes exist in your graph.
The button at the lower left corner of the app that says How to load nodes just opens this page of the manual.
Now that we learned how to load nodes, I'd just like to share common problems/situations that may happen when opening a .ndz file you got from someone or downloaded online.
First of all, if the nodes in the pack you are loading use other third-party libraries, you must also install them in order to use the nodes. For instance, if you download this local node pack that uses the Pillow library for image editing you must also have the Pillow library installed for it to work properly.
It is expected that you won't have to do this for installed node packs, because people who upload their node packs to PyPI are encouraged to have any third-party library used by their nodes marked as dependencies so that they are installed automatically when users install their node packs with pip. After all, installed node packs are Python packages and can trigger the installation of extra libraries if needed.
If you picked a .ndz file from someone else and that file references installed node packs, remember you must first install them in your system using pip. If you don't, a dialogue is presented to you when you try to open the .ndz file, explaining the problem and the operation is aborted.
For instance, if you try to open a .ndz file that references the mynodepack installed node pack, but you don't have it installed, the following dialogue appears:
If you see a dialogue like that, just install the missing installable node packs and try opening the .ndz file again.
If the .ndz file you are opening references local node packs, you'll also need a copy of the local node pack to be able to open it.
As we explained, references to both local and installed node packs are saved in the .ndz file when you load their nodes. For installed node packs, Nodezator only stores their names. This is so because Nodezator just needs the name of the pack to access it. After all, installed node packs are just Python packages installed on the system, so Nodezator just has to import them. People don't need to know where Python's standard library module math is located in order to use it, right? they can access it just with its name by executing import math in their code. Likewise, Nodezator just need the names of installed node packs.
Local node packs, however, are referenced in .ndz files by their location in the system, that is, the absolute path to the folder containing the nodes. So, if the .ndz file you are opening references local node packs, there's an additional step needed: you'll need to update the node pack's location.
So, for instance, let's say Jessie sent a .ndz file and a local node pack (a folder named jessie_nodes containing the nodes used) to a friend called Jackie. When Jackie opens the .ndz file, inside its data the local node pack path will point to C:\Users\Jessie\node_packs\jessie_nodes which is the original location of the node pack is Jessie's computer. However, that location doesn't exist in Jackie's computer, but instead, the copy of the node pack Jackie received is saved in the C:\Users\Jackie\Downloads\jessie_nodes location.
This means when Jackie attempts to open the .ndz file, Nodezator will notice that there's no jessie_nodes node pack in the original location, so it will ask Jackie to provide the new location using a dialogue similar to the one shown below:
Fortunately, the solution is simple: just click the button that says Select replacement/new path then browse the file manager that will be shown to you to the location where the needed node pack is and select it by clicking on the folder and then pressing the Submit button. If there's no other problems with the new path you provided or other local node packs referenced in the file, the .ndz file should load without problems from now on.
Beware that other kinds of problems may be found in both local and installed node packs when opening a new .ndz file or loading them in a newly created .ndz file. They will cause other messages to be displayed. Those problems might be related to requirements of node packs not being met. For instance, the path to the node pack is right but the node pack itself might be structured in the wrong way.
If such an error occurs, replacing the path won't solve the problem, since the path is already right. Instead, you'll have to cancel loading the file (by pressing the corresponding button in the dialogue) and fix the contents of the node pack yourself or ask the creator/maintainer to do this.
When in doubt, read the message on the dialogue carefully and/or check the contents of the chapter that explains how node packs are organized to make sure the node pack you are trying to load has no problems.
User-defined nodes are identified in the .ndz file (in the script_id keys) using a combination of the node pack name, the category name and the script folder name where the node script is located. This is so regardless of whether the node pack is local or installed.
As such, if you rename any of those folders and open a .ndz file containing nodes affected by the renaming, Nodezator will look for the old folder names in the identification of the node and won't find them and will thus show a dialogue with a general message saying that one or more errors were found when trying to load the node packs, like in the image below:
This general message will actually appear for many other kinds of problems that can be found when trying to load node packs (either by opening a new file or via the form from the Graph > Load nodes option in the menubar).
Just like the dialog says, the full error(s) report can be found in the user log. Opening the user log will explain the problem in detail. In our specific case, the problem reported is a node script that could not be found (it is missing), as seen in the screenshot of the user log shown below:
To solve the problems, just open the .ndz file in any text editor of your preference and look for the lines that say script_id, and update the names of the folders you changed. It may be boring but is usually quick work. As Nodezator evolves over time, dedicated UI should be created so the user can perform this task in the app itself.
Updating the source of your nodes is fine, you must always improve them when you can or when it is needed. However, be careful when changing the function/callable signature. If the new signature is incompatible with the previous one, it will create conflicts when trying to open the .ndz file containing instances of that node.
For instance, connections between nodes are stored in .ndz files using the name of the parameters/outputs and other relevant data. If you rename the parameter or output of a node that is in your .ndz file, Nodezator won't be able to find that parameter/output anymore, so it will display a dialogue describing the problem and abort loading the file.
Hence, if you change the name of parameters/outputs or make other changes that result in an incompatible signature, your file will become invalid or you'll have to update the .ndz file by hand yourself.
A feature that consists in a conflict resolution mode for Nodezator, to guide the user in the resolution of such problems is already listed among the planned/requested features for Nodezator.
For now, if you want to update the signature of a node that is in use, it is easier to delete the instances of that node in the related .ndz files, make your changes, than instantiate and reconnect the node again. Or just seek help on the discord server.