Revision as of 19:06, 15 July 2011

 

Home

 

Download

 

News

 

Support

 

Admin

 

Dev

 

Screen Shots

 

Grid List

 

Bugs

Languages:

English

Library Overview

The library in OpenSim is described in the file bin/inventory/Libraries.xml. That file defines a number of other libraries, each of which have a file for folders and a file for items. The files described in Libraries.xml are read each time the server starts. (Note, however, that the viewer caches library information, so you may need to clear your cache viewer side to see changes you've made.)

If you want to add assets to the Library on your OpenSim server, there are two fundamental steps. The first is generating the assets, the second is generating these inventory XML files. The assets have information about the objects themselves; the geometry of prims, the image of textures, the text of notecards, etc. The inventory items are entries in the folders that allow users to actually access the assets.

If you want ready-to-import libraries, you could check out the Free Assets section...

Generating Assets

The server also is able to bulk import asset sets. These asset sets are described in the file bin/assets/AssetSets.xml. Each asset set has its own XML file describing the assets, coupled with another file that has the actual asset data (image or text data). You can define new asset sets and add the XML file describing them to AssetSets.xml. When Robust (in grid mode) or OpenSim (in standalone mode) starts up, it looks at the AssetSets.xml file. It figures out which of the assets in the asset sets don't exist in its asset store, and adds them.

Generating Assets With the Viewer

The easiest way to generate assets is just to create them in-world, or upload them with the viewer. If you do this, there is no need to muck about with asset sets.

In Bulk

However, if you want to create assets in bulk, then you need to define your own asset set. Look at some of the asset sets defined in AssetSets.xml, to get a sense for what the an asset set XML file looks like.

Practically speaking, at the moment, you can only import lsl scripts, notecards, and textures this way. There are two steps. First, you must get the assets into the right format. Second, you must generate the XML files for the assets.

Getting Assets into the Right Formats

Notecards and lsl files are plain text files.

Images have a size that is a power of two on each side. That is, both the width and height must be one of 16, 32, 64, 128, 256, 512, or 1024. They must also be in be in JPEG2000 .j2k format. You can use the OpenJPEG utilities to convert from other formats to JPEG2000. Note that version 1.3 of the OpenJPEG libraries does not support greyscale images or transparency. It will fail to work on greyscale images, and will remove any alpha channel from transparent images. As of revision 824 in the OpenJPEG svn archives, it also supports transparency, and may read PNG files directly, and (at least with PNG files) handles greyscale images. It's worth compiling a more recent version from the svn archives, at least until a version of OpenJPEG is officially released that supports these features.

Convert a single image file to OpenJPEG with

 image_to_j2k -i inputfile -o outputbase.j2k -r 100,30,10

A note on compression: the values after "-r" are the compression ratios to store in the OpenJPEG file. If you upload an image with the viewer (at least with Imprudence), the list of compression ratios used is 1920,480,120,30,10. Bigger numbers mean more compression, and hence blurrier images. The advantage of storing multiple levels of compression is that when the (small amount) of data for a high level of compression is downloaded, at least that much can be rendered. This is why when you watch a texture load, it starts blurry, and (at least if you're lucky) eventually becomes sharp. A compression level of 1 is lossless... and also uses a lot of space in the asset store, and a lot of bandwidth when it's sent down. A smallest compression of 10 should be good for most purposes. However, for things like sculpt maps (or small, precise textures), you may want to add a compression ratio of 1 to the end of the arguments.

Two scripts exist, a Linux script or Windows script in perl. They use ImageMagick and image_to_j2k to resize image files to the appropriate size and convert them to j2k files (although named with an extension of .jp2, since that's what the viewer expects for some perverse reason). However, if you want to use this, be aware of some caveats:

• The script deletes your original image file.
• The script does no error checking. This means that if for whatever reason (and there can be several!) image_to_j2k file fails, the script will delete your image file anyway. This could make you sad if, like a certain stupid wiki page editor, you didn't make backup copies first.
• The script makes j2k files with compression ratios 20,10,1. While this is great for image files that are bundled with the viewer, it's not good for server-side image files. That lossless compression means gratuitous use of server asset store space and bandwidth.

Maybe one day there will be an updated script....

Creating Asset Set XML Files

Once you have all your assets in the right format, you need to create the AssetSet XML file. Ultimately, you're going to want to make a new subdirectory underneath bin/assets. For example, let's suppose you're making a new asset set called MyAwesomeAssetSet. You'll need to create, in that directory, a file MyAwesomeAssetSet.xml. You can use the python script updatelibrary.py to generate this file. It will also generate the inventory XML files needed. This script is documented below.

Terrains

Create a terrain heightmap

• Creating custom terrains with L3DT

Generating Inventory Items

The folders that show up in the library are defined in bin/inventory/Libraries.xml. That xml file has an entry for each library; each library is defined by two XML files. One describes the folders in the library, (i.e. subfolders underneath a top folder that shows up underneath OpenSim Library), and the other describes the items in those folders. What you probably want to do is create a new library. Make a subdirectory for that library. Generate the two XML files describing the folders and items in that library. Add an entry to Libraries.xml giving the name of the two XML files for your library. You're done! Except that it's very painful, because it will involve copying and generating a lot of UUIDs. As such, except for the most trivial of libraries, you don't want to do this by hand.

Generating Inventory and Asset Files

The python script updatelibrary.py is able to generate asset and inventory XML files at the same time. Basically, you maintain a tree of assets in an asset set directory, and run this script to sync the XML files with your tree. (Note that at the moment it can only add assets; it will not delete them if you remove them frmo yoru tree.) It is able to add both assets in your asset set, and pre-existing assets already in your grid's asset store (for which you don't have to add something to an asset set.)

In order to use it, you must:

• Create an asset set directory
• Arrange all of your asset files (text files for scripts and notecards, properly sized j2k files for textures) in directories underneath that asset set directory that will correspond to the folders and subfolders underneath your top-level library directory.
• Decide on the name of your library, and on a short version (without spaces) that will be used for filenames.

For example, if you're making a library that will show up as a folder under the OpenSim Library folder as "My Awesome Library", you could build it inside the MyAwesomeAssetSet directory. Underneath that directory, make subdirectories named Textures, Clothing, Objects, and so forth. In the Textures directory, put your properlly formatted j2k files. Right now, the script only handles textures (.j2k), notecards (.txt), and scripts (.lsl).

In addition, in each directory you can put a file named "addassets.lis". You can list assets that are already in your grid's asset store here to be added to the library at the folder corresponding to the directory of each adassets.lis file. Any type of asset may be added to the library this way. This file is a series of lines, each of which follows the format

 asset_uuid  asset_type  inventory_type  name of object in inventory

A viewer such as Imprudence is able to tell you the asset_uuid of anything in your inventory; you can just copy this to the addassets.lis file. asset_type is a number, depending on the type of asset:

inventory_type is another number, again depending on the type of inventory. (Inventory type and asset type are not the same thing, although they're often closely related. Inventory type is what tells the viewer which sort of icon to show next to the inventory item's name.)

(There is also the "None" inventory type, which has number -1.)

Run the script. It will go through the entire directory tree where you have put your asset files. It will read the Asset Set, Inventory Folder, and Inventory Item XML files that already exist. It will then add entries as necessary to those files for any new .j2k, .txt, or .lsl files in your directory tree, as well as for any new entries in any addassets.lis file.

When the script is complete, you need only to edit inventory/Libraries.xml and assets/AssetSets.xml to tell it about your new asset set and your new library. Next time you start up OpenSim or (in grid mode) Robust, it should import your assets and add your entries to the library. Again, remember that the viewer caches the library list, so you may need to clear your cache on the viewer in order to get the current version of the library.

Caution

(I don't know if this is true, but I seem to remember reading somewhere that in grid mode, library inventory xml files must exist not only on the Robust server, but also on each and every individual region OpenSim server. I do not know if this is the case. If it is, it certainly complicates matters.)

Additionally, all of this may be obsolete in the future. Rather than using this code, it's possible that OpenSim will use IAR files to define the library (or, perhaps, default items for avatars). For the time being, though, try this.

Contact Rob Knop (rknop on freenode, usually hanging out in opensim-dev; Prospero Frobozz on many grids) with any questions about updatelibrary.py.