In this tutorial, we’ll deal with file handling and the project system that helps referencing the files.
Let’s open the File Browser panel. Here on the left side we already see the Projects section listing the project folders. What are these project folders? They are specially handled privileged folders on our drive that can be used to store our distinct project materials. We’ll discuss their exact location on the disk a bit later. Of course, the system provides access to any folders on any drives directly, so what is the advantage of thinking in privileged project folders?
To exemplify this I’ll load a texture from the Common project’s Tutorials folder. Let’s choose this carpet texture. But, of course, we must have a compound to drop the texture into, so I create an empty one. Upon dropping the texture an Image module is created which has a reference to the file I dropped, namely in its Image File property. Here we can see the path of the texture file, and this is what I want to show you.
We can see immediately that this is not a standard path format. It begins with a project name in square brackets, in this case, “Common”, then continues with a colon and the relative path of the file within the project. This means that we can specify a file location referring directly to a project folder. This can be very advantageous. For e.g. suppose we create a compound that refers to files located in another project. It can be the “Common” which contains commonly usable files for everyone but can be a project containing third-party visual elements. In this case, we can share our compound with all other users that also have this third-party project installed, without worrying about the exact location of the project on their drives, since the system will find the referred files by the project name itself.
Where is the actual location of these project folders? We can specify it ourselves. We have to provide one or more so-called Project Root folders, and simply all the subfolders of these roots will be considered as project folders by the system.
The first occasion we can specify a root is the installation of the Aximmetry software itself. First, the installer asks for the location of the software, then the next page is what we are interested in. Here we can choose an arbitrary folder, or we can leave the default, which is a subfolder under our personal Documents folder.
So if after the installation we go into the Documents folder, then into Aximmetry, we can see a folder named Projects. Its subfolders are the ones considered to be the project folders by the system.
This location can be modified at any time. When starting the Composer, in the Startup Configuration we have a Preferences section and a “Project root folders” list within it. The fact that it is plural is not accidental here, since the system can gather the project folders from multiple root locations if necessary. Let’s add another root. For e.g. create a folder named “AxiProjects” on drive C. Then select it, and we can see that it is added to the root folder list. This means that the system will gather all the subfolders from the original default location and from the new folder we’ve created as well, and will display them as project folders.
For the sake of demonstration let’s create a couple of subfolders under AxiProjects. Make them Test1 and Test2. If we now start the Composer we can see these folders listed among the Projects.
Of course, we can create new project folders from Aximmetry as well. Let’s right-click on the Projects list, then choose New Project. If we have multiple root folders, we are offered a list from them so that we can choose the one where we want to create the new project. Let’s select AxiProjects, then name the new project Test3. If we return to Explorer we can see that the Test3 folder has been created within the AxiProjects root.
We can see the advantages easily. The compound located in various projects can refer to files from other projects without the need to know the exact absolute location of these folders. What’s more, later we can relocate these projects to another drive. For e.g. we can move the Test1 and Test2 projects to another root folder while leaving Test3 at its current location - the references to these projects won’t break at all.
Having clarified the nature of the project folders we can step forward to the discussion of the File Browser operations.
First of all, how can we find a specific file? If we know its exact location, we can step through the folder hierarchy as usual to reach it. For e.g. let’s load a tutorial compound from the Common project. Let’s enter the Tutorials subfolder with a double-click, then the Getting Started, and select the 3D tutorial and load it with a double-click.
The loaded files are always displayed with bold font within the File Browser, and also their containing folders. If we step through again starting from the Common folder, we can see that Common itself is displayed with bold, and also each subfolder that contains the loaded file.
Each folder we loaded something from or saved something into is added to the Recent section here. So it’s basically the list of the recently used folders sorted by the access time in descending order. With a simple click, we can return to these folders. We can remove the items no longer needed from here using the context menu.
Besides the recent folders, we can easily access the recently loaded document files as well. For that here is the Recent button on the toolbar that opens the recent document list also in descending time order. From here we can easily reopen the latest compound for example.
The frequently used folders can be marked as Favourites. If I enter a folder, for e.g. our Getting Started one, I simply click the star button here, and the folder is added to the Favourites section. Clicking the star again removes the folder from the list. Let’s add a couple of other folders. For e.g. the folder containing the Standard shaders is usually a frequently used one. Let’s enter the folder - it’s important to note that we must enter it, it’s not enough to select its name on the previous level - and then we can mark it with the star. Let’s choose a folder among the Texture ones as well, for e.g. the Test.
The favorite folders can be rearranged using drag-n-drop. Using the context menu we can remove them. Also, we can give them custom names for easier recognition. Right-click the item and choose Name. Let’s name this folder “Standard Shaders”. From now on it appears in the list with that name. If we want to return to its original path display mode we simply choose Unname from the menu.
Let’s return to finding files. In practice in many cases, it’s much easier to find a file by its name rather than browsing through the folders. We can do this by using the search field here. It’s important to note that we can only search for files that reside under the project folders. So we can’t search generally on all drives on the PC. The easiest way to jump to the search field is using the Ctrl+Shift+F combination. It reveals the File Browser if it’s currently hidden, and puts the focus on the search box, so we can begin typing the search expression right away. The equivalent menu operation is the Find item within the File menu.
The search expression itself can contain one or more parts of the name we are looking for. For e.g. to find all the Getting Starting tutorial files we can type “getti”. Or if we want to find the shaders that are capable of handling of both normal and specular maps, we can type “nor spe”, and we get all the matching shaders. Of course, from here we can drag-n-drop them into the compound right away.
We may want to know where these files are located in the folders. If we move the mouse over a file name, after a while a green tooltip appears containing the exact path and other data. Also, we can right-click the file and choose Go To to jump to the folder containing the file.
We can narrow the search by file type. The search expression works on the filename extensions as well. If I type jpg, all the JPEG files are listed. But it can be more straightforward to search by Aximmetry’s own file type categorization. Let’s search for all files containing “test” in their names. The result list contains files of several different types. Using the File Types section here we can narrow the list. The file types can be turned on and off individually by left-clicking them. Right-clicking an item select it exclusively. In this case, we only see the image files in the search list. Right-double-clicking any item will select all the items again.
Let’s see all the ways a file can be loaded or opened. If it’s a document file for e.g. a compound, it can be opened in a way we’ve seen before, by double-clicking on the file. It can also be drag-n-dropped, in this case, it must be dropped to the header of the main window. The third way is the most conventional, we choose the Open menu item, and get a dialog where we practically see the same File Browser interface. The focus is on the search field, so we can start searching right away if we want. We can open the selected file either by double-click on it, or clicking the Open button.
There are file types that cannot be opened in themselves but can be added to an open document, for e.g. textures, shaders, models, etc. They also have multiple ways to add to the document. The first is a simple drag-n-drop from the File Browser. For e.g. let’s load a texture. We simply drop it into the compound. When files of such types are dropped into the compound a new module with the corresponding type is created. In this case, we’ve dropped a texture file, therefore we got an Image module that already contains the reference to the texture file in its property. Similarly, if we add a video file, we get a Video Player module, also with a prefilled property referencing to the file. We can add shaders, Collada models, XML and JSON files, and so on in a similar manner.
So, how can we replace an already added element? Let’s see this Image module. I expose it out so we can watch its changes. Now we want to replace the texture it refers to. The first way is that we simply drag-n-drop another texture file onto the existing module. This changes the file reference and the name of the module as well. We can also drop the file to this editor field of the file name property. In this case, the module name remains unchanged. The third way is obviously the editing of the property itself. We can type or copy a path here, but we can also click the button with the three dots to bring up a File Browser dialog we’ve already seen. Here we have a special feature, the Instant preview. If we turn it on, we can preview the result in the scene continuously while traversing among the image files.
Let’s display the 3D scene again. If we look at a module type that has multiple file references, for e.g. this shader which has several texture properties, we can use the latter two methods to change the textures. Let’s select this carpet texture. We can drop it to the Color Map property of the shader. We can see that the texture of the floor has changed. We can drop the file onto the module pin itself, too. Or we can use the browser dialog, where we can watch the floor texture changing as we’re traversing among the files. The same goes for the Normal Map as well.
A further useful feature is that we can drag-n-drop files not only from the File Browser but from the property editor as well, by grabbing the name field of the property. This operation is effectively identical to the grabbing from the File Browser. For e.g. we can drop it to the compound. This way we practically extracted a constant property value and added it to the scene as an Image module. What’s the benefit of doing that? It can be several things. For e.g. we can connect the same texture to multiple shaders. After that, I can change the texture of both shaders simultaneously. Or we can do some processing on the texture. For e.g. I can add an Adjuster and wire it between the Image and the shader, and shift the Hue property. We can see the parquet color changing.
Another important convenience has resulted from this method. To demonstrate it I load a PNG texture into the shader. Let’s make it a cloud texture. If I start dragging the texture from the property editor, we can drop it not only inside Aximmetry, but we can transfer it to another application. For e.g. let’s drop it onto Photoshop. After that, we can modify the image, let’s paint a red stripe into it. One of Aximmetry’s important feature is that if a referred file is changed by an external application, Aximmetry reloads it immediately. So if now I save this repainted texture from Photoshop, the change is immediately reflected in Aximmetry.
Of course, I can drop the file into any other application that allows it. For e.g. by dropping it into Windows Explorer we can copy the file to another folder. These operations also work in the opposite direction. From Windows Explorer we can drag-n-drop files into Aximmetry, either adding them to the compound or, by dropping them to the File Browser, we can copy them into a project folder.
It’s also worth noting that if I drop a file that is located under a project folder - let’s enter the Common project and drag-n-drop a video file from it - then Aximmetry recognizes that it is from a project folder, and automatically puts the file path into a project-based format. So we can see that there is a very natural relationship between Aximmetry’s file system and Windows Explorer.
Of course, we can perform file operations within File Browser as well. Let’s copy some videos from Common to another project. For e.g. the folders Misc and Textures. Select and right-click them and choose Copy. We switch to the target folder and choose Paste. Thus the copy operation is performed.
There is another way to load files I haven’t mentioned yet. If you don’t like the drag-n-drop method from the side File Browser, but prefer the traditional Open dialog way, you can use it as well. Right-click on an empty area and choose Import File - or you can simply use the Alt+Insert shortcut. The usual file selector dialog comes up. Let’s find for e.g. our parquet texture and open it. An Image module is added to the compound as before.
Replacing the texture also can be done with the Open dialog method. We’ve seen this before, using the Pin Values editor. But we can also bring up the dialog by a simple double-click on the module, and - in this case - we can select between textures. This method can be used on other module types that hold a file path, for e.g. Video Player.
Let’s talk about the shaders a bit. Here the drag-n-drop method also works. If we want to change the shader type, we can simply drop another shader file onto the module. This time I replaced my Norm shader with a Flat shader. During this operation, the system tries to carry as many property values as it can into the new shader. It matches them considering their name and type. For e.g. we can see that the Color Map property got through, but the Normal Map value was lost because the new shader doesn’t have such property.
Here we can also use the Open dialog method. Right-click the module and choose Change Import Source. In the displayed dialog we can pick the desired shader type. We can also find the Import Source property in the Pin Values editor. By clicking the three dots button we get the same file selector dialog.
Let’s return to the compounds for a bit. In other tutorials, we demonstrated that we can drag-n-drop a compound file inside the edited compound. By this, a so-called Linked Compound is created. For e.g. we can drop a complex effect available as a compound into our scene. Let’s pick a cartoon effect. By dropping it into the editor we create a subcompund that is linked to the file it’s originated from. Note that this operation differs from the one when I open the compound as a document. If I drop the file onto the header of the Composer window, it’s opened as a separate document. It’s important to differentiate these two opening operations from each other.
This is true for shaders, too. Shaders are different type graphs but can be edited in the Flow Editor similarly to the compounds. So if I drop the shader file into a compound, it’s added to the compound as a working shader. But by opening it as a separate document, we can edit the different components of the shader.
A Linked Compound or a Shader that is added to the editor also can be opened as a separate document without locating the file itself. We simply right-click the module and choose Open Import Source.
In the case of a Linked Compound, this is not needed usually, since Linked Compounds can be edited in-place. We right-click the module and choose Edit Compound In-Place. After that, we can enter the compound with a double-click as usual and can edit it.
Let’s return to the file search function. We have used it so far with file names or extension snippets. But the function is also capable of searching within the long descriptions and the tag list we can assign to the files. In the case of compounds, this extra information can be provided in the File Properties dialog. In the Information section, we can enter a Description here, let’s make it a Tutorial 3D scene. The tags can be provided by comma separation, let’s make it a sphere, cube, and a flower for the sake of testing. Let’s save the scene so that the information is written into the compound file. From now on we can search for the word “tutor” and we get our file based on its description. Or we can type “sphere” - we can see that this is not a very good choice here, there’s plenty of files named sphere. So type “flower” instead, and we get our compound again based on the added tag.
What can we say about the other file types? For e.g. the textures. In this case, we can assign descriptions and tags within the File Browser. Let’s see these parquet textures. We right-click the file and choose Properties. Here we can provide the extra information. Let’s add a “tutorial” tag. Since the information cannot be added to the image file itself, in this case, the system creates a separate file for storing the description and the tags. The File Browser won’t show this extra file to keep the file view undisturbed, but we can find it in Windows Explorer. It has the same name as the image extended with an “xdesc” extension. Now if we search for the “tutor” keyword both the parquet and the compound file come up.
Our last topic is the thumbnails. If we browse through the files we can see a thumbnail of most of them. In the case of images and videos, it’s trivially created from the content of the file. But in the case of the compound, we have to specify a thumbnail manually. It can be done in the File Properties dialog, in the Information section, along with the description. One method is to draw a custom image in a third-party app and assign it to the compound using the Load button. But in most cases, the simplest way is capturing a frame from the rendered output. Simply click the Capture button, and we can see a new picture with the modified floor texture. Save the compound, and from now on by selecting this compound in the File Browser we’ll see the new thumbnail.
This concludes the tutorial of the file system.
