slothbear-redcap 0.7.1

data/README.rdoc

@@ -0,0 +1,70 @@
+= redcap
+
+redcap is a library for uploading images
+to Second Life.  It costs L$10 per image uploaded.
+You can save some money during testing by using the
+Preview Grid (if available).
+
+== installation
+
+To install redcap as a gem:
+   gem install slothbear-redcap --source http://gems.github.com
+
+If you'd rather grab a couple files and give it a try, download
+the following files from http://github.com/slothbear/redcap/tree/master
+   bin/redcap
+   lib/redcap/uploader.rb
+
+Amend this line in redcap to fit your installation and give it a try.
+   require "redcap/uploader"
+
+== usage
+
+Upload a JPG:
+    redcap your_image.jpg first_name last_name SL_password
+
+Upload a PNG to the preview grid:
+    redcap -g preview picture.png first_name last_name SL_password
+
+Note you can upload any image format that your installation of ImageMagick
+can read.
+
+== release notes
+All images are uploaded into the top level of your Inventory. [to be
+fixed for release 1.0.0]
+
+Second Life requires the uploaded image dimensions to be powers of 2.  If you'd
+like to re-size your image to its original aspect ratio, make use of
+Uploader::aspect_ratio.  (see forthcoming LSL example)
+
+installing ImageMagick and RMagick: http://rmagick.rubyforge.org/install-osx.html
+
+When you install ImageMagick, make sure you include the jpeg2 variant:
+    sudo port install tiff -macosx imagemagick +q8 +gs +wmf +jpeg2
+
+To make sure your ImageMagick can produce SL-compatible JPEG-2000 files,
+issue the following command:
+   identify -list format | grep JPC
+The JPC line should include "rw-" indicating it can write files, like:
+    JPC* JPC       rw-   JPEG-2000 Code Stream Syntax
+
+The /tests were developed for a previous release and do not run at this time.
+
+
+== copyright
+
+redcap -- library for uploading files to Second Life
+Copyright 2009  Paul Morganthall
+
+redcap is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,60 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name     = "redcap"
+    gem.summary  = %Q{Utilities for uploading files to Second Life}
+    gem.email    = "slothbear@constella.org"
+    gem.homepage = "http://adammarker.org/redcap"
+    gem.authors  = ["Paul Morganthall"]
+    # gem.platform = Gem::Platform::Ruby
+    gem.has_rdoc = false
+    gem.required_ruby_version = '>=1.8'
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "redcap #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 7
+:patch: 1
+:major: 0

data/bin/redcap

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+
+# redcap -- library for uploading files to Second Life
+# Copyright 2009  Paul Morganthall
+# 
+# redcap is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'redcap/uploader'
+require 'getoptlong'
+
+synopsis = %{# == Synopsis
+#
+# redcap: upload image to Second Life
+#         using the specified AV credentials.
+#
+# == Usage
+#
+# redcap [OPTIONS] [first_name last_name password] image_file
+#
+# --help, -h:
+#    show help
+#
+# --grid grid, -g grid:
+#    upload image to the specified grid, default = main
+#    other legal value:  preview
+#
+# first_name, last_name, password:
+#    Second Life credentials used to login.
+#
+# image_file: path to the image file to be uploaded
+}
+
+grid = 'main'
+
+opts = GetoptLong.new(
+  [ '--help', '-h', GetoptLong::NO_ARGUMENT ],
+  [ '--grid', '-g', GetoptLong::REQUIRED_ARGUMENT ]
+  )
+
+opts.each do |opt, arg|
+  case opt
+    when '--help'
+      puts synopsis
+      exit
+    when '--grid'
+      grid = arg
+  end
+end
+
+case ARGV.size
+when 4
+  first_name, last_name, password, image_file = ARGV
+else
+  puts "missing arguments (try --help)"
+  exit
+end
+
+unless image_file =~ /^http/ or File.exists?(image_file)
+  puts "file not found: #{image_file}"
+  exit
+end
+
+uploader = Redcap::Uploader.new(first_name, last_name, password, image_file, grid)
+
+
+# on successful upload, prepend the original image aspect ratio.
+if uploader.success
+  puts "file successfully uploaded, UUID=#{uploader.new_asset_id}"
+  puts "original aspect ratio: #{sprintf("%.4f", uploader.aspect_ratio)}"
+else
+  puts "error encountered while uploading:\n#{uploader.msg}"
+end

data/lib/redcap/uploader.rb

@@ -0,0 +1,208 @@
+# redcap -- library for uploading files to Second Life
+# Copyright 2009  Paul Morganthall
+# 
+# redcap is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'rubygems'
+require 'builder'
+require 'digest/md5'
+require 'logger'
+require 'net/https'
+require 'rexml/document'
+require 'RMagick'  # Requires ImageMagick with JPEG2000 (.JPC) installed
+require 'tempfile'
+require 'xmlrpc/client'
+require 'yaml'
+
+# Uploader: support for uploading files to Second Life
+# The standard upload fee (L$10) is charged upon successful upload.
+# This program was inspired and informed by the work of Katherine Berry, author
+# of phpsimcaps, AjaxLife, and other cool stuff:
+#    http://blog.katharineberry.co.uk/
+
+module Redcap
+  GRIDS = {"main"    => "https://login.agni.lindenlab.com/cgi-bin/login.cgi",
+           "preview" => "https://login.aditi.lindenlab.com/cgi-bin/login.cgi"}
+
+  class Uploader
+    attr_reader :success, :new_asset_id, :msg, :aspect_ratio
+    
+    def initialize(first_name, last_name, password, filename, grid="main")
+      @debug = false
+      @log = Logger.new('redcap.log')
+      @log.level = Logger::DEBUG    # DEBUG, WARN, 
+      @trace = Array.new            # global trace stored here for now
+        # ? seperate from log, so it can be glommed to log in one piece
+      @trace << [first_name, last_name, filename, grid, Time.now].join("/")
+      
+      #1: invoke [begin block has rescue at end]
+      begin
+        #2: login
+        login_data = login(first_name, last_name, password, GRIDS[grid])
+        login_data["seed_capability"] or raise "seed_capability not found"
+        login_data["inventory-root"] or raise "inventory-root not found"
+
+        #3: request the upload capability
+        cap_request = send_request(login_data["seed_capability"],
+          %{<llsd><array><string>NewFileAgentInventory</string></array></llsd>})
+        cap_request["NewFileAgentInventory"] or raise "no image upload capability found"
+
+        #4: request an upload ticket
+        ticket_request = send_request(cap_request["NewFileAgentInventory"],
+          encode_ticket(login_data["inventory-root"], filename))
+        ticket_request["state"] == "upload" or raise "state not upload"
+        ticket_request["uploader"] or raise "no uploader found"
+
+        #5: upload image
+        upload_status = send_request(ticket_request["uploader"], make_slimage(filename))
+        upload_status["state"] = "complete" or raise "upload failed: #{upload_status["state"]}"
+
+        #7: retrieve the UUID of the newly uploaded image
+        @success = true
+        @new_asset_id = upload_status["new_asset"]
+        # upon success, log the original request and the final result.
+        @log.info(@trace[0].to_yaml + @trace[-1].to_yaml)
+
+      rescue
+        @success = false
+        @msg = "#{$!}"
+        @log.fatal @trace.to_yaml     # on failure, log everything
+        if @debug
+          @msg += "\ntrace: #{@trace[0]}"
+        end
+      end
+
+    end # initialize
+
+    private
+    
+    def login(first_name, last_name, password, login_url, method="login_to_simulator")
+
+      login_params = {
+        :first     => first_name,
+        :last      => last_name,
+        :passwd    => "$1$" + Digest::MD5.hexdigest(password),
+        :options   => %w{inventory-root},
+        :start     => "last",
+        :channel   => "redcap.rb",          # w/channel, no need for build id.
+        :mac       => "00:D0:4D:28:A1:F1",  # required.
+        :read_critical => "true",           # skip...
+        :agree_to_tos  => "true",           #   potential...
+        :skipoptional  => "true",           #     dialogs...
+      }
+
+      login_url or raise "unrecognized grid name"
+      @trace << [login_url, method] << login_params
+      @log.debug "#{login_url} / #{method} / #{login_params}"
+      server = XMLRPC::Client.new2(login_url)
+      server.http_header_extra = {"Content-Type" => "text/xml"}
+      server.timeout = 120
+      result = server.call(method, login_params)
+      @trace << result
+      @log.debug "raw login response: #{result.to_yaml}"
+      # unearth some parameters
+      if result.has_key?("inventory-root") then
+        result["inventory-root"] = result["inventory-root"][0]["folder_id"]
+      end
+
+      # If the login server says "indeterminate", follow the path given.
+      if "indeterminate" == result["login"] then
+        @log.info "indeterminate login:\n#{result.to_yaml}"
+        next_url = result["next_url"]
+        next_method = result["next_method"]
+        message = result["message"]
+        @log.warn "Login redirected:\n#{next_url}, method: #{next_method}, message: #{message}"
+        result = login(first_name, last_name, password, next_url, next_method)     
+      elsif "false" == result["login"] or "true" != result["login"] then
+        raise "error during login: #{result["message"]}"
+      end
+
+      result
+    end  # login
+
+    # Examine URL and return the base url (server), port number, and parameter path
+    def parse_capability(cap)
+      match = %r{https://(.+):(\d+)(.+)}.match(cap)
+      match or raise "capability format not understood: #{cap}"
+      match.captures
+    end
+
+    # Convert LLSD ( Linden Lab Structured Data) into a simple hash.
+    def decode_llsd(body)
+      doc = REXML::Document.new(body)
+      pairs = Hash[*doc.elements.to_a("/llsd/map/*")]
+      result = Hash.new
+      pairs.each { |key,value| result[key.text.strip] = value.text.strip }
+      result
+    end
+
+    def send_request(capability, data)
+      @log.debug "send_request / #{capability} #{data if data[0,1] == '<'}"
+
+      server, port, path = parse_capability(capability)
+      site = Net::HTTP.new(server, port)
+      # site.set_debug_output($stderr)
+      site.use_ssl = true
+      site.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+      response = site.request_post(path, data, {"Content-Type" => "text/xml"})
+      result = decode_llsd(response.body)
+      @log.debug "response\n#{result.to_yaml}"
+      @trace << result
+      result
+    end
+
+    def encode_ticket(folder, filename)
+      request = {
+        "asset_type" => "texture",
+        "description" => "uploaded by http://adammarker.org/redcap/",
+        "folder_id" => folder,
+        "inventory_type" => "texture",
+        "name" => File.basename(filename)
+        }
+
+        xml = Builder::XmlMarkup.new(:indent => 2)
+        xml.llsd {
+          xml.map {
+            request.each do |key, value|
+              xml.key(key)
+              xml.string(value)
+            end
+          }
+        }
+      xml.target!
+    end
+
+    # adapted from function by Simon Kröger posted in comp.lang.ruby
+    # maximum dimension of an SL image is 1024.
+    def nextpow2(n)
+      throw 'eeek' if n < 0   # Simon's.  perhaps there is another way?
+      return 1 if n < 2
+      [1 << (n-1).to_s(2).size, 1024].min
+    end
+
+    # Convert image to SL standards:
+    # 1. JPEG-2000 Code Stream Syntax (JPC)
+    # 2. width and height must be a power of 2
+    def make_slimage(filename)      
+      image = Magick::Image.read(filename).first
+      @aspect_ratio = image.columns.to_f / image.rows.to_f
+      new_image = image.resize(nextpow2(image.columns), nextpow2(image.rows))
+      slimage = Tempfile.new('redcap').path
+      new_image.write("jpc:#{slimage}") or raise "Unable to write JPC image."
+      open(slimage, 'rb') { |f| f.read }
+    end
+
+  end # class
+end # module

data/redcap.gemspec

@@ -0,0 +1,61 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{redcap}
+  s.version = "0.7.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Paul Morganthall"]
+  s.date = %q{2009-07-24}
+  s.default_executable = %q{redcap}
+  s.email = %q{slothbear@constella.org}
+  s.executables = ["redcap"]
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION.yml",
+     "bin/redcap",
+     "doc/placeholder",
+     "lib/redcap/uploader.rb",
+     "redcap.gemspec",
+     "test/redcap_image.jpc",
+     "test/redcap_test.rb",
+     "test/synapse.jpg",
+     "test/test_helper.rb",
+     "test/test_llsd.rb",
+     "test/test_nextpowerof2.rb",
+     "test/test_parsecap.rb",
+     "test/test_ticket.rb"
+  ]
+  s.homepage = %q{http://adammarker.org/redcap}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.required_ruby_version = Gem::Requirement.new(">= 1.8")
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Utilities for uploading files to Second Life}
+  s.test_files = [
+    "test/redcap_test.rb",
+     "test/test_helper.rb",
+     "test/test_llsd.rb",
+     "test/test_nextpowerof2.rb",
+     "test/test_parsecap.rb",
+     "test/test_ticket.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/test/redcap_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class RedcapTest < Test::Unit::TestCase
+  def test_something_for_real
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'redcap'
+
+class Test::Unit::TestCase
+end

data/test/test_llsd.rb

@@ -0,0 +1,62 @@
+# LLSD (The Linden Lab Structured Data system) is the XML protocol
+# used for redcap's communication with Second Life.  All current
+# structures are simple maps (hashes) with pairs of key/values.
+
+# For more information regarding The LLSD flexible data system
+# see http://wiki.secondlife.com/wiki/LLSD
+
+require 'test/unit'
+require 'redcap'
+
+$llsd = %{
+  <llsd>
+    <map>
+      <key>name</key>
+      <string>/Users/orion/Desktop/textures/rose bases are red.jpeg</string>
+      <key>folder_id</key>
+      <string>98359cef-1609-4317-be54-f044cc784b0a</string>
+      <key>description</key>
+      <string>uploaded by redcap</string>
+      <key>inventory_type</key>
+      <string>texture</string>
+      <key>asset_type</key>
+      <string>texture</string>
+    </map>
+  </llsd>
+}
+
+$llsd_odd = %{
+  <llsd>
+    <map>
+      <key>name</key>
+    </map>
+  </llsd>
+}
+
+class TestLLSD < Test::Unit::TestCase
+
+  def testTypicalDecode
+    result = decode_llsd($llsd)
+    assert_equal("/Users/orion/Desktop/textures/rose bases are red.jpeg", result["name"])
+    assert_equal("98359cef-1609-4317-be54-f044cc784b0a", result["folder_id"])
+    assert_equal("uploaded by redcap", result["description"])
+    assert_equal("texture", result["inventory_type"])
+    assert_equal("texture", result["asset_type"])
+  end
+  
+  def testDecodeBadXML
+    assert_raise(REXML::ParseException) { decode_llsd("<badxml>") }
+  end
+  
+  # The LLSD should contain an even number of elements (key, value, key, value)
+  # Well formed LLSD shouldn't have an odd number, but if it does...
+  def testDecodeOddPair
+    assert_raise(ArgumentError) { decode_llsd($llsd_odd) }
+  end
+  
+  def testDecodeRandomText
+    result = decode_llsd("gibberish")
+    assert_equal({}, result)
+  end
+  
+end

data/test/test_nextpowerof2.rb

@@ -0,0 +1,39 @@
+# nextpow2 is adapted from function by Simon Kröger posted in comp.lang.ruby
+# original post: http://www.ruby-forum.com/topic/76261
+
+# The adaptation made for Second Life constrain the maximum value returned
+# to 1024, the maximum dimention of an SL texture.
+
+require 'test/unit'
+require '../redcap'
+
+class TestNextPowerOf2 < Test::Unit::TestCase
+  
+  def setup
+    @check_array = [[1, 1], [2,2]]
+    (2..9).each do | i |
+      @check_array << [ 2**i - 1, 2**i] << [2**i, 2**i] << [2**i + 1, 2**(i+1)]
+    end
+  end  
+  
+  # test copied from Rick Denatale's post to the thread mentioned above.
+  def test_normal
+    @check_array.each do | input, output |
+      assert_equal(output, nextpow2(input))
+    end
+  end
+  
+  def test_over
+    assert_equal(1024, nextpow2(1023))
+    assert_equal(1024, nextpow2(1025))
+    assert_equal(1024, nextpow2(10240))
+  end
+  
+  def test_under
+    assert_equal(2, nextpow2(2))
+    assert_equal(1, nextpow2(1))
+    assert_equal(1, nextpow2(0))
+    assert_raise(NameError) { nextpow2(-1) }
+  end
+  
+end

data/test/test_parsecap.rb

@@ -0,0 +1,31 @@
+# Second Life hands us complete URLs, but Net::HTTP requires
+# separate values for protocol, server, port, and path.
+
+# HTTPS protocol is always used, so that part of the URL is ignored.
+
+
+require 'test/unit'
+# can I use require relative??
+require '../lib/redcap/uploader'
+
+class TestParseCap < Test::Unit::TestCase
+  
+  def test_typical
+    result = parse_capability("https://sim4.aditi.lindenlab.com:12043/cap/f692b7fc-3074-a277-c08c-74363e5248cb")
+    assert_equal(3,result.size)
+    server, port, path = result
+    assert_equal("sim4.aditi.lindenlab.com", server)
+    assert_equal("12043", port)
+    assert_equal("/cap/f692b7fc-3074-a277-c08c-74363e5248cb", path)
+  end
+  
+  def test_abnormal
+    assert_raise(RuntimeError) { parse_capability("") }
+    assert_raise(RuntimeError) { parse_capability("ftp://www.secondlife.com:12045/cap/xxx") }
+    assert_raise(RuntimeError) { parse_capability("https://test.server.com:/app/path") }
+  end
+  
+  
+end
+
+# squeak

data/test/test_ticket.rb

@@ -0,0 +1,26 @@
+# A more general routine to encode to LLSD is probably in the future,
+# but the structure is so simple a custom routine is sufficient for now.
+
+# encode_ticket wraps a hash around the asset upload parameters, then uses
+# Builder to create the required LLSD structure.
+
+# The required structure is a series of <key> <string> elements, wrapped
+# in the top level <llsd><map>.  For example: 
+#     <llsd><map>
+#        <key>asset_type</key>
+#        <string>texture</string>
+#      </map></llsd>
+
+# TODO:  this test is lame and fragile; perhaps a mock object would help?
+
+require "test/unit"
+require "../redcap.rb"
+
+$answer = %{<llsd>\n  <map>\n    <key>name</key>\n    <string>file.jpg</string>\n    <key>folder_id</key>\n    <string>000-ffff-f0lde4</string>\n    <key>description</key>\n    <string>uploaded by redcap</string>\n    <key>inventory_type</key>\n    <string>texture</string>\n    <key>asset_type</key>\n    <string>texture</string>\n  </map>\n</llsd>\n}
+
+class TestTicket < Test::Unit::TestCase
+  def test_typical
+    result = encode_ticket("000-ffff-f0lde4", "file.jpg")
+    assert_equal($answer, result)
+  end
+end