Leveller for OpenSimulator (part 1)

Importing from Opensim to Leveller

Leveller is a powerful 3D terrain editor for windows from Daylon Graphics. With Leveller the user can "paint" terrain, use vectors to create contours (which can then create heightfields) and use a variety of filters and tools to create distinctive and realistic terrain features (see the website for a more complete list of features). Users can also import and export heightfields in a variety of formats, and the latest update includes methods to easily import from and export to terrains with OpenSimulator (Opensim for short). This tutorial gives a run though on how to do that and why.

Why use an external terrain editor?

While it is possible to create and edit terrain within Opensim, this is a mixture of in-world techniques inherited from Second Life, and brute force console commands. It is possible to get exactly what you want, but using an external terrain editor to create or edit terrain has the following advantages:

• Editing a set of adjacent regions becomes a lot easier, as the editor can be used to edit the terrain for all the regions;

• Real world terrain can often by imported into the editor and then exported into a grid;

• It provides the user with greater precision in editing the terrain, and terrain can easily be copied and/or divided into different documents;

• Dedicated terrain editors have tools which better emulate real terrain, and/or are easier to use;

• Terrain editors may have several levels of "undo", and backing up terrain sets; and

• Once you have a separate heightfield document, you can usually export it to a different editor if you want, and also use it in other applications (such as Unity).

Using a dedicated terrain editor encourages a certain type of work flow.  The editor's version of the heightfield becomes the main or "master" version. Edits (and backups) then get made in the editor and exported to Opensim. Minor changes might be made in Opensim, but once the heightfield is in an editor's document format, that is the version that gets edited for major changes. The limiting factor is how you can get terrain into and out of Opensim. Any terrain editor you're using needs to be able to read and write in a format that Opensim can understand. In the following examples we'll be using a sample grid, as shown below:

A four region island.

As you can see the terrain's already been edited and the larger island is composed of regions eeny, meeny, miny, and moe. These will be used to demonstrate saving terrain to be imported to Leveller. The four other regions of test00, test01, test10, and test11 will be used to demonstrate exporting terrains from Leveller back into the grid. The listing for these regions likes a bit like...

The positions only become relevant when importing and exporting tilesets of multiple regions. We'll tackle importing to Leveller in this part, as the tutorial assumes you already have one or more regions in  one or more grids (even if that is only a stand-alone grid). 

Importing via a viewer

You can save a region's terrain as an RAW file from in-world via the viewer if your avatar owns the region. You need to find the Region/Estate menu option within the viewer. The location of this can be different depending on which viewer you're using (the example below is using Singularity) and sometimes the ALT-R shortcut is assigned to it. Find the option and select it. When the Region/Estate dialog appears, move to  the Terrain tab, as per below:

Selecting Download RAW Terrain will save the current definition as a RAW so the image is used to store heightfield data file. A RAW file is an image file. It can be edited in Photoshop and other graphics editors but it can also be read by Leveller. After you've saved the file you'll have something like this:
 

In this example we are only saving the terrain from the eeny region. To import this file into Leveller, go to that application and select from the File menu the Import option and from the list of formats select Second Life. You then use the browser to select the .raw file to read and will see something like this:

The choices are Elevations, Water elevations, and Original elevations. The Water channel comes from raw channel 3, whereas the others come from raw channels 1+2, and 12+13, respectively. A local coordinate system is set with the origin in the south west corner, to match the ground coordinates that Second Life uses. After loading the raw file you should then see something like this in Leveller:

This import can now be edited in Leveller. There may be some inaccuracy in using .raw files.  

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

To save 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 eeny region we'd type...

change region eeny [ENTER]

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

Region (eeny) #

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 save" command to save that to a particular file. For example...

terrain save N:\OpenSim\HeightFields\Leveller\Tutorial\single\eeny.ter

...would save the terrain to the eeny.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 saved in the Terragen format. The reasons for choosing that format are that it is a heightfield format rather that a graphics format. Leveller also uses the .ter extension for its documents but these are not in Terragen format. Leveller can however easily import and export in Terragen format. To import this file into Leveller, from the File menu select Import and change the format to Terragen Terrain. After selecting a file you will something like this:

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

Notice how using Terragen instead of Raw gives a smoother result.

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, with each region being one tile. The following three examples are taken from 3rd Rock Grid:

The above is a 2x2 tileset, surrounded by non-region water areas.

The above is a 3x1 tileset, surrounded by non-region water areas.

The above is a 2x3 tileset, surrounded by non-region water areas, but one that also includes gaps where there are no regions. The large island in the example used for this tutorial is a 2x2 tileset. 

Save-tile command

It is possible to save a single file for a tileset using the terrain save-tile command in the console. This only works saving to a PNG file. The syntax is:

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

...and where: <filename> is the file name of the of the saved file (e.g. EnnyIsland-all.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. 1100 1000 for the sample island with is the eeny region). The command is a little buggy in that it may fail if you add a path to the file name of the saved file (under Windows it gets saved in the \bin sub-directory) and a single command doesn't save all the regions terrain, but rather the terrain of the region you have currently selected.

For example if your current region is moe and you do the following command...

terrain save-tile EnnyIsland-all.png 2 2 1100 1000

...you would get the following result:

As you can see only the top left region (moe) has been saved to the file, the other regions are transparent. If you had eeny selected instead, you would get...

To save all the region's terrain, you need to change regions one at a time and repeat  the same command:

...will produce this result:

You can import this file to Leveller by doing an import as per above, but using the PNG option instead of .ter. The result will look something like this:

Note how the terrain looks very terraced. This is a result of using a graphics format instead of a heightfield format.

Saving tilesets for Leveller

Leveller now has an Import Tileset option which will automatically import saved terrain files from a tileset and place them correctly - provided you name the terrain files correctly first. To do this, you follow through the procedure outlined under For single regions for each region in the tileset. Each file must be in Terragen format (.ter) and its name must use the syntax base_xN1_yN2, where base is any text you want as long as it is the same for each tile, N1 is the horizontal tile index starting at zero and growing eastward, and N2 is the vertical tile index starting at zero and growing northward.

For example, in saving the sample island, the following commands were used...

Notice how the regions were changed between terrain saves, and how the file names were adjusted slightly to reflect the position of that region in the tileset. This results in the following files in Import directory:

 We now swap to Leveller and select File > Import Tileset. After selected that directory we would see something like this:

The elevation offset (set to -20 by default) will adjust the heightfield after import. Opensim's default water level is 20, but Leveller's (and other programs like L3DT) default water level is zero. This allows the user to automatically adjust when importing from Opensim, and there is an export equivalent that adds height back on. We won't change this value. After import you should see:

This is much smoother the heightfield is when compared with the PNG import. We might want to adjust  those grid lines on the map. Going to Navigation > Gridlines we'll see something like this:

Delete all spacings except for 1, and add 256 before OKing. Now the map will look like this, showing the different region's borders:

You can have gaps in the tileset, like the 2x3 tileset from 3rd Rock Grid. In this case Leveller just replaces empty positions with blocks of 0m heightfields. 

In part 2 we'll show how to export 
heightfields back to Opensim