Custom Libraries
From OpenSimulator
(→Textures) |
(Massive rewriting) |
||
| Line 2: | Line 2: | ||
{{Quicklinks}} | {{Quicklinks}} | ||
<br /> | <br /> | ||
| − | |||
| − | |||
| − | |||
| − | The second | + | 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 the inventory items. 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= | ||
| − | = | + | ==With the Viewer== |
| − | + | The easiest way to generate assets is just to create them in-world, or upload them with the viewer. | |
| − | == | + | ==In Bulk== |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | However, if you want to create assets in bulk, for instance from a directory of image files, you can create images and add them into the default asset sets. These are found in the <tt>bin/assets</tt> directory. The file <tt>AssetSets.xml</tt> has a list of "asset sets", directories that contain the actual data for the assets and an XML file that has the metadata. Look at the XML file for the example; the format is not too complicated. | |
| − | + | 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 [http://www.openjpeg.org/ 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 [http://code.google.com/p/openjpeg/source/checkout 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 | ||
| + | |||
| + | <tt>image_to_j2k -i ''inputfile'' -o ''outputbase''.j2k -r 100,30,10</tt> | ||
| + | |||
| + | 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 [[jp2_batch_converter|Linux script]] or [[Jp2_batch_converter_for_windows|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 <tt>bin/assets</tt>. For example, let's suppose you're making a new asset set called <tt>MyAwesomeAssetSet</tt>. You'll need to create, in that directory, a file <tt>MyAwesomeAssetSet.xml</tt>. You can use the python script genassets.py to generate this file. It will also generate the inventory XML files needeed. This script is documented [[#Generating_Inventory_and_Asset_Files|below]]. | ||
| − | |||
==Terrains== | ==Terrains== | ||
| Line 34: | Line 50: | ||
* [[Using_L3DT|Creating custom terrains with L3DT]] | * [[Using_L3DT|Creating custom terrains with L3DT]] | ||
| + | =Generating Inventory Items= | ||
| + | |||
| + | The folders that show up in the library are defined in <tt>bin/inventory/Libraries.xml</tt>. That xml file has an entry for each library. What you probably want to do is create a new library. Make a subdirectory for that library. Generate the XML files describing the folders and items in that library. Add an entry to <tt>Libraries.xml</tt> giving the name of the two XML files for your library. | ||
| + | |||
| + | ==Generating Inventory and Asset Files== | ||
| + | |||
| + | The python script <tt>genassets.py</tt> is able to generate asset and inventory XML files at the same time. In order to use it, you must: | ||
| + | * Arrange all of your asset files (text files for scripts and notecards, properly sized j2k files for textures) in a directory tree that corresponds to the folders you want to see in your new library. | ||
| + | * Decide on the name of your library, and on a short version (without spaces) that will be used for filenames. | ||
| + | |||
| + | Run the script. It will go through the entire directory tree where you have put your asset files. It will copy all of those asset files to an asset directory, and generate the AssetSet XML file there. (Thus, you tell the script the asset directory is your new directory underneath <tt>bin/assets</tt>, which is where you want the files to end up eventually.) It will also generate two inventory XML files, one for folders and one for items, that put all of your new assets into the library. You can make the inventory directory (to which only those two XML files are written) your new directory underneath <tt>bin/inventory</tt>. | ||
| + | |||
| + | When the script is complete, you need only to edit <tt>inventory/Libraries.xml</tt> and <tt>assets/AssetSets.xml</tt> to tell it about your new library. Next time you start up OpenSim or (in grid mode) Robust, it should import your assets. | ||
| + | |||
| + | '''NOTE''': the generator script replaces the XML files it finds. This means that it's not really useful for adding files to an existing library but for creating the library from whole cloth. Each time you run it, it generates new UUIDs for all of the assets. That means if you run it on a set of assets you've already imported, they will get re-imported into the asset store; the old ones ''will not'' be deleted. (They may also be used in-world already!) To avoid redundancy and cruft, you don't want to re-import things. If you want to add things to a library, just generate XML files as if they were all new. Then, merge the XML files by hand in a text editor. | ||
| + | ==Generating Inventory Files for Existing Assets== | ||
| − | + | If you have assets that you've already uploaded, and you just want to have them appear in the library folders, then... there is more to be written. | |
| − | == | + | ==Caution== |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | (I don't know if this is true, but I seem to remember reading somewhere that in grid mode, library assets have to 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.) | |
| − | + | ||
| − | + | ||
| − | + | ||
Revision as of 21:17, 14 July 2011
 |
Languages: |
|
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 the inventory items. 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
With the Viewer
The easiest way to generate assets is just to create them in-world, or upload them with the viewer.
In Bulk
However, if you want to create assets in bulk, for instance from a directory of image files, you can create images and add them into the default asset sets. These are found in the bin/assets directory. The file AssetSets.xml has a list of "asset sets", directories that contain the actual data for the assets and an XML file that has the metadata. Look at the XML file for the example; the format is not too complicated.
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 genassets.py to generate this file. It will also generate the inventory XML files needeed. This script is documented below.
Terrains
Create a terrain heightmap
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. What you probably want to do is create a new library. Make a subdirectory for that library. Generate the 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.
Generating Inventory and Asset Files
The python script genassets.py is able to generate asset and inventory XML files at the same time. In order to use it, you must:
- Arrange all of your asset files (text files for scripts and notecards, properly sized j2k files for textures) in a directory tree that corresponds to the folders you want to see in your new library.
- Decide on the name of your library, and on a short version (without spaces) that will be used for filenames.
Run the script. It will go through the entire directory tree where you have put your asset files. It will copy all of those asset files to an asset directory, and generate the AssetSet XML file there. (Thus, you tell the script the asset directory is your new directory underneath bin/assets, which is where you want the files to end up eventually.) It will also generate two inventory XML files, one for folders and one for items, that put all of your new assets into the library. You can make the inventory directory (to which only those two XML files are written) your new directory underneath bin/inventory.
When the script is complete, you need only to edit inventory/Libraries.xml and assets/AssetSets.xml to tell it about your new library. Next time you start up OpenSim or (in grid mode) Robust, it should import your assets.
NOTE: the generator script replaces the XML files it finds. This means that it's not really useful for adding files to an existing library but for creating the library from whole cloth. Each time you run it, it generates new UUIDs for all of the assets. That means if you run it on a set of assets you've already imported, they will get re-imported into the asset store; the old ones will not be deleted. (They may also be used in-world already!) To avoid redundancy and cruft, you don't want to re-import things. If you want to add things to a library, just generate XML files as if they were all new. Then, merge the XML files by hand in a text editor.
Generating Inventory Files for Existing Assets
If you have assets that you've already uploaded, and you just want to have them appear in the library folders, then... there is more to be written.
Caution
(I don't know if this is true, but I seem to remember reading somewhere that in grid mode, library assets have to 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.)
