Zonja Capalini

ZOE version 0.1 released

Zoe

Zoe (Zonja’s OAR Editor) is a simple offline OAR manipulation tool that I wrote recently. You can find a detailed description of its functionality in my recent post “Moving and rotating OARs”. In this post I’ll describe how to install and use Zoe. I’ve designed Zoe with simplicity in mind, so that currently it only implements some very basic operations — by combining these operations, however, a number of pretty cool things can already be done. I’d love to get some feedback about the functionality of Zoe — at the end of the post I’ll list some of the things that I want to add to it, but I’m open to suggestions.

ZOE version 0.1 released

Installing Zoe

Prerequisites

Zoe is distributed as a single file called ‘zoe.rex’ that contains the (BSD) license, a short manual and the program itself. To run it, you’ll need to install Open Object Rexx (oorexx) first. You can download oorexx from here. The installation is a breeze and should not take more than some few minutes.

Zoe can run in two modes: directory mode and file mode. In directory mode, Zoe edits the directory where an OAR file has been extracted; in file mode, Zoe takes care first to extract the OAR file to a directory, then edits that directory. To be able to extract the files contained in an OAR, Zoe needs an external tool. This release of Zoe includes support for file mode in Windows only (it should be trivial to add support for file mode on Linux machines, but I don’t have access to any Linux machine right now — I’d love to cooperate with somebody who does, and add this support in the next release). To use Zoe in file mode under Windows, you’ll have to download 7-Zip and install it. Again, installation is a breeze. Please make sure that the 7-Zip directory has got to the Windows path — you can check that by opening a command prompt and typing “7z” after 7-Zip has been installed. If you get an “unrecognized command” response, you’ll have to add “C:\Program Files\7-Zip” (or the localized version, etc) to your path manually.

Testing for correct operation

Once you have installed oorexx (and eventually 7-Zip), put ‘zoe.rex’ in a directory of your choice, open a command prompt, and type ‘zoe ?’. This should display a short help information (some users have reported that they need to type ‘rexx zoe ?’ instead — please try this if ‘zoe ?’ didn’t work for you).

    C:\CL>zoe ?
    [ZOE] Zonja's Oar Editor, v0.1

    ZOE is a tool to edit Opensim ARchive (OAR) files.

    Usage:
      zoe ?
             Prints this information
      zoe ??
             Prints a short manual
      zoe (c)
             Prints the license information for ZOE
      zoe [<directory>]
             Edits an OAR file previously unpacked in <directory>
      zoe
             Edits an OAR file previously unpacked in the current directory
      zoe <filename>[.oar]
             Unpacks the OAR file '<filename>[.oar]' in the file's directory,
             then edits the OAR file
             (Windows only, requires 7-Zip -- please read the manual)
    C:\CL>

Using Zoe

To use Zoe, you’ll need an OAR file. If you don’t know how to get an OAR file, you probably shouldn’t be using Zoe. If you absolutely must, you can find some OARs in the Opensim wiki, or in rexxed.com, for example.

Using Zoe in directory mode

OARs are gzipped tarballs. If you are going to use Zoe in directory mode, you’ll need to unzip the tarball yourself, then extract it. Under Linux there are native commands to do this; under Windows, you can use 7-Zip (see above under ‘Prerequisites’). In the following, we will talk about “the OAR directory” to refer to the directory where the tarball has been extracted to, i.e., the directory containing the contents of the tarball: the file ‘archive.xml’, and the ‘assets’, ‘landdata’, ‘objects’, ‘settings’ and ‘terrains’ directories. (The current version of Zoe operates on the ‘objects’ directory only.)

Assuming that zoe.rex is in your path, to start editing an OAR directory you can open a command prompt and either 1) cd to the OAR directory and type

    zoe

(or ‘rexx zoe’ if for some reason ‘zoe’ does not work — you can also type ‘zoe .’ [or ‘rexx zoe .’] to get the same effect), or 2) type

    zoe directory

substituting ‘directory’ by the OAR directory. You should get something similar to the following:

    C:\CL>zoe
    [ZOE] Zonja's Oar Editor, v0.1

    [ZOE] Loading objects...
            50 objects processed...
           100 objects processed...
           150 objects processed...
           200 objects processed...
           250 objects processed...
           300 objects processed...
           350 objects processed...
           400 objects processed...
           450 objects processed...
           500 objects processed...
           550 objects processed...
           600 objects processed...
           650 objects processed...
           700 objects processed...
           750 objects processed...
           800 objects processed...
           850 objects processed...
           900 objects processed...
           950 objects processed...
          1000 objects processed...
          1050 objects processed...
    [ZOE] 1066 objects found.

    [ZOE]:

Zoe has processed all the objects in the OAR directory and is now ready to begin editing the OAR.

Using Zoe in file mode (Windows only)

If your installation meets the conditions described above under “Prerequisites”, you can also run Zoe in file mode. To run Zoe in file mode, you have to type

    zoe filename

(or ‘rexx zoe filename’) and substitute ‘filename’ for the name of your OAR file. You don’t need to specify the .oar file extension, that is, ‘zoe file’ and ‘zoe file.oar’ are equivalent (if you have an OAR without an extension, use ‘zoe file.’). In this case, Zoe will automatically unzip and extract the tarball in the same directory where the OAR is located, and enter directory mode against the extracted directory:

    C:\CL>zoe cl
    [ZOE] Zonja's Oar Editor, v0.1

    [ZOE] Unzipping 'C:\CL\cl.oar' to extract tarball 'CL'...  Done! (3.34 s)
    [ZOE] Unpacking tarball 'CL'...  Done! (8.84 s)
    [ZOE] Loading objects...
            50 objects processed...
           100 objects processed...
           150 objects processed...
           200 objects processed...
           250 objects processed...
           300 objects processed...
           350 objects processed...
           400 objects processed...
           450 objects processed...
           500 objects processed...
           550 objects processed...
           600 objects processed...
           650 objects processed...
           700 objects processed...
           750 objects processed...
           800 objects processed...
           850 objects processed...
           900 objects processed...
           950 objects processed...
          1000 objects processed...
          1050 objects processed...
    [ZOE] 1066 objects found.

    [ZOE]:

You can then proceed to edit your OAR.

Zoe commands

Once Zoe has started, you can begin editing your OAR by typing commands at the Zoe command prompt ‘[ZOE]: ‘. Here’s an alphabetical list of the commands you can use (all commands are case-insensitive):

The ? (or HELP) command

The ‘?’ (or ‘help’)  command displays a short list of the available commands:

    [ZOE]: help

    List of available commands:

      ?                            -- Displays this information
      ADD <number> TO [X | Y | Z]  -- Moves all objects
      CLS                          -- Clears the screen
      CLEANUP                      -- Deletes extracted files
      DELETE where [X | Y | Z] ['<' | '>'] <number>
                                   -- Deletes some objects
      HELP                         -- Displays this information
      PACK <filename>              -- Packs the OAR into a file called <filename>
      QUIT                         -- Exits the program
      ROTATE 90 [DEGREES]          -- Rotates all objects 90 degrees relative
                                      to the center of the region

    All commands are case-insensitive

    [ZOE]:

The ADD command

The ‘add’ commands adds a positive or negative quantity to the position of all linksets in the OAR. For example, “add 1000 to z” would heighten all linksets by 1000 meters, and “add -500 to z” would lower them by 500 meters, and so on: “add 100 to x” will displace all linksets by 100 meters to the east, etc. The general format of the ‘add’ command is:

    ADD <number> TO [X | Y | Z]

where number may be specified as an integer or a real. Please note that no verification is done to check that the resulting linksets fit into the region, and therefore the resulting OAR file may become invalid. For example, if you type “add -1000 to y” all the linksets will go out-of-world. On the other hand, adding multiples of 256 to an existing OAR may be useful when working with megaregions (consult “Moving and rotating OARs” for details).

    [ZOE]: add 1000 to z
    [ZOE] 1066 objects moved in 6.03 seconds.

    [ZOE]:

The above example took a long time (> 6 seconds) because we are moving a large linkset (2889 prims), which is by force expensive.

The CLS command

The ‘cls’ command just clears the screen.

The CLEANUP command

The ‘cleanup’ command prompts the user for confirmation and then deletes all the files created by an OAR extraction and exits Zoe.

    [ZOE]: cleanup
    [ZOE] This will delete permanently the following files:
      archive.xml
      assets\*
      landdata\*
      objects\*
      settings\*
      terrains\*
    [ZOE] Are you sure? (Yes/No):y
    [ZOE] and then exit ZOE. Are you sure? (Yes/No):y
    [ZOE] 1501 files and 5 directories deleted.

    C:\CL>

Please note that you can exit Zoe without cleaning the extracted OAR by using the ‘quit’ command described below, and resume later your edition by simply restarting Zoe in directory mode.

The DELETE command

The ‘delete’ command deletes all linksets that satisfy some conditions. For example, ‘delete where z > 500’ would delete all airboxes (i.e., those located at > 500 meters), ‘delete where x < 128’ would delete all objects in the west half of the sim, etc. The general format of the ‘delete’ command is:

    DELETE where [X | Y | Z] ['<' | '>'] <number>

Linksets are deleted from memory and from the filesystem.

    [ZOE]: delete where x < 129
    [ZOE] 521 object(s) deleted in 0.24 seconds.

    [ZOE]:

The PACK command (Windows only)

The ‘pack’ command creates a tarball with all the files present in the OAR directory and then gzips that tarball, thus creating a new (compressed) OAR file. The format of the ‘pack’ command is the following:

    PACK filename

where ‘filename’ has to be substituted by the name of your OAR file. Please note that the ‘.oar’ suffix is not added automatically.

    [ZOE]: pack new.oar
    [ZOE] Building tarball... Done! (1.97 s.)
    [ZOE] Gzipping tarball... Done! (4.78 s.)
    [ZOE] OAR file 'new.oar' successfully created.

    [ZOE]:

You can use the ‘pack’ command as many times as you like, perhaps to save different OARs in different states of editing.

The QUIT command

The ‘quit’ command exits Zoe. Please note that the OAR directory is not cleaned up automatically by Zoe, so that you can resume editing later by calling Zoe again in directory mode. If you want to perform a cleanup of the OAR directory, use the ‘cleanup’ command instead.

The ROTATE command

The ‘rotate’ command rotates all linksets in the region by 90 degrees clockwise around the center of the region. The format of the ‘rotate’ command is

    rotate 90 [degrees]

Please note that you can use the rotate command repeatedly to get rotations of 180 and 270 degrees.

    [ZOE]: rotate 90 degrees
    [ZOE] 545 objects rotated in 0.42 seconds.

    [ZOE]:

Special calls

Zoe can be called in three special ways: ‘zoe ?’ displays a short help information:

    C:\CL>zoe ?
    [ZOE] Zonja's Oar Editor, v0.1

    ZOE is a tool to edit Opensim ARchive (OAR) files.

    Usage:
      zoe ?
             Prints this information
      zoe ??
             Prints a short manual
      zoe (c)
             Prints the license information for ZOE
      zoe [<directory>]
             Edits an OAR file previously unpacked in <directory>
      zoe
             Edits an OAR file previously unpacked in the current directory
      zoe <filename>[.oar]
             Unpacks the OAR file '<filename>[.oar]' in the file's directory,
             then edits the OAR file
             (Windows only, requires 7-Zip -- please read the manual)

    C:\CL>

‘zoe ??’ displays a short manual, and ‘zoe (c)’ displays the license information.

Download

You can download Zoe here. PLEASE take into account that Zoe is an experimental program — run at your own risk.

Further work

Things I should do

  • (Immediate) Improve the ‘delete’ command so that it accepts a limited form of  and-or expression, and numeric ranges, for example ‘delete where x between 100 and 120 and y between 60 and 100’.
  • (Immediate) Improve the ‘rotate’ command so that it can accept arbitrary rotations.
  • (Immediate) Ensure that ‘cleanup’ deletes recursively subdirectories when objects contain the “/” character (currently it doesn’t).
  • (Important) Make exit codes consistent and document them.
  • (Important) Add some kind of support for selection by owner and/or parcel.
  • (Important) Add some form of selection by object name.

Things I would like others to do

  • Cooperate with me to implement ‘file’ mode for Linux (this should be trivial, email me if you’re interested).
  • Test the program thoroughly and report here or by emailing me.
  • Suggest new features — I can’t guarantee that I’ll implement them, but feedback would be much appreciated.

December 16, 2009 - Posted by | OpenSim, Tech News, ZOE | , ,

14 Comments »

  1. […] Moving and rotating OARs [UPDATED] [Update 20091216: ZOE v 0.1 has been released. You'll find a manual and the download link here.] […]

    Pingback by Moving and rotating OARs [UPDATED] « Zonja Capalini | December 16, 2009

  2. […] fitting perfectly! Now it should be pretty easy to implement deletion of objects by parcel in Zoe: since for each object we already have its X and Y coordinates, to evaluate whether the (root prim […]

    Pingback by Reverse-engineering OARs: Understanding parcel maps « Zonja Capalini | December 18, 2009

  3. […] In this article I present the results of several simple tests I have made by extending my “Zoe” OAR editor so that it supports (a very simplified sub-dialect of) SQL. Even in a simplified form, […]

    Pingback by Using SQL to manipulate OARs « Zonja Capalini | January 1, 2010

  4. […] an automated tool to assist in the cloning, and I developed the (admittedly hacky) tool I called Zoe — you can find a detailed description of the technical details in my post “Moving and […]

    Pingback by Mirror Worlds: a hypergridded eternal art exhib « Zonja Capalini | January 17, 2010

  5. […] information by manually looking at the XML2 files when developing the simple OAR editor I called ZOE and in recent modifications to that editor. I’ve also taken a look at the source code for […]

    Pingback by Partial documentation for XML2 « Zonja Capalini | January 25, 2010

  6. […] I’ve implemented the tool as a new command called “SPLIT” in version 0.2 of my ZOE OAR editor. You open a megaregion OAR file with ZOE, type “SPLIT”, and that’s it — in […]

    Pingback by Splitting Megaregions « Zonja Capalini | February 13, 2010

  7. Great work Zonja! The “Zoe” tool looks wonderful, and it’s a great concept to have a tool for editing OAR’s.

    Comment by Mark Malewski | February 16, 2010

  8. Thank you! :-) It’s more of a proof-of-concept than a finished application, since I’m using a not very efficient interpreted language — but it works as advertised, and it’s allowing me to explore the world of offline xAR editing, in which I see a lot of future…

    Comment by Zonja Capalini | February 16, 2010

  9. Just came across this toll, will have to give it a try out, my 25 region mega on osgrid is getting too large and is failing when I try to restore the oar for it, maybe splitting it up using your tool and then loading the smaller ones will work (we migrating to 0.7 in the next couple of days thats why I doing it)
    Anyway I going to give it a try, thank you very much for your work :)
    Simpy (Castle-Haven-Mega)

    Comment by John Haines | October 16, 2010

  10. Wow, a 25 sims megaregion! :-) Hope it works for you, if you have any difficulty please feel free to contact me by email.

    Comment by Zonja Capalini | October 17, 2010

  11. Hi Zonja,
    I want to rotate an OAR and red you made it possible with the program ZOE.
    Only the link you give doesn’t work anymore.
    Can you tell me how to get the program?
    Thank you!

    Comment by Fred | November 4, 2012

  12. Hi Zonja,
    I am also looking for your ZOE.REX application. As I have one oar file to rotate and one to lower. Please re-post your app somewhere where your grateful followers can find it! Or let us know where to find a comparable app if yours is no longer available. :( Which in my opinion would be a shame since this is a needed app to align regions when bringing them together on new grids.
    Thanks ever so much! :)

    Comment by Chuck | February 13, 2013

  13. Hi Zonja
    I would love to get your tool as well. As your provided link is not working anymore could you please make this very useful programm available again. Thanks for sharing, highly appreciated, Yanna

    Comment by Yanna | April 6, 2013


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: