Calise calise

.TH calise-service 1 "February 22 2012" "Nicolò Barbon"
.SH NAME
Calise \- Camera Light Sensor Project
.SH SYNOPSIS
.B calised
.BR [SWITCH]
.PP
.SH DESCRIPTION
Calise is a python program that uses any system supported camera as a light
sensor. The program calculates ambient brightness and suggests (or sets) the
screen's correct backlight using a webcam.

Service version is optimized for long-time usage and its power/cpu time usage
is negligible.

.PP
.SH GLOBAL OPTIONS
Options available either with service started or starting the service. If sent
to a started service will be effective only on next non-manual capture or after
giving a
.I \-\-restart
command.
.TP
.B \-h, \-\-help
Print a help screen and exit.
.TP
.B \-\-version
Print program name and version and exit.
.TP
.B \-\-no-geoip/\-\-geoip
Disable/Enable geoip internet lookup. Is set to True by default.
Lookup happens once per half an hour.

Geoip lookup is done with SSL connection to "geoiplookup.wikimedia.org".
It's not as precise as manual entering
.I latitude
and
.I longitude
but if you're not in a fixed place avoids you to manually set location every
time it changes.
.TP
.B \-\-no-screen/\-\-screen
Disable/Enable screen-brightness compensation. Is set to True by default.

The screen has a certain amount of backlight that can lead to imprecision of
capture values obtained. With bright ambient brightness the amount of
imprecision is negligible but when the ambient brightness is low, error
can be even more than 10/255. Screen-brightness compensation can correct that
error up to 80%.

To see if your screen isn't that bright to need this contol being active try
that: with low light (not complete darkness though) let the screen be as
"white" as possible (open a white image or so), do a capture *with* the
control enabled and, same situation and setting, one *without*. Compare.
.TP
.B \-\-no-weather/\-\-weather
Disable/Enable weather internet lookup. Is set to True by default.
Lookup happens once per hour.

Wheather lookup optimization feature grabs, through SSL connection to several
APIs, weather conditions of profile-specified latitude/longitude from internet
and sets a daytime multiplier accordingly (from 0.2 to 1.0), for example, if
weather is 'cloudy', multiplier will be ~0.23, else if weather is 'clear' it
will be 1.00.
.TP
.B \-\-location <lat>:<lon>
Set current location. <lat> (latitude) and <lon> (longitude) have to be
expressed as float degrees.

Geolocation allows the service to optimize captures according to current
condition of the sun: dawn, day, sunset, night. During dawns and sunsets (from
15° to -6° above the horizon), since ambient brightness increases/decreases
rapidly, captures are done often; during the day (more than 15° above the
hotizon) captures are set according to weather conditions or, if not able to
obtain those, to 3min; by night (less than -6° above the horizon) the service
puts itself in idle state till next dawn.
.TP
.B \-\-capture-number <int>
.TP
.B \-\-capture-interval <float>
Set number and interval (in seconds) of captures per "capture-session".

The service executes once every X seconds (value obtained with the help
of geolocation coordinates), and on every execution, takes some captures
on a specified interval. These options control the number and the time interval
of the captures.
.TP
.B \-\-twilight\-mul <float>
Set the multiplier for dawn/sunset sleeptime.

The service sets dawn/sunset sleeptime to (dawn/sunset duration * 0.01) * 0.8
(where 0.8 is the default multiplier), setting a different multiplier will
increase/decrease the sleeptime proportionally.
.TP
.B \-\-day\-sleeptime <float>
Set maximum seconds between captures during the day.

During the day (not night nor dawns/sunsets) the service takes a capture every
X seconds. X can vary from X * 0.2 to X * 1.0 if weather lookup it's enabled
(and internet connection available) or be equal to X * 0.6 elsewhere; this
control sets X.
.TP
.B \-\-night\-sleeptime <float>
Set seconds between captures at night, "0" means no captures (default).
.TP
.B \-\-loglevel <level>
Set log <level> to either "critical", "error", "warning", "info" (default),
"debug". This setting does not affect the log level of the logfile wich is set
to be as verbose as possible (debug).
.TP
.B \-\-logfile <path>
Specify a valid path to a file where to save application log. If not specified,
the log is stored in calise's temporary directory and removed with that
directory on exit.
.PP
.SH START ONLY OPTIONS
.TP
options available only when starting the service.
.TP
.B \-p, \-\-profile <name>|<path>
Read given profile name (to be found in calise xdg-config directory) or a
valid path. Default is profile named "default" in calise xdg-config directory.
.PP
.SH EXECUTION OPTIONS
.TP
These options are available only if the service is already running (and won't \
start/stop the service).
.TP
.B \-k, \-\-stop
Terminate the service.
.TP
.B \-e, \-\-pause
Pause capture thread.
.TP
.B \-r, \-\-resume
Resume capture thread (from a "pause" state).
.TP
.B \-\-restart
Restart the capture thread. Read
.I GLOBAL_OPTIONS
description for further infos about that command.
.TP
.B \-c, \-\-capture
Calculate and automatically set backlight step. The service can be either
running (and if so, after the capture, is resumed) or paused.
.TP
.B \-d, \-\-dump
Display last capture data.
.TP
.B \-a, \-\-dump\-all
Display all captures data.
.TP
.B \-\-dump\-settings
Display current execution's settings.
.PP
.SH EXAMPLES
.TP
.B calised
Start the service with default profile.
.TP
.B calised \-\-profile foobar \-\-no\-weather \-\-loglevel warning
Start the service with profile foobar, without weather optimization feature and
with log level set to WARNING.
.TP
.B calised \-\-stop
(if the service is running) Terminate a running service.
.TP
.B calised \-c
(if the service is running) Do a capture and set the backlight accordingly.
.TP
.B calised \-\-dump\-all \-\-dump\-settings \-c
(if the service is running) Do a capture and display both all captures's data
and current settings.
.TP
.B calised \-\-dump
(if the service is running) Display last capture data.
.PP
.SH "SEE ALSO"
calise, sample.conf
.\.PP
.\.SH "HTML Documentation"
.\None
.SH AUTHOR
.TP
Written by Nicolò Barbon.