Editing a library

Overview​

In addition to the tree libraries included with Forest Pack and a comprehensive range of Xfrog, Evermotion and HQ Plants expansions it is often desirable to create and edit custom libraries to re-use and share commonly used assets. The library browser allows you to easily organise and edit your libraries and create new 3d objects and billboards.

Procedures​

To add and modify library locations​

1. With the library editor open go to File>Preferences… or click the preferences button from the top toolbar.

2. The Library Paths rollout shows a list of all the locations currently being used. To add a new location click on the Add button and navigate to the folder for your libraries.

   

3. In the Label field enter a location name to display in the tree navigator.

4. Click Use Path to add the location to the library and return to the preferences.

   

5. Click OK and you should now see all the sub folders and libraries displayed in the tree navigator on the left hand side of library browser.

Alternatively to modify or update an existing location​

1. With the library editor open go to File>Preferences or click from the top toolbar. Setting button.
2. To modify a location select it from the library paths list and click Modify.
3. Navigate to the root folder of the new location and select Use Path.

To organise and Create new libraries​

Each library location path can be further organised into subfolders. Forest Pack will scan these subfolders and replicate the directory tree in the tree navigator found on the left hand side of the library browser window. From this panel folders and libraries can be created and deleted using the procedures outline below, and the directory structure easily reorganised using drag and drop.

To create a subfolder​

1. With the Library Browser open, in the tree navigator on the left hand side, right-click on a user library and select Create Folder.
2. A new folder has been created. The name will be highlighted, type in a new name for the folder.

Alternatively to create the subfolders directly in Windows Explorer​

1. Navigate to the library location in Windows Explorer or locate it automatically using the Library Browser by right-clicking its name from the tree navigator and selecting Open in Shell…. Create your directory structure in the usual way using Windows Explorer

2. When you are done, update the view in the Library Browser to reflect the new directory tree by clicking on the Refresh button (button image)from the top toolbar or select from the View menu.

   

   The same directory showin in Windows Explorer and the Tree Navigator

To create a new library​

When you create a library Forest Pack creates a new folder that includes an XML file and sub folders for thumbnails. This and any other sub folders found in the library location will not be displayed. This allows you to add additional directories for models, maps and materials used by the library without them cluttering up the tree navigator.

1. In the tree navigator, right-click on the folder where you would like to save your new library and select Create Library. The library name will be highlighted, enter a title and press return
2. If you need to rename your library at a later date, simply right click on it and select Rename.

To delete a library or folder​

1. To delete a folder or library, simply right click and select Delete.

To add a new object or preset to a library from the scene​

It is possible to add selected objects from a scene directly to a library with just a few clicks. This can include Forest Pack object which will be added as a complete preset with their source objects.

To add a new object or preset​

1. Select the objects you wish to add to the library

2. Open the Library Browser using the button on the Forest Toolbar

3. Navigate to the library to which you wish to add the items

4. Right-click in the items list and select Import Objects.

5. A new dialog will open with a number of options. For the most part you won't need to change much here, and it's pretty self-explanatory, but let's take a look at what each option does.

   

   Create 3DS Max Scene Allows you to change the name of the Max file to store the new library objects. You can let FP automatically name files for you, or you can specify them manually. The browser cannot add objects to an existing file, so a new max file we be created each time you run the process, and you'll be warned if you try to overwrite something

   Create Material Library will save the materials assigned to the objects to a new material library. The materials in this library are assigned to the objects on import. we separate them in this way to allow users to have a different matlib for each renderer should they want it. If you choose a material library name that already exists, the new materials are appended to the existing file. This option allows you to overwrite the file instead.

   Collect Assets moves all the external files referenced by the selected objects to a Maps folder in the library location. This will help to ensure that assets never go missing and can be found by Max.

   Create Thumbnails Allows you to create and assign a thumbnail captured from the viewport for each object. 6. Click Import. Wait a few seconds and the items will be added to the whole library

To add a new 3D object to a library from a file​

3D geometry can be added to any library saved in a user location (represented in the tree navigator as a green folder). Items are stored in .max files located anywhere on your computer or network. However, sharing is simplified if the files and any material libraries and bitmaps use relative paths and are located in the library folder. If images with the same name as the object are placed in the thumbnails folder, these will be used automatically.

To add a new 3d object​

1. From the navigator on the left, select a user's library.

2. Right click in the browser and select Create Item>3d Object

   

3. A new blank 3d item will be created in the item browser. To edit, right-click on the item and select Properties…. Fill in the Taxonomy values, note that the common name is the text displayed by default in the library browser though this can be toggled to display the Latin name. Other values can be left blank if not required

   

4. Click on the folder item next to the Max File field to select the .max scene file that contains the new object 6. A list will open containing the objects in the scene, pick the item you wish to add to the library.

1. If the object had a material applied this will be also be used in Forest Pack. It is also possible to override the material from an external material library. In order to do this enable the Override Material tick box.
2. Select the material library by clicking the folder icon next to the Mat. Library field. Find the library and click Open. Next click the Select Material button, this brings up a list of the contents of the material library. Highlight the material to be used and click OK.
3. Add a thumbnail by clicking the image file button below the thumbnail preview window. Select an image file and click OK.
4. Click OK to accept the changes
5. Save the library by going to File>Save or selecting from the top toolbar.

To create a new preset​

Creating a new preset is the same as creating a new 3d object, the only difference being that you select a pre-made Forest object in an external file instead of a mesh.

1. First prepare .max files, these will contain a separate Forest object for each preset. Configure the Forest object's parameters as you would normally include geometry, distribution, transforms, materials, diversity etc.
2. Save the max file to your Forest library folder, see below for more information on file structures.
3. Open the library browser and from the navigator on the left, select a user library.
4. Right click in the items grid and select Create Item>3d Object. A new blank Preset will be created in the item browser. To edit, right-click on the item and select Properties…. Fill in the Taxonomy values if required
5. Click on the folder icon next to the Max File field to select the .max scene file that contains the preset (created in step 1).
6. A list will open containing the objects in the scene, pick a Forest object that you wish to use as a preset. A single max file can contain multiple objects, geometry and presets that be combined in a single external file without problems.
7. Add a thumbnail by clicking the image file button below the thumbnail preview window. Select an image file and click OK.
8. Click OK to accept the changes
9. Save the library by going to File>Save… or selecting from the top toolbar.
10. To use the preset, select in the same way as though it were a 3d object. See the Library Browser reference for more information.

To add a new billboard object to a library​

2D billboards can easily be added to a user's library. These are loaded from a material library file that can be saved anywhere on the local machine or network though for ease of sharing it is common to move the files to the library folder and use relative paths.

1. From the navigator on the left, select the library you wish to add a new object too.

2. Right click in the browser and select Create Item>Billboard

   .

   A new blank billboard item will be created, to edit it right-click on the item and select Properties…. As above, fill in the Taxonomy values.

3. Choose the material library by clicking on the folder icon to the right of the Material Library field, select the library and then Open.

   

4. Choose the material from the library by clicking on the Select Material button to bring up a list of the contents, select a material and click OK.

   

5. Add a thumbnail by clicking the image file button below the thumbnail preview window. Select an image file and click OK.

6. Set a Default Height and Width from the Dimensions settings. To retain the proportions of the image ensure Keep Aspect Ratio is turned on.

   

7. The center point for the rotation, scale and position can be adjusted using the Center Offset and ZOffset attributes, represented as a percentage. A dashed line on the thumbnail illustrates the effect of these settings. Typically, the lines should intersect at the base of a plant's trunk or stem.

   

8. Click OK to finish and save the library by going to File>Save Library or pressing F2

To adding multiple 3D objects to a library​

The library editor can speed up the creation of libraries by loading multiple objects from a single scene file

1. Open the Library Browser and use the tree navigator to locate the library you wish to add items to.

2. Right click anywhere in the items grid and select Import Objects…. An Import From Scene window will open, select the .max file containing the objects by clicking on the ellipsis (…), locating the files and clicking Open.

   Adding objects from multiple .max files

   It is possible to import objects from multiple source files. To do this, you just select additional .max files while holding down CTRL or SHIFT.

3. You will now see a list of all the objects in the scene. Select the items you wish to add to the library. Use control and shift to select multiple objects in the usual way.

   

4. Click import. If bitmaps are located in the thumnbnails folder with the same name as the items being loaded, these will be used as previews in the item browser.

5. If necessary edit the objects as described above.

Adding Multiple Billboards to the Library​

The library editor can greatly speed up the creation of libraries by loading multiple billboards contained within a single material (.mat) file. When creating libraries using this process thumbnails can be generated automatically and materials can remain in the original location or be consolidated into a single material file in the library folder.

Prerequisites​

• A single .mat file containing multiple billboard materials.

To add multiple billboards​

1. Open the Library Browser and use the tree navigator to locate the library you wish to add items to.

2. Right click anywhere in the items grid and select Import Billboards…. The Material Importer will open. Select a material library by clicking on the ellipsis under the Source section. Locate a material library and click open. Highlight the billboards you wish to import.

   

3. Under the Catalog Location section tick the desired options:

   Create Items in Forest Catalog adds the selected materials as billboards to the active library

   Create Thumbnail Images automatically generates thumbnails from the diffuse maps of the selected materials

   Create Material Library consolidates the selected materials into a single material library located in the library folder. There is also an option to automatically convert them to Forest Materials.

   The default settings are generally OK.

4. Click Import and the materials will be added to the library.

To add a macro to assign a material according to the active renderer​

When creating libraries it is possible to use macros to add variables to an item's property fields. This is very useful for creating flexible libraries that can dynamically respond to individual installations or changeable 3DS Max settings. One common usage is the creation of library items that automatically load appropriate materials based on the active renderer.

Auto-loading a material library by renderer​

1. Either create a new object as described above, or right click and select Properties to edit an existing item.

2. Turn on Override Material this allows you to use a separate material library to texture the object. In this example it will automatically select a different material library according to the current renderer.

3. In the Max File field type the parts of your material library name that is common to all files. In the examples given above you would type MaterialLibraryName-.mat

4. Position the cursor where you want to add the renderer variable, in this case it would after MaterialLibraryName- and before .mat. Click on Macros… and select hdfreerenderer from the subsequent list. Click OK to add the variable to the filename. The material filename should now read MaterialLibraryName-$(HDFREERENDERER).mat.

   

5. Select an appropriate material by clicking the select material button and picking one from the list. If the materials are identically named in each library, this macro will change the material depending on the currently selected renderer.

Interface​

Library Browser Preferences​

To access the Library Browsers go to File>Preferences or click from the toolbar

Name	Description
Use scene material	When selected in the event of a a duplicate material the version already in the scene will be used
Replace material from library	When selected in the event of a a duplicate material the version in the library will be used
Ask user	When selected in the event of a a duplicate material the which of the two options above should be used
Merge into scene	When adding objects the geometry will be merged into the scene.
XRef to library	When adding objects the geometry remains in a external file and is XRef is used to add to the scene
Add...	Adds a new library location.
Modify...	Modifies the location of an existing library.
Delete	Deletes a library location.
Evaluate	Shows the currect values for all macros.

---

Folder and Library Addition​

Use the context menu accessible by right-clicking in the tree navigator to create new sub folders and libraries, and reorganise your directory using the mouse to drag and drop folders and libraries.

Commands available in the tree navigator context menu​

Name	Description
Open in Shell	Opens the file location of the library in Windows Explorer.
Create Library	Creates a folder with and a new "index.xml" file.
Create Folder	Creates an empty folder on the disk.
Rename	Renames a Folder or Library.
Delete	Deletes a Folder or Library with all its contents. Use with caution !

---

Item Addition​

To access the commands to edit a library's content, right click anywhere in the item grid. Note that changes are only stored in the system memory until the library is saved to disk.

Commands available in the item context menu​

Name	Description
Use Item(s)	Adds the selected item to Forest's geometry list..
Properties	Shows the Item Settings dialog box.
Delete	Delete the selected item.
Create Item	Creates either a billboard or 3d object
Import Materials	Loads multiple billboads from a .mat material library Material Importer.
Import Objects	Loads multiple 3d objects from a .max scene file Object Importer.

---

Item Settings, Billboards​

This window is used to set the properties for a billboard item. The Forest plugin uses these settings to construct the plant object, most of them match properties in the plugin Geometry panel.

Settings available for items :

Name	Description
Scientific name	Latin plant name.
Common name	Common plant name.
Family	Botanical family of plant.
Description	Textual description about the plant.
Geometry	3D Geometry applied to the plant when is generated. Choose one of the general Forest geometry templates.
Material library	3DS Material library for material.
Material name	Name of the material to apply. Choose one of the materials in the selected material library.
Width	Width of the tree object in world units.
Height	Height of the tree object in world units.
Keep aspect ratio	Keep the width/height of the object synchronized with map aspect ratio.
Center Offset	Center of rotation for the object in % of width.
ZOffset	Elevation offset from the floor level.
Thumbnail	Preview image of object, represented with the same aspect ratio as real object.
Thumbnail Selector button	Press this button to change the thumbnail image.

---

Item Settings, 3D Objects​

This window is used to set the properties for a 3d object item. The Forest plugin uses these settings to construct the plant object, most of them match properties in the plugin Geometry panel.

Settings available for items​

Name	Description
Scientific name	Latin plant name.
Common name	Common plant name.
Family	Botanical family of plant.
Description	Textual description about the plant.
Max File	The location of the scene file contatining the item geometry
Object	The name of the object in the scene file.
Override material	When on the object uses a material from a separate material library.
Mat. Library	The location of the material library
Material	The name of the material to be used if override is on.
Thumbnail	Preview image of object, represented with the same aspect ratio as real object.
Thumbnail Selector button	Press this button to change the thumbnail image.

The settings are similar as for billboards, however instead loading a material we supply a 3dsmax scene with an object name. Optionally is possible to set a material override. The loading process can be done merging or XREF the object into our scene.

Material Importer​

If you have a 3DS material library with tree materials and textures, you can import them directly into a Forest Library as billboards using this window. Forest and Planes Materials are recognized in the process and their properties (such as plane size or offsets) are copied to the new items.

Name	Description
Mat. Library	Used to select a material library to import billboard materials from.
Create items in Forest Catalog	When activated adds the selected materials to the current library.
Create thumbnail images	When activated automatically generates thumbnail images and saves them to the thumbnails folder.
Create material library	When activated adds and consolidates the selected materials to a new material library.
Create as Forest Materials	Saves new billboards as Forest Materials.

Object Importer​

As for materials, you can import a whole directory of 3DS Max objects into a library automatically.

Name	Description
From Scene	Used to select a Max scene to import geometry.
Object list	Lists all the objects found in the selected scene.
All	Selects all objects.
None	Deselects all objects.
Invert	Inverts the current selection.

File Structure​

A library is a special folder on the disk which contains an index.xml file, where the items are listed. This file points to the files necesary to define a library item. The browser stops to scan directories when an index.xml file is found, so a library folder can't contain other libraries and all subfolders are hidden in the interface, this permits to you to organize the data in several subfolders.

Each library item points to a single template object in a .max file or to a material in a .mat file. Each time you select a library item, all settings in the template object are loaded and applied to the current Forest object. You can group several objects in a single file, or have separate files for each one. You can also use macro substituion (see section below) to use conditions or complex structures.

Each library item also has an associated image file, typically stored in the thumbnails' folder. This image is used to show the image preview in the library, and you should have one image for each library item. If you name the files using the same name of the object, the image is automatically selected in the editor.

Additionally, you can have materials libraries to override the object's default material. This way you can have several library items with the same geometric base, but with different materials and textures.

Macros​

In some fields, such as filenames and object or material names, you can use macro sustituions to add more flexibility to your library structures. These macros represent the library root location, current folder, or 3dsmax state values. The macros are instanced using the $(NAME) format.

To open the Insert Macro window, press the Macros... button in the properties window, select a macro and click OK, the selected macro will be inserted in the current field of the properties.