i hate computers

doc/conf.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-\
+import sys,os
+
+pardir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+print(pardir)
+sys.path.append(pardir)
+
+from sphinx_materialdesign_theme  import __version__
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+version = __version__
+release = __version__
+
+
+project = 'LectureSight'
+author = 'The LectureSight Athors'
+
+language = 'en'
+
+html_favicon = '_static/favicon.ico'
+html_logo = '_static/logo.png'
+
+html_theme = 'sphinx_materialdesign_theme'
+html_theme_path = ['../']
+
+html_theme_options = {
+    # Specify a list of menu in Header.
+    # Tuples forms:
+    #  ('Name', 'external url or path of pages in the document', boolean, 'icon name')
+    #
+    # Third argument:
+    # True indicates an external link.
+    # False indicates path of pages in the document.
+    #
+    # Fourth argument:
+    # Specify the icon name.
+    # For details see link.
+    # https://material.io/icons/
+    'header_links' : [
+       ('Home', 'index', False, 'home'),
+       ("ExternalLink", "http://example.com", True, 'launch'),
+       ("NoIconLink", "http://example.com", True, ''),
+       ("GitHub", "https://github.com/myyasuda/sphinx_materialdesign_theme", True, 'link')
+    ],
+
+    # Customize css colors.
+    # For details see link.
+    # https://getmdl.io/customize/index.html
+    #
+    # Values: amber, blue, brown, cyan deep_orange, deep_purple, green, grey, indigo, light_blue,
+    #         light_green, lime, orange, pink, purple, red, teal, yellow(Default: indigo)
+    'primary_color': 'indigo',
+    # Values: Same as primary_color. (Default: pink)
+    'accent_color': 'pink',
+
+    # Customize layout.
+    # For details see link.
+    # https://getmdl.io/components/index.html#layout-section
+    'fixed_drawer': True,
+    'fixed_header': True,
+    'header_waterfall': True,
+    'header_scroll': False,
+
+    # Render title in header.
+    # Values: True, False (Default: False)
+    'show_header_title': False,
+    # Render title in drawer.
+    # Values: True, False (Default: True)
+    'show_drawer_title': True,
+    # Render footer.
+    # Values: True, False (Default: True)
+    'show_footer': True
+}
+
+html_show_sourcelink = True

doc/config/calibration.rst

@@ -0,0 +1,192 @@
+Calibration
+===========
+
+After getting the overview camera and the PTZ camera to work, we have to
+calibrate the system so that the two can work together correctly.
+
+Co-ordinates
+------------
+
+LectureSight uses 3 co-ordinate systems:
+
+-  `Video Analysis <../modules/videoanalysis>`__ uses the dimensions of
+   the overview camera image (for example 640x360). Pixel counts and
+   movement thresholds defined for object tracking therefore refer to
+   these dimensions.
+
+-  The `Camera Operator <../modules/cameraoperator-ptz>`__ uses a
+   normalized co-ordinate system from -1 to 1 on both the horizontal and
+   vertical axes, where the top-left is (-1, -1), centre is (0,0) and
+   bottom-right is (1,1). Zoom is mapped from 0 (wide) to 1 (close).
+
+-  The `Steering Worker <../modules/steeringworker-relativemove>`__ uses
+   the co-ordinate system of the PTZ camera.
+
+    `VAPIX <../modules/ptzcontrol-vapix>`__ cameras use degrees as
+    co-ordinates. As LectureSight manages PTZ co-ordinates as integers,
+    VAPIX co-ordinates are scaled up by 100 by the camera driver to
+    preserve precision, so 37.65 degrees is represented as 3765.
+
+Inverted cameras
+----------------
+
+If the Overview Camera is mounted inverted (up-side down), you can
+invert the overview image using:
+
+::
+
+    cv.lecturesight.framesource.inverted=true
+
+If the PTZ Camera is mounted inverted, you may need to add these
+properties for some `VISCA <../modules/ptzcontrol-visca>`__ cameras:
+
+::
+
+    cv.lecturesight.ptz.steering.worker.relativemove.xflip=true
+    cv.lecturesight.ptz.steering.worker.relativemove.yflip=true
+
+and this property for `VAPIX <../modules/ptzcontrol-vapix>`__ cameras:
+
+::
+
+    cv.lecturesight.vapix.camera.inverted=true
+
+Scene Profile
+-------------
+
+Create a new `Scene Profile <../ui/profile>`__ to restrict the area in
+which the system tracks objects.
+
+Scene Limits
+------------
+
+These 4 configuration properties map the overview image to the camera
+PTZ co-ordinates.
+
+::
+
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.left
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.right
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.top
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.bottom
+
+Initially these values are not set, and thus the limits of the camera's
+co-ordinates are used as the scene limits.
+
+Manual Calibration
+~~~~~~~~~~~~~~~~~~
+
+To set values for the four scene limits, disable camera steering by
+using the following command on the `console <../core/console>`__
+
+::
+
+    cs:off
+
+Move the production camera (using the PTZ Camera's remote control or web
+interface) first so that the PTZ Camera is centred on the top-left point
+of the overview image, and then on the bottom-right point.
+
+Note the camera's co-ordinates at those points in the `PTZ Camera
+Control <../ui/cameracontrol>`__ window. Update the
+``lecturesight.properties`` configuration with those values, and restart
+LectureSight.
+
+Marker Calibration
+~~~~~~~~~~~~~~~~~~
+
+!!! info "Automatic marker calibration is only supported for
+`VAPIX <../modules/ptzcontrol-vapix>`__ cameras."
+
+Marker calibration maps overview co-ordinates to camera pan and tilt
+values by matching positions on the overview image with camera preset
+positions.
+
+    The calibration process creates horizontal and vertical conversion
+    models using `spline
+    interpolation <https://en.wikipedia.org/wiki/Spline_interpolation>`__
+    inside the range of the marker points, and linear extrapolation
+    outside the range, to convert between overview image co-ordinates
+    and camera positions. This will in general provide more accurate
+    results than setting the scene limits manually.
+
+To set up marker calibration:
+
+-  In the `Scene Profile Editor <../ui/profile#calibration-markers>`__,
+   identify 3 or more fixed points on the image (for example the corner
+   of a fixed blackboard, or a light switch). The set of points should
+   cover most of the horizontal and vertical range of the presentation
+   area.
+-  Create calibration markers at each point. Give each marker a name,
+   for example ``m1``, ``m2``, ``m3``, ``m4``, ``m5``, and save the
+   profile.
+-  In the camera web interface, create a set of presets with the same
+   names as the calibration markers. At each preset, the camera should
+   be centred on the venue feature identified by the matching
+   calibration marker.
+-  Restart LectureSight, or use the `console <../core/console>`__
+   command ``cs:calibrate`` to trigger marker calibration:
+
+::
+
+    g! cs:calibrate
+    Automatic calibration completed
+
+The calibration process discovers the pan and tilt co-ordinates of each
+preset by moving the camera in turn to each position, with a pause time
+of 2.5s between presets.
+
+On subsequent startup, the `Steering
+Worker <../modules/steeringworker-relativemove>`__ will report whether
+automatic calibration has been used, and if successful, the values of
+the calculated pan and tilt thresholds:
+
+::
+
+    Automatic calibration, camera pan/tilt limits: pan -3673 to 3649, tilt -2596 to 2348
+
+Once automatic calibration has successfully run, changes to the
+configured scene limits will have no effect, as the calculated values
+will be used.
+
+If no calibration markers have been created or there are too few
+matching markers and presets, the log will include:
+
+::
+
+    Automatic calibration not possible
+
+This can be caused by markers that are too close together in the x or y
+axes. Try to adjust the marker positions so they are distributed across
+the field of view, both horizontally and vertically.
+
+Initial position
+----------------
+
+Set the initial position of the `PTZ
+camera <../modules/cameraoperator-ptz>`__
+
+::
+
+    cv.lecturesight.cameraoperator.ptz.pan=0.0
+    cv.lecturesight.cameraoperator.ptz.tilt=0.0
+    cv.lecturesight.cameraoperator.ptz.zoom=0.0
+
+Frame width
+-----------
+
+Set the frame width of the `PTZ
+camera <../modules/cameraoperator-ptz>`__ at the configured zoom
+position, relative to the width of the overview image, which is 2 in
+normalized co-ordinates (-1 to 1).
+
+For example a frame.width of 0.5 means that the PTZ Camera's image is
+25% of the width of the overview image (0.5 / 2).
+
+::
+
+    cv.lecturesight.cameraoperator.ptz.frame.width=0.5
+
+You can verify visually that the frame width is correct by looking at
+the frame boundary guides on the `PTZ Camera
+Control <../ui/cameracontrol>`__ window.

doc/config/examples.rst

@@ -0,0 +1,120 @@
+Configuration Examples
+======================
+
+Logitech C920 Overview Camera, Axis V5915 PTZ Camera
+----------------------------------------------------
+
+::
+
+    # --- Webcam V4L2 framesource
+    cv.lecturesight.framesource.input.mrl=v4l2:///dev/logitech[width=640;height=360;Power Line Frequency=50 Hz;Focus, Auto=0;Focus (absolute)=0;Zoom, Absolute=200]
+    cv.lecturesight.framesource.v4l.format=MJPEG
+    cv.lecturesight.framesource.maxfps=25
+
+    # --- VAPIX Configuration (Axis cameras)
+    cv.lecturesight.vapix.camera.host=camera-hostname.some.domain
+    cv.lecturesight.vapix.camera.username=root
+    cv.lecturesight.vapix.camera.password=PASSWORD
+    cv.lecturesight.vapix.camera.pan.min=-17000
+    cv.lecturesight.vapix.camera.pan.max=17000
+    cv.lecturesight.vapix.camera.tilt.min=-2000
+    cv.lecturesight.vapix.camera.tilt.max=9000
+    cv.lecturesight.vapix.camera.zoom.min=1
+    cv.lecturesight.vapix.camera.zoom.max=9999
+    cv.lecturesight.vapix.camera.zoom.maxspeed=1
+    cv.lecturesight.vapix.updater.interval=100
+
+    # --- Video Analysis
+    cv.lecturesight.videoanalysis.change.threshold=30
+    cv.lecturesight.videoanalysis.cell.activation.threshold=2
+    cv.lecturesight.videoanalysis.object.cells.min=15
+    cv.lecturesight.videoanalysis.object.cells.max=128
+    cv.lecturesight.videoanalysis.object.dormant.max=1500
+    cv.lecturesight.videoanalysis.object.match.threshold=15
+
+    # --- Camera Steering Worker (relative movement)
+    cv.lecturesight.ptz.steering.worker.relativemove.move.damp.pan=0.65
+    cv.lecturesight.ptz.steering.worker.relativemove.move.damp.tilt=0.2
+    cv.lecturesight.ptz.steering.worker.relativemove.move.alpha.x=2000
+    cv.lecturesight.ptz.steering.worker.relativemove.move.alpha.y=2000
+    cv.lecturesight.ptz.steering.worker.relativemove.move.stop.x=35
+    cv.lecturesight.ptz.steering.worker.relativemove.move.stop.y=200
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.left=-2500
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.right=2500
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.top=-600
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.bottom=-5000
+
+    # --- Pan-only Camera Operator
+    cv.lecturesight.cameraoperator.ptz.pan=0.0
+    cv.lecturesight.cameraoperator.ptz.tilt=0.4
+    cv.lecturesight.cameraoperator.ptz.zoom=0.1
+    cv.lecturesight.cameraoperator.ptz.frame.width=0.8
+    cv.lecturesight.cameraoperator.ptz.timeout=500
+    cv.lecturesight.cameraoperator.ptz.idle.preset=Home
+    cv.lecturesight.cameraoperator.ptz.start.preset=Start
+    cv.lecturesight.cameraoperator.ptz.target.limit=2
+
+    # --- Scene Profile
+    cv.lecturesight.profile.manager.active.profile=overview
+
+    # --- Scheduler: watch the Galicaster schedule file
+    cv.lecturesight.scheduler.enable=true
+    cv.lecturesight.scheduler.schedule.file=/usr/share/galicaster-repository/attach/calendar.ical
+    cv.lecturesight.scheduler.timezone.offset=2
+    cv.lecturesight.scheduler.tracker.leadtime=10
+
+    # --- Enable DropWizard metrics collection
+    cv.lecturesight.util.metrics.enable=true
+
+    # --- Save overview snapshots
+    cv.lecturesight.framesource.snapshot.file=/opt/ls/record/overview.png
+
+    # --- Status Reporting
+    cv.lecturesight.status.enable=true
+    cv.lecturesight.status.name=hahn1
+    cv.lecturesight.status.url=http://lsdashboard.some.domain/lecturesight/
+    cv.lecturesight.status.interval=60
+
+Raspberry Pi Overview Camera, VISCA Vaddio HD-USB PTZ Camera
+------------------------------------------------------------
+
+::
+
+    # --- Overview camera
+    cv.lecturesight.framesource.input.mrl=rtph264://rpi-cam.some.domain:8554
+
+    # --- VISCA Camera Configuration
+    com.wulff.lecturesight.visca.port.device=/dev/ttyUSB0
+    com.wulff.lecturesight.visca.updater.interval=200
+
+    # --- Video Analysis
+    cv.lecturesight.videoanalysis.change.threshold=48
+    cv.lecturesight.videoanalysis.cell.activation.threshold=3
+    cv.lecturesight.videoanalysis.object.cells.min=20
+    cv.lecturesight.videoanalysis.object.cells.max=128
+    cv.lecturesight.videoanalysis.object.dormant.max=1500
+
+    # --- Camera Steering Worker
+    cv.lecturesight.ptz.steering.worker.relativemove.move.damp.pan=0.5
+    cv.lecturesight.ptz.steering.worker.relativemove.move.damp.tilt=0.1
+    cv.lecturesight.ptz.steering.worker.relativemove.move.alpha.x=3000
+    cv.lecturesight.ptz.steering.worker.relativemove.move.alpha.y=1000
+    cv.lecturesight.ptz.steering.worker.relativemove.move.stop.x=300
+    cv.lecturesight.ptz.steering.worker.relativemove.move.stop.y=200
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.left=-5500
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.right=3870
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.top=-600
+    cv.lecturesight.ptz.steering.worker.relativemove.scene.limit.bottom=-5000
+    cv.lecturesight.ptz.steering.worker.relativemove.focus.fixed=true
+    cv.lecturesight.ptz.steering.worker.relativemove.move.initial.delay=5000
+
+    # --- PTZ Camera Operator
+    cv.lecturesight.cameraoperator.ptz.pan=0.3
+    cv.lecturesight.cameraoperator.ptz.tilt=-0.40
+    cv.lecturesight.cameraoperator.ptz.zoom=0.55
+    cv.lecturesight.cameraoperator.ptz.timeout=500
+    cv.lecturesight.cameraoperator.ptz.idle.preset=0
+    cv.lecturesight.cameraoperator.ptz.target.limit=2
+
+    # -- Scene Profile
+    cv.lecturesight.profile.manager.active.profile=overview