Leveller for OpenSimulator (part 2)

Exporting from Leveller to Opensim

This tutorial looks at working with Leveller (a powerful 3D terrain editor for windows from Daylon Graphics) and OpenSimulator (Opensim). Part 1 explained how to import terrains from Opensim into Leveller. This part explains how to export heightfields in Leveller back into Opensim.

OpenSimulator Regions used

This part uses the four regions of test00, test01, test10, and test11 to demonstrate exporting terrains from Leveller back into the grid.

The listing for these regions likes a bit like...

...however the positions are only important  when importing the heightfields files using load-tile command.

Exporting single regions

To demonstrate exporting single regions we'll be using the following example from Leveller...

This 256x256 document was created by creating eight shapes, giving each a height (as shown on the map at right and then selecting all shapes followed by executing a Shapes > Heightfield from Selected Points command. Finally the water level was set using Edit > Water Level > Elevation to 20.

Exporting to In-World

You can export the above Leveller document as a RAW file for loading in-world. To do this, select File > Export and pick the Second Life option. After selecting a file to save to (it needs to be an existing RAW file, but you can easily copy the file and rename that copy) you might see something like this:

If the document has any heights less than zero you will get an error and the export will fail. It's best to play around with Original Elevations and Use per-pixel scaling. Once you've exported the file, you can go in-world and load it via your viewer.

You have to be the owner of the region in order to upload the raw file. Go to the Region / Estate dialog box and select the Terrain tab. You'll see something like this:

Select the Upload RAW terrain button, select the file and the terrain will be loaded. It should look something like this:

  

The submerged area above is roughly at 20m and matches the default water level. However on the original Leveller document that coastline contour is 20.6, and clears the waters. There's some trade off and inaccuracy using the .raw format. Compare this with exporting in .ter format (below). 
 

Server commands for saving terrains

The following two methods use server commands to save region's terrains. Server commands are made within the Opensim console. These examples are taken using ConEmu, a "Windows console emulator with tabs, which presents multiple consoles and simple GUI applications as one customizable GUI window with various features". ConEmu, rather than the Windows command line was used, as ConEmu behaves more like a Linux terminal, with the user being able scroll back through previous lines and reports, and use the up arrow to see (and then edit) previous commands. Users are also able to copy and paste from and to the console easier that with the standard  DOS prompt, and key shortcuts and colour schemes can be set for convenience.  All this makes using the Opensim console a lot easier for a Windows user. Other OSs may have their own equivalents. ConEmu was used as I predominantly use Windows and Windows apps (and hence Leveller).

For single regions

Leveller can export a heightfield to Opensim  simply by exporting using Terragen format (.ter). To do so, select File > Export and select the Terragen option. After selecting a file to save to, the dialog should look something like this:

To load the terrain for a single region you must first change to that region. You do this by using the "change region" command. For example, to go to the test00 region we'd type...

change region test00 [ENTER]

...and the console prompt should now show...

Region (test00) #

If it doesn't, you may have mistyped the name of the region. Making typos like that can create unexpected errors! Assuming you have now selected the region, You would use the "terrain load" command to save that to a particular file. For example...

terrain load N:\OpenSim\HeightFields\Leveller\Tutorial\in-world\test00.ter

...would load the terrain from the test00.ter file in that directory (you need to put quotes around a file path name if it has spaces in). The format of the file save is determined by the extension used as follows:

Extension	File Format
.r32/f32	32bit RAW, see RAW, 8 bit, 16 bit, and 32 bit explained
.ter	Terragen heightfield, see Terragen™ Terrain file specification
.raw	linden labs/Second Life RAW, see Tips for Creating Heightfields and Details on Terrain RAW Files
.jpg/jpeg	Joint Photographic Experts Group  image format.
.bmp	device independent BitMaP
.png	Portable Network Graphic
.gif	Graphics Interchange Format
.tif/tiff	Tagged Image File Format
.gsd	geographic survey data file

As you can see above, the example file was loaded in the Terragen format. The reasons for choosing that format are that it is a heightfield format rather that a graphics format, and that Leveller uses a modified Terragen format for its documents. If this is successful the console should look something like this:

  After loading the file in the region it'll look something like this in Opensim:

Here's a comparison between .raw and .ter exports, using the in-world map:

A good work practice is to use the Leveller document as a master file, and to make changes in that, rather than later re-import that region a second time to make modifications. Here's the above region re-imported back into Leveller using a raw file generated in-world...

...not pretty is it? Most of the bumpiness and abstraction is caused by using an image format to save heightfield data. If you own or rent a region but can't access the console for that grid, see if you can get the administrator to use terrain save (see part 1) and terrain load to for you (using .ter format), rather than using a .raw file.

For tilesets

In Opensim you can create regions that are square with dimensions in multiples of 256, for example 256x256, 512x512, 768x768, and so on. However at present you cannot have two regions of different sizes adjacent, without having issues  with one or more of those regions. So, in general you won't see a 256x256 region next to a 512x512 region, but you may see a string of 256x256 or larger regions together. A "tileset" is a collection of adjacent or connected regions of the same size. The following is a 512x512 example we'll be using in Leveller (which will be a 2x2 tileset of 256x256 regions):

You can just see the 256m grid lines on the map. This is also an example of  the MicroDEM colour scheme. Leveller allows you to change display colours for heights. It's also an example of me playing around with different tools!

Export a Leveller document as a PNG

Leveller can export the above as a PNG file. To do so, use the File > Export command and select the PNG option. After choosing a filename, and opening option, you should see something like this:

After OKing that, the following gets created in that directory:

The .wld and .xml  files are created by Leveller in the process of making the PNG. And the PNG looks something like this:

Load-tile command

The single PNG file created above for a tileset, can be loaded into Opensim using the terrain load-tile command in the console. This only works saving to a PNG file. The syntax is:

terrain load-tile <filename> <tile width <tile height> <xstart> <ystart>

...and where: <filename> is the file name of the of the saved file (e.g. 2x2tileset(default).png), and <tile width <tile height> is the width and height of the tileset, and <xstart> <ystart> are the grid's x and y location of the south west corner of the tileset (e.g. 1102 1000 for the sample island is the test00 region). However, you must also select each region in the tileset in sequence, and then repeat the command for that image, in order to load the section of that PNG that corresponds to the region selected.

For example, to load the PNG image above into test00, test01, test10 and test11, you would need to do the following commands:

Unlike the save-tile command (see part 1), you can load images that are not just in the /bin directory! The result of the above commands is...

Now this looks like the heightfield alright, but it seems to be a bit exaggerated, and what's happened with the water level? Comparing the Leveller map with the Opensim map, we can see this more clearly:

The water level hasn't changed in Opensim so it must be something to do with the format of the PNG (16bpp and the map elevations range). You can either go back to Leveller and fiddle around with the export settings (and check the document for silly errors like setting the water level at the wrong height, though in the above example it was set to 20.0008m in Leveller), or you can fiddle around with the height field either in-world, or via the console. If you want to go via the console method, select the region and try playing around with the following commands:

terrain elevate <num>

Raises the current heightmap by the specified amount.

terrain lower <num>

Lowers the current heightmap by the specified amount.

terrain multiply <num>

Multiplies the heightmap by the value specified.

terrain rescale <min> <max>

Rescales the current terrain to fit between the given min and max heights

terrain revert

Loads the revert map terrain into the regions heightmap.

In this instance I was able to fix the height issue buy using terrain lower 11 in each region. The result looks like...

But, the solution won't always be to do that command - it varies depending on the terrain. There is a third alternative, and that's to use the Export tileset feature of Leveller. 

Exporting tilesets from Leveller

Leveller now has an Export Tileset option which will automatically export a Leveller document as a set of Terragen formatted files suitable to be imported using terrain load within Opensim. To create this, use File > Export Tileset. The following dialog will appear:

There are several sets of options on this dialog. Output filename allows you to select both the directory to save the tile files in, and a "base name" to use how those files are named. The directory you use for a tileset export should either be empty, otherwise confusion might result.The base name (e.g. if you enter test.ter, the base name is test) is added to codes generated by Leveller to indicate where in the tileset the file goes. For example test_x0_y2.ter should be loaded into the region in the bottom row (numbering starts with 0) and 3 columns from the left. See below for an efficient way of doing this.

Tiling has two ways to decide split up the document into tiles - by px per tile, and by the number of tiles across and down the tileset. If you always use the same size regions (and they'll always be square in Opensim) then you might just just use that option (e.g. 256), but choosing the second might be easier if you're working with larger sized regions. The Elevation offset is added to the the heightfields of the exported files, and works the opposite way to the same option on Import Tileset. It defaults to 20 which matches the default water level in Opensim, but can be changed.

The water height may be an issue with the current example. Above I mentioned it was set to 20.0008m (some minor rounding errors). If we're using the Export Tileset method, that expects the water level to be at 0m in Leveller. Now we could either go back into Leveller and drop the heightfield by 20m, and then then set the water level to 0m. To drop the whole heightfield we'd either select all (or none) and then do Filter > Elevate and use the following settings:

Setting the water level is as simple as Edit > Water lever > Elevation and entering 0.0 m (works better than just plain 0). Now that might a good thing to do if you're working on several documents and most of them have the Water Level set to 0. However, if we just wanted to export that tileset now and doing that later, we could just enter 0 m for the Elevation offset instead! Assuming that we do, here's what the dialog might now look like:

After you OK that, the files in the Export sub-directory will look like this:

The next step is loading the files into Opensim using the terrain load command as detailed above. You simply change regions and then terrain load for each. The following is how this would look in the console for the example tileset...

...and here's the result in-world:

No adjusting needed!

Part 3 shows how to make terrain using shapes.