axis-netcam 0.1.0 → 0.2.0

data/CHANGELOG.txt

@@ -1,3 +1,13 @@
+=== 0.2.0 :: 2007-08-13
+
+* Added methods for obtaining camera parameters and for calibrating the
+  camera's position.
+* The library can now be installed directly as a Rails plugin (instead
+  of installing as a RubyGem). See README for instructions.
+* Added method for fetching the camera's PTZ limits.
+* snapshot_jpeg method now takes an optional hash of parameters to send
+  with the snapshot request.
+
 === 0.1.0 :: 2007-07-26
 
 * First public release.

data/README.txt

@@ -1,5 +1,10 @@
 = AxisNetcam
 
+<b>AxisNetcam provides a Ruby interface for interacting with network cameras
+from  Axis Communications.</b>
+
+=== Copyright & Contact Info
+
 <i>Copyright 2007 Urbacon Ltd.</i>
 
 For info and downloads please see:
@@ -9,10 +14,21 @@ For info and downloads please see:
 You can contact the author at:
 
   matt at roughest dot net
+
+=== Installation
+
+As a RubyGem[http://rubygems.org/read/chapter/3]):
+
+  gem install axis-netcam
   
+As a plugin in a Rails application (this will install as an svn external,
+so your installation will be linked to the newest, bleeding-edge version
+of AxisNetcam):
 
-<b>AxisNetcam provides a Ruby interface for interacting with network cameras
-from  Axis Communications.</b>
+  cd <your Rails application's root directory>
+  ruby script/plugin install -x http://axis-netcam.rubyforge.org/svn/trunk/lib/axis-netcam
+
+=== Usage  
 
 Note that only a subset of the full Axis API is currently implemented, but the most
 useful functionality is in place.
@@ -31,7 +47,7 @@ Example usage:
   f.write(c.snapshot_jpeg)
   f.close
   
-For more information about using a Camera object, see the AxisNetcam::Camera RDocs.
+For more information about using the Camera class, see the AxisNetcam::Camera RDocs.
 
 
 ------

data/lib/axis-netcam/camera.rb

@@ -1,3 +1,22 @@
+#--
+# This file is part of axis-netcam.
+#
+# Copyright (2007) Matt Zukowski <matt at roughest dot net>.
+# 
+# axis-netcam is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+# 
+# axis-netcam 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 Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#--
+
 require 'net/http'
 require 'cgi'
 require 'logger'
@@ -28,7 +47,7 @@ module AxisNetcam
   class Camera
     
     # The HTTP network connection to the camera.
-    @@http = nil
+    @http = nil
     
     attr_reader :hostname, :logger
     
@@ -57,10 +76,11 @@ module AxisNetcam
       # viewing angle) and 10000 approaching a camera's maximum zoom. Again,
       # this depends on your camera's capabilities.
       def get_position
-        str = axis_action("com/ptz.cgi", {'query' => 'position'}).split
-        pan = str[0].split("=").last
-        tilt = str[1].split("=").last
-        zoom = str[2].split("=").last
+        raw = axis_action("com/ptz.cgi", {'query' => 'position'})
+        str = raw.split
+        pan = str[0].split("=").last.to_f
+        tilt = str[1].split("=").last.to_f
+        zoom = str[2].split("=").last.to_i
         
         {:pan => pan, :tilt => tilt, :zoom => zoom}
       end
@@ -108,9 +128,89 @@ module AxisNetcam
         positions
       end
       
+      # Returns a hash with info about the camera's point-tilt-zoom limits.
+      #
+      # The returned hash will look something like:
+      #
+      #   {'MinPan' => "-169",
+      #    'MaxPan' => "169",
+      #    'MinTilt' => "-90",
+      #    'MaxTilt' => "10",
+      #    'MinZoom' => "1",
+      #    'MaxZoom' => "19999"}
+      #
+      # The pan and tilt limit values assume that your camera's image is not
+      # rotated. If you want to use these values in <tt>ptz</tt> calls
+      # and your image is configured to be rotated, then you should also
+      # specify <tt>:imagerotation => 0</tt> as one of your parameters
+      # to <tt>ptz</tt>. For example:
+      #
+      #   limits = c.get_ptz_limits
+      #   c.ptz(:tilt => limits['MaxTilt'], :imagerotation => 0)
+      #
+      # Alternatively, you can specify a +rotation+ argument. This will
+      # automatically adjust the returned pan and tilt values to match
+      # the given rotation. You can also specify :auto instead of providing
+      # a numeric value, in which case the system will try to fetch
+      # the rotation value for you (but be careful, because this can slow
+      # things down, since the camera must be queried first).
+      def get_ptz_limits(rotation = nil)
+        l = get_parameters("PTZ.Limit.L1")
+        return l unless rotation
+        
+        rotation = get_current_image_rotation if rotation == :auto
+        
+        # TODO: this only works for the 0, 90, 180, 270 rotations but not arbitrary values
+        case rotation
+        when 90
+          l['MinPan'], l['MaxPan'], l['MinTilt'], l['MaxTilt'] =
+          l['MinTilt'], l['MaxTilt'], l['MinPan'], l['MaxPan']
+        when 180
+          l['MinPan'], l['MaxPan'], l['MinTilt'], l['MaxTilt'] =
+          l['MinPan'], l['MaxPan'], l['MaxTilt']*-1, l['MinTilt']*-1
+        when 270
+          # FIXME: This transformation appears to be busted :(
+          l['MinPan'], l['MaxPan'], l['MinTilt'], l['MaxTilt'] =
+          l['MinTilt'], l['MaxTilt'], l['MinPan']*-1, l['MaxPan']*-1
+        end
+        
+        l
+      end
+      
+      # Points the camera at the given preset.
       def point_at_preset_name(preset_name)
         axis_action("com/ptz.cgi", {'gotoserverpresetname' => preset_name})
       end
+      
+      # Tries to 'calibrate' the camera by rotating to all extremes.
+      #
+      # This may be useful when the camera is shifted by some external
+      # force and looses its place. Running the calibration should reset 
+      # things so that the camera's absolute point and tilt co-ordinates are
+      # consistent relative to the camera's base.
+      def calibrate
+        @log.info("Starting camera calibration...")
+        
+        pos = get_position
+        limits = get_ptz_limits(:auto)
+        
+        zoom(limits['MinZoom'])
+        (1..2).each do # do it twice, just to be safe...
+          sleep(3)
+          ptz(:pan => limits['MinPan'], :tilt => limits['MinTilt'])
+          sleep(7)
+          ptz(:pan => limits['MinPan'], :tilt => limits['MaxTilt'])
+          sleep(7)
+          ptz(:pan => limits['MaxPan'], :tilt => limits['MaxTilt'])
+          sleep(7)
+          ptz(:pan => limits['MaxPan'], :tilt => limits['MinTilt'])
+          sleep(7)
+        end
+        
+        ptz(pos)
+        
+        @log.info("Finished camera calibration.")
+      end
     end
     include PTZ
     
@@ -194,6 +294,7 @@ module AxisNetcam
       # Returns JPEG data with a snapshot of the current camera image.
       # size :: optionally specifies the image size -- one of :full, :medium, 
       #         or :thumbnail, or a string specifying the WxH dimensions like "640x480".
+      # options :: hash of additional options (if any) to send with the image request
       #
       # To dump the JPEG data to a file, you can do something like this:
       #
@@ -204,20 +305,23 @@ module AxisNetcam
       #   f.write(data)
       #   f.close
       #
-      def snapshot_jpeg(size = :full)
+      # The options hash can include parameters such as 'compression', 'rotation', 'date', etc.
+      # See http://www.axis.com/techsup/cam_servers/dev/cam_http_api_2.htm#api_blocks_image_video_jpeg_snapshot
+      # for more information.
+      def snapshot_jpeg(size = :full, options = {})
         case size
         when :thumbnail
           resolution = "160x120"
         when :medium
           resolution = "480x360"
         when :full
-          resolution = "640x480"
+          resolution = "704x480"
         else
           resolution = size
         end
         
         axis_action("jpg/image.cgi", 
-          {'resolution' => resolution, 'text' => '0'})
+          options.merge('resolution' => resolution))
       end
       
       # Returns the URI for accessing the camera's streaming Motion JPEG video.
@@ -234,12 +338,91 @@ module AxisNetcam
         end
         "http://#{hostname}/axis-cgi/mjpg/video.cgi?resolution=#{resolution}&text=0"
       end
+      
+      # Returns the current image rotation setting.
+      def get_current_image_rotation
+        v = get_parameters("Image.I0.Appearance.Rotation")
+        if v && v["Image.I0.Appearance.Rotation"]
+          v["Image.I0.Appearance.Rotation"]
+        else
+          nil
+        end
+      end
     end
     include Video
     
     # Functionality related to obtaining information about the camera, such as its
     # status, model number, etc.
     module Info
+      # Returns a hash enumerating the camera's various parameters.
+      # The +group+ parameter limits the returned values to the given group.
+      # Note that if given, the group is removed from the parameter names.
+      #
+      # For example:
+      # 
+      #   c.get_parameters("PTZ.Limit")
+      #
+      # Returns:
+      #   
+      #  {"L1.MaxFocus"=>9999, "L1.MaxFieldAngle"=>50, "L1.MaxTilt"=>10, 
+      #   "L1.MinFieldAngle"=>1, "L1.MaxPan"=>169, "L1.MaxIris"=>9999, 
+      #   "L1.MaxZoom"=>19999, "L1.MinFocus"=>1, "L1.MinPan"=>-169, 
+      #   "L1.MinIris"=>1, "L1.MinZoom"=>1, "L1.MinTilt"=>-90}
+      #
+      # But the following:
+      #
+      #   c.get_parameters("PTZ.Limit.L1")
+      #
+      # Returns:
+      #
+      #   {"MaxIris"=>9999, "MaxZoom"=>19999, "MaxTilt"=>10, "MaxFocus"=>9999,
+      #    "MaxPan"=>169, "MinFieldAngle"=>1, "MinTilt"=>-90, "MinPan"=>-169, 
+      #    "MinIris"=>1, "MinZoom"=>1, "MinFocus"=>1, "MaxFieldAngle"=>50}
+      #
+      def get_parameters(group = nil)
+        params = {
+          'action' => 'list', 
+          'responseformat' => 'rfc'
+        }
+        params['group'] = group if group
+        
+        response = axis_action("admin/param.cgi", params)
+        
+        if response =~ /Error -1 getting param in group '.*?'!/
+          raise RemoteError, "There is no parameter group '#{group}' on this camera."
+        end
+        
+        values = {}
+        response.each do |line|
+          k,v = line.split("=")
+          k.strip!
+          
+          if v.nil?
+            v = nil
+          else
+            case v.strip
+            when /^true$/
+              v = true
+            when /^false$/
+              v = false
+            when /^[-]?[0-9]+$/
+              v = v.to_i
+            when /^[-]?[0-9]+\.?[0-9]+$/
+              v = v.to_f
+            else
+              v = v.strip
+            end
+          end
+        
+          key = k.gsub(group ? "root.#{group}." : "root.", "")
+          
+          values[key] = v
+        end
+        
+        values
+      end
+      
+      
       # Returns the raw camera server report. 
       #
       # The report is a string with info about the camera's status and parameters,
@@ -266,13 +449,7 @@ module AxisNetcam
       
       # Returns the camera's model name.
       def model
-        begin
-          server_report =~ /prodshortname\s*=\s*"(.*?)"/i
-          $~[1]
-        rescue RemoteTimeout, RemoteError => e
-          @error = e
-          nil
-        end
+        extract_value_pairs_from_server_report(['prodshortname'])['prodshortname']
       end
       
       # Returns a code describing the camera's current status.
@@ -306,6 +483,7 @@ module AxisNetcam
           :error
         end
       end
+      alias status status_code
       
       # Returns the result of the status message resulting from the last 
       # status_code call. If no status message is available, status_code
@@ -321,6 +499,11 @@ module AxisNetcam
     end
     include Info
     
+    def to_s
+      s = super
+      s.gsub(">", %{ @hostname=#{hostname.inspect}>})
+    end
+    
     private
       # Executes an AXIS HTTP API call.
       # script :: the remote cgi script to call
@@ -335,16 +518,16 @@ module AxisNetcam
           Timeout.timeout(15) do
             req = Net::HTTP::Get.new(cmd_uri)
             
-    #        if @@http && @@http.active?
-    #          @log.debug "AXIS REMOTE API reusing HTTP connection #{@@http}"
-    #          http = @@http
-    #        else
+            if @http && @http.active?
+              @log.debug "AXIS REMOTE API reusing HTTP connection #{@http}"
+              http = @http
+            else
               @log.debug "AXIS REMOTE API opening new HTTP connection to '#{hostname}'"
               http = Net::HTTP.start(hostname)
               http.read_timeout = 15 # wait 15 seconds for camera to respond, then give up
               http.open_timeout = 15
-    #          @@http = http
-    #        end
+              @http = http
+            end
             
             req.basic_auth @username, @password
             
@@ -377,6 +560,22 @@ module AxisNetcam
           raise RemoteTimeout, err
         end
       end
+      
+      def extract_value_pairs_from_server_report(keys)
+        values = {}
+        report = server_report
+        begin
+          keys.each do |k|
+            report =~ Regexp.new(%{#{k}\s*=\s*"(.*?)"}, "i")
+            values[k] = $~[1] if $~ && $~[1]
+          end
+        rescue RemoteTimeout, RemoteError => e
+          @error = e
+          nil
+        end
+        
+        values
+      end
     
       # Raised when a Camera is instantiated with incorrect username and/or password.
       class InvalidLogin < Exception

data/lib/axis-netcam/version.rb

@@ -1,7 +1,7 @@
 module AxisNetcam #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 1
+    MINOR = 2
     TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: axis-netcam
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2007-07-26 00:00:00 -04:00
+  version: 0.2.0
+date: 2007-08-13 00:00:00 -04:00
 summary: Provides a Ruby interface for interacting with network cameras from Axis Communications.
 require_paths: 
 - lib