The Library

From Terragen Documentation from Planetside Software
Jump to: navigation, search

Introduction[edit]

The Library collects assets for use with Terragen 3. The Library window displays the assets that have been added to the Library. It collects assets from multiple locations on disk into one window for ease of browsing and adding to your scenes. The Library window can be used in addition to the existing Open dialogs for various assets.

The Library is only available on Windows and OS X. The Linux render node obviously doesn't have a UI for the Library, but it also doesn't create any of the supporting files for the Library either.

Currently the Library can handle the following types of assets:

  • Clip files
  • Heightfields (including DEMs)
  • Image files
  • Object files
  • Project files

Opening the Library Window[edit]

The Library window can be opened in various ways. To browse everything in the Library, choose "Library" from the "View" menu.

The Library can also be used for loading specific asset types. For example if you choose "Load Project from Library" in the "File" menu the Library window will open in Project mode, which means it will only display projects. Similarly choosing "Import Object from Library" will open the Library window and only display objects.

When the Library window is first opened it may take some time to be ready for use. This is because the Library information is being loaded. The window will open much quicker the next time you use it. Similarly the main list may be a bit slow the first time you scroll through it as previews are loaded, but it will be faster after that.

Library Concepts[edit]

This section explains some of the basic concepts related to the Library.

Types
The Library handles the following types of files:

  • Clips
  • Heightfields
  • Images
  • Objects
  • Projects

When assets are added to the library they're automatically assigned one of these types. The type cannot be changed.

The item type is used in several ways. When you open the Library for a specific type, for example by choosing "Import Object from Library" in the File menu, only items of that type are displayed in the Library window. If you open a Library from the View menu a set of Types items are available in the contents list which let you filter the items displayed by type.

Categories
Library items can have a category assigned to them. Categories correspond to the different project views in TG, such as Atmosphere and Cameras. At this stage categories are only really useful for clip files. With clips they're used as a hint for where they should be inserted into the node network. You can assign a category to types other than clips but this is currently only useful as an organisational tool in the Library, allowing you to filter the items by category.

Storage
The Library doesn't enforce any particular storage scheme for items added to it. The original file location on disk is used. This can mean that if you move a file the Library may not be able to load it. This is less of a problem on OS X.

Library Window Overview[edit]

This section gives an overview of the Library window and the different areas it is made up of. The following screenshot is divided up into different sections which are explained further below.

Library window marked up.jpg


Contents List (1)
The contents list is located in the top left of the Library window. It allows you to view the library contents in different ways, for example you can view recently added items, favourites or items organised by type. When you select an item in the contents list the main list updates to show library items that match that criteria.

Info Panel (2)
The info panel is located at the bottom left of the Library window. The info panel displays and lets you edit information for the library item selected in the main list. By default the info panel is shown in condensed mode, which just shows the item preview, if available, and the item name. You can click the information button at top left of the info panel to expand it and all the information about the library item. The screenshot above shows the info panel in its expanded form.

Top Toolbar (3)
The top toolbar is situated above the main list. It contains settings for how library items are displayed in the main list. It also has various ways of interacting with library items such as creating favourites, showing the files for items in Explorer/the Finder and adding new items to the library. It's described in greater detail below.

Main list (4)
The main list takes up the bulk of the Library window and displays the items in the library. The items displayed depend on what's selected in the contents list and the current search (see below for more info).

The main list can be viewed in a number ways. There are two main display modes. The first mode is browsing mode which shows previews for all items plus additional information. The second mode is the list mode which displays items as a text list. The way items are displayed can be changed with the Display popup list in the top toolbar.

Bottom Toolbar (5)
The bottom toolbar is underneath the main list. It contains two groups of controls. On the left are the search controls, which allow you search for items in the library. On the right one or two creation buttons are displayed when an item is selected in the main list. These buttons are used to add items to the scene. The bottom toolbar is described in greater detail below.

Adding Items to the Library[edit]

There are several ways of adding items to the Library:

  • To add multiple items at once you can click the "Scan Folder" button in the top toolbar. This allows you to choose a folder on your hard drive to scan for items that can be added to the library. When you click the button a dialog opens which allows you to choose what sort of items to load and whether to scan subfolders as well. Click the "Choose Folder..." button in that dialog to choose a folder and start scanning.
  • Items can be added automatically to the Library when you open/load them. For example projects can be added to the Library when they're opened. You can control what gets added automatically using the Library preferences panel. By default all supported types are added to the Library automatically.
  • Items are added to the Library automatically when they're saved. For example if you save a project it will be added to the Library. This behaviour can be turned off in the Library preferences panel.

Removing Items from the Library[edit]

There are two ways to remove items from the library:

  • Select items in the Library window main list and press the delete key. Multiple items can be deleted at once.
  • You can delete the entire Library using the "Delete Library Database" button in the Library preferences panel.

Removing items from the Library cannot be undone.

Item Previews[edit]

Library items can have preview images. These are shown when the main list is in browsing mode and in the Info panel. In some cases these previews are generated on the fly for you by TG.

Previews are generated for objects when they're imported into a scene. TG also attempts to load Xfrog billboard images to use as previews when an object is being added to the Library. In the future there will be a way to generate previews for all objects in the Library without having to import them into a scene first. You can set up a preview image which TG will load when adding an object to the Library. Please see the Advanced Topics section below for more information.

TG generates previews for images and heightfields. You might see red areas on the previews generated for DEMs. These red areas represet NODATA values in the DEM.

You can assign a preview to a library item using the Preview button in the Info panel. When you assign a preview to a project or clip file the preview is added into the file itself. This means you can send the file to someone else and they'll be able to see the same preview in their Library.

You can double click the preview image in the Info panel to see it larger in an Image Preview window.

Previews can be removed from library items using the Preview button. Note that TG will add a new preview for the image if the library is one of the types it can generate previews for. You can assign a new preview to an item without clearing the old one first, so you don't have to worry about TG generating new previews when you want to add a new one.

If the preview is displayed with a question mark in the lower right corner this means the Library is unable to find the file for the item is missing, or in other words it can't be found on disk.

Creating Items using the Library[edit]

There are a number of ways to create nodes etc. using the Library. What happens will depend on the type of the item:

  • Clips: Clip files will be added to the network.
  • Heightfields: Heightfields are created as Heightfield shaders with an appropriate heightfield loader node attached. You can also load the heightfield as a DEM.
  • Images: Images are created as Image map shader nodes.
  • Objects: The appropriate object reader node will be created. You can also create populations.
  • Projects: The project will be opened. You'll be prompted to save any changes to the current project if needed.

You can open Library items in the following ways:

  • Double click
    Double click a library item in the main list and will be created as mentioned above. Heightfield and objects can also be created by holding down the alt/option key and double clicking. For heightfields this will create a Geog Heightfield Load node to load the heightfields as a DEM, as opposed to the Heightfield Load node created with a regular double click. For objects a population will be created.
  • Creation buttons
    The Creation button(s) are shown in the bottom toolbar when an item is selected in the main list. One or two buttons might be displayed. For example if you select a project item then a "Open Project" button is shown. If you select an object item both an "Import Object" and "Import Population" button are shown.

  • Drag and Drop
    You can drag and drop all items except for projects to the network view and appropriate nodes will be created or clips be added. You can also drag certain item types to parameter view file buttons. For example you can drag an image from the library to the "Image filename" file button of an Image map shader and the image will be loaded into that parameter.

Only one item can be created at a time, even if multiple items are selected in the main list.

The Library Window in Detail[edit]

This section describes the different parts of the Library window in detail.

Contents list
The contents list lets you choose what is displayed in the main list. The options in the content list depend upon how the Library window was opened. If it was opened from the View menu then all options will be available. If opened for a specific item type, clips or objects for example, some options may not be available. Here's a description of the various options available:

  • All Library Items (or All {specific type}): This shows all the items in the library, or all the items of a specific type if the Library wasn't opened from the View menu.
  • Recently Added: This shows items that have been recently added to the library, although at the moment it displays all items in the library as there is no cut-off time.
  • Favourites: This item shows all the library items chosen as favourites. You can add a library item to the Favourites by selecting it in the main list and clicking the "Add to Favourites" button in the top toolbar.
  • Types: Expand this item to filter library items by type. This will only be available if the Library was not opened for a specific type.
  • Category: Expand this item to filter library items by category. This is not available for some specific types.


Info panel
The info panel displays and lets you edit information about the item selected in the main list. By default it's shown in condensed mode which just displays the preview and name to the time. Clicking the information button in the top left will expand the panel to show more information.

Changing information for a clip file in the info panel will also update that information in the clip file itself. This means that if you send the clip file to someone else they will see the updated information.

  • Information button (top left): Click this button to condense and expand the info panel.
  • Preview image: If a preview is available for the item it will be displayed here. You can double click on the preview to see it larger in an Image Preview window.
  • Preview button: This button allows you to perform several preview related operations. You can display the preview at a larger size in an Image Preview window, add a new preview from an image file and remove a preview from an item. See the Item Previews section above for more information about previews.
  • Name: This displays the name of the item.

Info tab
The Info tab contains the following:

  • Description field: This allows you to add a description for the item.
  • Date: This displays the last modified date of the file for the item. This is the date you would see in Explorer (Windows) or the Finder (Mac).
  • Poly count/Size: This field shows size information about the selected item. If the selected item is an object this field displays the poly count, if it's available. If the item is an image the image dimensions are displayed. If the poly count/size is not available a "?" is displayed. For items without size information a "-" is displayed.

Metadata tab
The Metadata tab contains the following:

  • Rating popup: This lets you choose a 1 to 5 rating for the item.
  • Category popup: This sets the category for the item. See above the Concepts section for a description of Library categories.
  • Tags field: This lets you add or remove tags for the item. You should use a comma to separate tags.
  • Comments: This lets you add a comment for the item.


Top Toolbar
These are the controls in the top toolbar, from left to right:

  • Display popup: This popup list allows you to choose how the items in the main list are displayed.
  • Arrange by popup: This popup list lets you choose how items in the main list are sorted/arranged.

  • Sort order button: Clicking this button changes the sort direction for the main list.

  • Add to Favourites button: This button lets you added the currently selected library item to the favourites.

  • Choose file button: This button lets you choose a file to open from disk, in case the file you were looking for wasn't in the Library after all.

  • Action button: Clicking this button pops up a menu which lets you perform a number of different operations. Here's what each one does:

    • Add files to Library: Choosing this opens a file dialog which lets you choose files to add to the library. You can select multiple files in the dialog.
    • Scan folder for Library items: This item will open the Scan Folder dialog. This will let you add multiple items to the Library at once by scanning a folder on disk. The dialog lets you choose what sort of files should be added, as well as whether subfolders of the folder you choose should also be scanned. That could potentially be slow. As an extreme example, let's say you chose to scan your Documents folder. There could many folders with many items inside them. You can always stop the folder scanning if it's taking too long, but it's just something to bear in mind.

      When you've set up how you want folder scanning to be done click the "Choose Folder" button to choose a folder and start scanning.

    • Show selected item in Explorer/the Finder: Choose this to show the file for the item selected in the main list in Explorer (Windows) or the Finder (Mac).

    • Only show missing files: Select this to have only missing files shown in the main list. These are items where the file cannot be found on disk. You can find out more about missing files below.

    • Refresh the Library: Choosing this will cause the Library to be reloaded and the Library window to be refreshed. One reason you might want to do this is if you have a lot of missing items because their files are on a removable disk. If you mount the disk and refresh the library the files will be found again.


Main list
The main list displays the library items. Which items are show depends on the settings in various other parts of the window. The main list has two basic modes - browsing mode and list mode. The mode is set using the Display popup in the top toolbar.

Browsing mode displays a preview as well as other information. There are three ways to display the items in browsing mode - "Icon", "Icon and Name" and "Icon Detailed". "Icon" just shows the item preview, or the name of the item if it doesn't have a preview. "Icon and Name" displays the preview with the item name underneath. "Icon Detailed" shows the preview, name, rating, date modified and item size (if appropriate). The rating stars can be clicked on set the rating.

When you're in browsing mode a tooltip shows with the item name when you mouse over an item. If you hold down alt/option when mousing over an item the tooltip will display the full path to the file on disk.

List mode displays the items as a text list. There are two ways to display the list - "Name" and "Name Detailed". "Name" only shows the item name. "Name detailed" displays the name plus several other columns of information.

You can open items from main list, for example to add an object to your scene or open a new project. You can do this by double click, using the Creation buttons or by drag and drop to the network view. Please see the Creating Items using the Library section above for details.

You can select multiple items in the main list. This is main useful for deleting items from the Library. You can only ever open one item from the Library at a time.

Missing files are shown in the main list in a special way. Please see the Missing Files section below for more information.


Bottom Toolbar
The first group of controls on the left of the bottom toolbar allows you to search for library items by name or by tag. The results of the search are displayed in main list. The search remains active either until you click the "Done" button or clear the search field.

  • Search options button: Clicking this button pops up a menu which lets you choose different options for searching, for example ignoring case or only searching for whole words.
  • Search field: This text field is where you enter search terms. Clear the field to stop searching and show all relevant items.
  • Done button: This button will stop searching. It clears the search field.

Creation buttons are shown on the right of the bottom toolbar. Different buttons are shown depending on what type of item is selected in the main list. Creation buttons allow you to perform actions like opening a project, adding a clip or creating a new node of the appropriate type for a library item.

Missing Files[edit]

For one reason or another the Library might not be able to find the file for an item. This might happen if the file has been moved, deleted, is on a disk which has been removed or similar.

Missing files are indicated in several ways. One is that the preview image is shown in the info panel and main list (when in browsing mode) with a question mark drawn in the bottom right corner. If the main list is using one of the list display modes the item text will be drawn in red. The name of the item in the info panel will also be drawn in red.

If you want to only see missing files in the Library you can choose the "Only show missing files" item in Action button, which is in the top toolbar.

If a file has been moved or deleted then you will need to remove it from the library. You are less likely to have problems with moving files on OS X.

If the file was on a removable drive or a network drive that isn't mounted the Library will be able to find the file when that drive is available again. If you have the Library window open when the drive become available again you might want to choose "Refresh the Library" from the Action button in the top toolbar. This makes sure the Library notices the files are available again and will also update the Library window.

Advanced Topics[edit]

As mentioned in the Item Previews section, you can set up an image file so that it will be used as the preview when an object is added to the Library. To do this you place a specially named image file into the same folder as the object file. The format for the file image name is :

(model file name)_preview.XXX

where (model file name) is the name of the model file and .XXX is the image extension. The supported image extensions are ".jpg", ".png", ".tif" and ".tiff". As an example let's say you have an object called:

Ryegrass_variant1.tgo

You would need to name the image file for the preview like this:

Ryegrass_variant1_preview.jpg

The preview image can contain an alpha channel. Note that JPEGs don't support alpha. TIFF is the preferred format for the preview image file.

The back end of the Library is a database and a folder containing any previews generated for Library items. The Library data is stored here on Windows:

and here on OS X:

~/Library/Application Support/Planetside Software/Terragen 3/Terragen Library

You can easily access these locations in the registered version by choosing "Reveal Key File" from the Help menu.

If you so desire you can delete the Library database or clear all item previews using the Library preferences panel.

When you delete the Library database all item previews are also deleted. It is important to note that deleting the Library database doesn't effect any files which were part of the Library. They are not deleted.

Some files may have integrated previews or previews may be generated on the fly (which can happen for images for example). Clearing previews will not effect those files. It won't delete integrated previews from files.

In a graphical user interface (GUI) on a computer a toolbar is a row, column, or block of onscreen buttons or icons that, when clicked, activate certain functions of the program.

DEM stands for Digital Elevation Model (or Map). A DEM is similar to a heightfield. DEMs are normally generated from real world measurements of a planet's surface, for example Earth or Mars.

A heightmap or heightfield is an array of height values, usually in a grid which describe the height at specific points in a defined area. Heightfields are used to represent real-world and virtual terrain in a specific, easily converted format. Most heightfields can be represented as simple image data in grayscale, with black being minimum height and white being maximum height.

A shader is a program or set of instructions used in 3D computer graphics to determine the final surface properties of an object or image. This can include arbitrarily complex descriptions of light absorption and diffusion, texture mapping, reflection and refraction, shadowing, surface displacement and post-processing effects. In Terragen 2 shaders are used to construct and modify almost every element of a scene.

A parameter is an individual setting in a node parameter view which controls some aspect of the node.