redcap

introduction

Redcap is a Ruby command and library for uploading images to Second Life. Note: each image upload costs L$10, just as it does with the Second Life client. Redcap supports uploads to the preview grid, if you'd like to save some cash while testing.

If you'd like to be notified of new versions, contact me. If you try redcap, I'd appreciate any comments you might have -- even if it's just "I'm using it." If possible, let me know what you're using redcap for. If you want to upload textures but would prefer another language or environment, check the resources section below for other options.

Redcap was inspired and informed by the work of Katherine Berry, creator of phpsimcaps. If you are interested in this kind of stuff, you should check out another of her projects, AjaxLife, an amazing Second Life client for your browser.

elsewhere in the Marker network: Interested in up-to-date syntax files for your LSL editor? Try Shill.

installation

Please check the details on the installation page.

usage

    redcap Sam Bacon sams_password chunky.jpg
    redcap --grid preview Sam Ideano sams_password esperanto.png

If the upload is successful, the program will return the UUID of new image, and the original image aspect ratio. The id and ratio can be used by the LSL function llSetTexture to apply the image to any prim. [note: a later release will include sample LSL code and web program for using the UUID and aspect ratio.]

troubleshooting

If any part of the process fails, errors from redcap and Second Life will appear on the console. If the source of the problem is not obvious, check the redcap.log file (in the current directory). It has a complete trace of program operation, including conversations with Second Life. The log does not include your password. If you can't figure out went wrong, please send me the log and as many details as you can.

redcap release 0.7.2 (24 July 2009)

• redcap can now be installed as a gem. Installation currently includes the redcap command and one support library, lib/uploader.rb
• redcap source is now available at github
• Added GPL license.
• Changed to gem-compatible release id (major.minor.patch).

redcap release 0.68

• The preview grid is now supported.  Save L$10 every time you test!  sample:  ruby upload.rb -grid preview Chunky Pig chunky-password bacon.jpg
• restructured as library. new calling program upload.rb returns aspect ratio and new UUID or ~error code.
• logging (see redcap.log)
• Added tests for all local routines. If you have questions about how things work, try reading test comments.
• If upload() succeeds it returns the UUID of the new image.  For instance: "47012234a-aaaa-abcbad". In uploa.rb, the original image aspect ratio is calculated.  You can use this measurement to adjust the size of a prim for proper display.
• If the upload fails, an error is raised, rescued, and upload() returns a value starting with "~", and including error trace.
• Use REXML instead of xmlsimple to interpret xml results.
• Use RMagick instead of command line ImageMagick calls.
• Refine nextpow2 to limit dimensions to 1024 (SL max).
• Use XMLRPC instead of Builder to construct and send the login request.

program flow

Redcap uses the sim-caps model added to Second Life in late 2006. A series of 4 HTTPS requests is all it takes to get the image into Second Life.

1. Login (via XML-RPC). The login response contains lots of useful stuff, including the URL to request capabilities, called the seed_capability.
   
   
2. Request upload capability. Send seed_capability a request for the NewFileAgentInventory capability.
   
   
3. Request upload ticket. Each upload transaction must be started by giving the upload capability basic information about the image. upload type=texture, name, description, destination folder.
   
   
4. Upload image. SL only accepts images formatted as JPEG-2000 Code Stream Syntax (JPC). SL also requires that the dimensions of the images be powers of two. ImageMagick/RMagick converts the images to this specification, then the binary image is posted to the URL in the upload ticket.
   
   
5. Use new texture UUID. If the upload succeeds, the new texture UUID is returned. This id can be used by any script, anywhere in SL, to apply the texture via llSetTexture. Note: the texture does not need to be in any object's inventory -- the only requirement is that you know the UUID. You probably also want to apply the original images's aspect ratio, since the uploaded image image dimensions have been resized to powers of 2 as SL requires.

note: This diagram is close to reality. Now that redcap is a gem, it can be called directly via the redcap command (instead of upload.rb/redcap#upload).

libraries used by redcap

library	use
pre-requisites
builder	create LLSD structures
RMagick	convert image to JPEG-2000, resize
standard libraries
digest/md5	encrypt the SL password
logger	simple logging to redcap.log
net/https	HTTPS POST requests to SL servers
rexml/document	interpret LLSD structures
tempfile	place to write the SL-formatted image
xmlrpc/client	login to SL
yaml	formatted output of hashes