summaryrefslogtreecommitdiffstats
path: root/info/blueshift.texinfo
blob: 23834110fee0d7f02a9afb3c93cec131321e9d4a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename blueshift.info
@settitle blueshift
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header


@dircategory Economy
@direntry
* blueshift: (blueshift).            Automatically adjust the colour temperature
@end direntry


@copying
Copyright @copyright{} 2014 Mattias Andrée

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@ifnottex
@node Top
@top blueshift -- Automatically adjust the colour temperature
@insertcopying
@end ifnottex

@titlepage
@title blueshift
@subtitle Automatically adjust the colour temperature
@author by Mattias Andrée (maandree)

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents



@menu
* Overview::                        Brief overview of @command{blueshift}.
* Invoking::                        Invocation of @command{blueshift}.
* Configuration API::               How to write configuration files.
* GNU Free Documentation License::  Copying and sharing this manual.
@end menu



@node Overview
@chapter Overview

Inspired by Redshift, Blueshift adjusts the colour
temperature of your monitor according to brightness
outside to reduce eye strain and make it easier to
fall asleep when going to bed. It can also be used
to increase the colour temperature and make the
monitor bluer, this helps you focus on your work.

Blueshift is not user friendly and it is not
meant too be. Blueshift does offer limited
use of command line options to apply settings,
but it is really meant for you to have configuration
files (written in Python 3) where all the policies
are implemented, Blueshift is only meant to provide
the mechanism for modifying the colour curves.
Blueshift neither provides any means of automatically
getting your geographical position; the intention is
that you should implement that in the policy yourself
using library which can do that. Additionally
Blueshift provides not safe guards from making your
screen unreadable or otherwise miscoloured; and
Blueshift will never, officially, add support
specifically for any proprietary operating system.
Blueshift is fully extensible so it is possible to
make extensions that make it usable under unsupported
systems, the base code is written in Python 3 without
calls to any system dependent functions.
If Blueshift does not work for you for any of these
reasons, you should take a look at Redshift.



@node Invoking
@chapter Invoking

Blueshift uses argparser to read options from the
commnad line. It inherits a few properaties from this:
abbreviations are supported, you only need to type the
beginning of the long options so that the rest can
be filled in unambiguously by the program; @option{--}
can be used, as usual, to make all following options
being parsed as just arguments; and @option{++} works
like @option{--}, except it only allied to the next
option. Any argument that is not parsed as an option
for Blueshift is passed onto the configuration script.

Blueshift recognises the following options:

@table @option
@item -c
@itemx --configurations FILE
Select configuration script. This defaults to the
first file of the following the exists:
@itemize @bullet
@item @file{$XDG_CONFIG_HOME/blueshift/blueshiftrc}
@item @file{$HOME/.config/blueshift/blueshiftrc}
@item @file{$HOME/.blueshiftrc}
@item @file{/etc/blueshiftrc}
@end itemize
Blueshift does not check the user home, rather it
checks @env{HOME} which should be the user home, unless
you change it yourself.

@item -p @c the long name of option is inspired from openntpd
@itemx --panic-gate
@itemx --panicgate
Applies the settings directly instead of transitioning
into the initial settings. There is not option for doing
this when the program exists. But you press @kbd{Control+c}
twice, or send SIGTERM twice, to skip transition into
default settings.

@item -h
@itemx -?
@itemx --help
Prints help information.

@item -C
@itemx --copying
@itemx --copyright
Prints copyright information.

@item -W
@itemx --warranty
Prints non-warranty information,
included in the copyright information.

@item -v
@itemx --version
Prints the name of the program and the
installed version of the program
@end table

Blueshift also supports a few options
for ad-hoc settings. These are ignored
(unlessed fetched by the configuration file)
if @option{-c} (@option{--configurations})
is used.

@table @option
@item -g
@itemx --gamma RGB
Apply gamma correction to the colour curves.
All values in the three colour curves are raised
to the power of 1 divided by @var{RGB}. Assuming
no values in the curves are larger than 1 (100 %)
the curves are bent upwards if @var{RGB} is larger
than 1.

@item -g
@itemx --gamma R:G:B
This works as @option{--gamma RGB}, except the
gamma is applied separately for the three colour
curves. If we want to apply the 0,9 gamma to the
red colour component, and 1,1 and 1,2 for the
green and blue colour components, respectively use
@option{-g 0.9:1.1:1.2} or @option{-gamma 0.9:1.1:1.2}.

@item -b
@itemx --brightness RGB
This multiplies all values in the colour curves
with @env{RGB}, effectively making the display
@env{RGB} times as bright. Values larger than 1,
will be clipped to 1. This is indented to be used
to make the screen slightly darker during the night.

@item -b
@itemx --brightness R:G:B
This option is to @option{--brightness RGB} as
@option{--gamma R:G:B} is to @option{--gamma RGB}.

@item +b
@itemx ++brightness Y
This option works as @option{--brightness RGB},
except the CIE xyY colour spaces is used instead
of sRGB and will probably make the colour curves
look better.

@item -t
@itemx --temperature TEMP
Changes the colour tempurature to @var{TEMP}
Kelvin. The standard colour tempurature is
6500 K@footnote{Or actually 6504 K using revised
constants in Plank's law}. If not specified,
the colour temperature will be 3700 K during
high night and 6500 K during the high day.

@item -l
@itemx --location LAT:LON
Specify your geographical coordinates. This
is used to determine how dark it is outside.
@env{LAT} is the latitude, floating point
measured in degrees from the equator to the
north. It is negative if you are on the
southern hemisphere. @env{LON} is the
longitude, floating point measured in degrees
from Greenwich to the east. Negative if you
are on the west side of the Earth.

@item -r
@itemx --reset
Transition from the specified settings to
normal, clean, settings.

@item -o
@itemx --output
@itemx --crtc CRTC
Select CRTC to apply changes to. This is
comma separated list, and multiple options
may be used. It is best to start one
instance per monitor with colour calibration.
@end table

@option{-g}, @option{-b}, @option{+b}, and
@option{-t} can be use twice, each, to use
different settings during the night and during
the day. While this is possible for gamma,
it is not recommended. The purpose of gamma
is to adjust the same error that are present
in minors and make all colours look correct
in relation to each other.



@node Configuration API
@chapter Configuration API

Blueshift has three colour curves:

@table @code
@item r_curve
The curve for the red colour component.
@item g_curve
The curve for the green colour component.
@item b_curve
The curve for the blue colour component.
@end table

These are @code{i_size} sized floating point
lists, where 0 is the darkest colour and 1
is the brightest colour. Values outside this
range are clipped unless @code{clip_result}
is set to @code{False}. By calling @code{clip}
(has no parameters) this clipping is done
independently of the value of @code{clip_result}.
When applied these values are automatically
translated to appropriate integer values:
[0, @code{o_size} - 1].

Blueshift provides a set of functions to
manipulate these curves:

@table @code
@item rgb_contrast(rgb)
Adjusts the contrast to @code{rgb}.

@item rgb_contrast(r, g, b)
Adjusts the contrast to @code{r}, @code{g}
and @code{b} on the red, green and blue curves,
respectively.

@item cie_contrast(y)
Adjusts the contrast to @code{y}.
The function calculate the values by using
the CIE xyY colour space instead of the sRGB
colour space.

@item rgb_brightness(rgb)
Adjusts the brightness to @code{rgb}.

@item rgb_brightness(r, g, b)
Adjusts the brightness to @code{r}, @code{g}
and @code{b} on the red, green and blue curves,
respectively.

@item cie_brightness(y)
Adjusts the brightness to @code{y}.
The function calculate the values by using
the CIE xyY colour space instead of the sRGB
colour space.

@item linearise()
Converts the colour curves from sRGB to
linear RGB. sRGB is the default colour space.

@item standardise()
Converts the colour curves from linear RGB to
sRGB, the default colour space.

@item gamma(rgb)
Adjusts the gamma to @code{rgb}.

@item gamma(r, g, b)
Adjusts the gamma to @code{r}, @code{g}
and @code{b} on the red, green and blue curves,
respectively.

@item negative(rgb)
Inverts the all values on the colour curves
if @code{rgb} is @code{True}.

@item negative(r, g, b)
Inverts the all values on the red, green and
blue curves if @code{r}, @code{g} and @code{b}
are @code{True}, respectively.

@item sigmoid(r, g, b)
An inverted sigmoid curve function is applied
to the values of in red, green and blue curves
if @code{r}, @code{g} and @code{b} are not
@code{None}, respectively. @code{r}, @code{g}
and @code{b} are the curve sigmoid curve
multipliers for the red, green and blue curves,
respectively.

@item manipulate(rgb)
Applies the function @code{rgb} : float
@click{} float to colour curves.

@item manipulate(r, g, b)
Applies the functions @code{r}, @code{g} and
@code{b} : float @click{} float to red, green
and blue colour curves, respectively.

@item temperature(temperature, algorithm)
Applies the a blackbody colour temperature of
@code{temperature}@footnote{Actually multiplied
by 1.000556328, due to revisions of natural
constants} Kelvin. Where the white point
for that temperature is calculates by
the function @code{algorithm} : @code{temperature}
@click{} (red, green, blue). When the white
point has been calculates, its components
are used as parameters in a componentwise
brightness adjustment.

There are a few algorithm for calculating the
white point included:
@table @code
@item series_d(temperature)
Can only calculate the white point correctly for
temperatures inside [4000, 7000]. The CIE illuminant
series D is used to calculate the white point.

@item simple_whitepoint(temperature)
Can only calculate the white point accurately for
temperatures inside [1000, 40000]. A mathematical
model of the @code{cmf_10deg} function is used.

@item cmf_2deg(temperature)
Uses a lookup table with linear interpolation to
calculate temperatures inside [1000, 40000].
CIE 1931 2 degree CMF is used.

@item cmf_10deg(temperature)
Uses a lookup table with linear interpolation to
calculate temperatures inside [1000, 40000].
CIE 1964 10 degree CMF is used. This is the
preferred algorithm.

@item redshift(temperature, old_version, linear_interpolation = False)
Uses the lookup table from Redshift with linear
interpolation. If @code{old_version} is @code{True}
the table Redshift<=1.8 is used, which is limited
to [1000, 10000], and is not that accurate. Otherwise
(the default) the table from Redshift>1.8 is used,
which is limited to [1000, 25100], and is accurate.

If @code{linear_interpolation} is @code{False}
(the default) the sRGB colour space is used for
interpolation, otherwise linear RGB is used.
@end table

Some of these algorithms (including @code{cmf_10deg})
are not very good by themself and should be wrapped
with @code{divide_by_maximum} or @code{clip_whitepoint}
((red, green, blue) @click{} (red, green, blue) functions.)
For example, instead of using @code{cmf_10deg}, you
can use @code{lambda t : divide_by_maximum(cmf_10deg(t))}.
@end table

Keep in mind that the order your call the
function matters. For example, adjusting
the gamma before the brightness does not
yeild the same result as in the reverse
order, the latter is the correct way to
apply gamma correction.

If you want to write your own functions
@code{curves(r, g, b)} returns a tuple
containing the tuples @code{(r_curve, r)},
@code{(g_curve, g)} and @code{(b_curve, b)}.



@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texinfo

@bye