Skip to content

Commit a288ed4

Browse files
PaintYourDragonPaintYourDragon
authored
Merge pull request #1 from tannewt/doc_fixup
Fix up docs
2 parents c65d526 + c34a8c5 commit a288ed4

File tree

2 files changed

+113
-111
lines changed

2 files changed

+113
-111
lines changed

‎README.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,17 @@ Introduction
33
============
44

55
.. image:: https://readthedocs.org/projects/adafruit-circuitpython-fancyled/badge/?version=latest
6-
76
:target: https://circuitpython.readthedocs.io/projects/fancyled/en/latest/
8-
97
:alt: Documentation Status
108

119
.. image :: https://img.shields.io/discord/327254708534116352.svg
1210
:target: https://discord.gg/nBQh6qu
1311
:alt: Discord
1412
13+
.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_FancyLED.svg?branch=master
14+
:target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_FancyLED
15+
:alt: Build Status
16+
1517
TODO
1618

1719
Dependencies

‎adafruit_fancyled.py

Lines changed: 109 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -43,24 +43,23 @@
4343

4444

4545
class CRGB(object):
46-
""" RGB (red, green, blue) color class.
46+
"""Color stored in Red, Green, Blue color space.
47+
48+
One of two ways: separate red, gren, blue values (either as integers (0 to 255
49+
range) or floats (0.0 to 1.0 range), either type is 'clamped' to valid range and
50+
stored internally in the normalized (float) format), OR can accept a CHSV color as
51+
input, which will be converted and stored in RGB format.
52+
53+
Following statements are equivalent - all return red:
54+
55+
.. code-block:: python
56+
57+
c = CRGB(255, 0, 0)
58+
c = CRGB(1.0, 0.0, 0.0)
59+
c = CRGB(CHSV(0.0, 1.0, 1.0))
4760
"""
4861

4962
def __init__(self, red, green=0.0, blue=0.0):
50-
""" Constructor for CRGB class.
51-
ACCEPTS: One of two ways: separate red, gren, blue values (either
52-
as integers (0 to 255 range) or floats (0.0 to 1.0 range),
53-
either type is 'clamped' to valid range and stored
54-
internally in the normalized (float) format),
55-
OR can accept a CHSV color as input, which will be
56-
converted and stored in RGB format.
57-
Following statements are equivalent - all return red:
58-
c = CRGB(255, 0, 0)
59-
c = CRGB(1.0, 0.0, 0.0)
60-
c = CRGB(CHSV(0.0, 1.0, 1.0))
61-
RETURNS: CRGB instance.
62-
"""
63-
6463
if isinstance(red, CHSV):
6564
# If first/only argument is a CHSV type, perform HSV to RGB
6665
# conversion.
@@ -111,27 +110,24 @@ def __str__(self):
111110

112111

113112
class CHSV(object):
114-
""" HSV (hue, saturation, value) color class.
115-
"""
113+
"""Color stored in Hue, Saturation, Value color space.
116114
117-
def __init__(self, h, s=1.0, v=1.0):
118-
""" Constructor for CHSV color class.
119-
ACCEPTS: hue as float (any range) or integer (0-256 -> 0.0-1.0)
120-
with no clamping performed (hue can 'wrap around'),
121-
saturation and value as float (0.0 to 1.0) or integer
122-
(0 to 255), both are clamped and stored internally in
123-
the normalized (float) format. Latter two are optional,
124-
can pass juse hue and saturation/value will default to 1.0.
125-
Unlike CRGB (which can take a CHSV as input), there's
126-
currently no equivalent RGB-to-HSV conversion, mostly
127-
because it's a bit like trying to reverse a hash...
128-
there may be multiple HSV solutions for a given RGB input.
129-
This might be OK as long as conversion precedence is
130-
documented, but otherwise (and maybe still) could cause
131-
confusion as certain HSV->RGB->HSV translations won't
132-
have the same input and output. Hmmm.
115+
Accepts hue as float (any range) or integer (0-256 -> 0.0-1.0) with no clamping
116+
performed (hue can 'wrap around'), saturation and value as float (0.0 to 1.0) or
117+
integer (0 to 255), both are clamped and stored internally in the normalized (float)
118+
format. Latter two are optional, can pass juse hue and saturation/value will
119+
default to 1.0.
120+
121+
Unlike `CRGB` (which can take a `CHSV` as input), there's currently no equivalent
122+
RGB-to-HSV conversion, mostly because it's a bit like trying to reverse a hash...
123+
there may be multiple HSV solutions for a given RGB input.
124+
125+
This might be OK as long as conversion precedence is documented, but otherwise (and
126+
maybe still) could cause confusion as certain HSV->RGB->HSV translations won't have
127+
the same input and output. Hmmm.
133128
"""
134129

130+
def __init__(self, h, s=1.0, v=1.0):
135131
if isinstance(h, float):
136132
self.hue = h # Don't clamp! Hue can wrap around forever.
137133
else:
@@ -153,18 +149,17 @@ def __str__(self):
153149

154150

155151
def clamp(val, lower, upper):
156-
""" Constrain value within a numeric range (inclusive).
152+
"""Constrain value within a numeric range (inclusive).
157153
"""
158154
return max(lower, min(val, upper))
159155

160156

161157
def normalize(val, inplace=False):
162-
""" Convert 8-bit (0 to 255) value to normalized (0.0 to 1.0) value.
163-
ACCEPTS: integer, 0 to 255 range (input is clamped) or a list or tuple
164-
of integers. In list case, 'inplace' can be used to control
165-
whether the original list is modified (True) or a new list
166-
is generated and returned (False).
167-
RETURNS: float, 0.0 to 1.0 range, or list of floats (or None if inplace).
158+
"""Convert 8-bit (0 to 255) value to normalized (0.0 to 1.0) value.
159+
160+
Accepts integer, 0 to 255 range (input is clamped) or a list or tuple of integers. In list case, 'inplace' can be used to control whether the original list is modified (True) or a new list is generated and returned (False).
161+
162+
Returns float, 0.0 to 1.0 range, or list of floats (or None if inplace).
168163
"""
169164

170165
if isinstance(val, int):
@@ -183,12 +178,13 @@ def normalize(val, inplace=False):
183178

184179

185180
def denormalize(val, inplace=False):
186-
""" Convert normalized (0.0 to 1.0) value to 8-bit (0 to 255) value
187-
ACCEPTS: float, 0.0 to 1.0 range or a list or tuple of floats. In list
188-
case, 'inplace' can be used to control whether the original
189-
list is modified (True) or a new list is generated and returned
190-
(False).
191-
RETURNS: integer, 0 to 255 range, or list of integers (or None if inplace).
181+
"""Convert normalized (0.0 to 1.0) value to 8-bit (0 to 255) value
182+
183+
Accepts float, 0.0 to 1.0 range or a list or tuple of floats. In list case,
184+
'inplace' can be used to control whether the original list is modified (True) or a
185+
new list is generated and returned (False).
186+
187+
Returns integer, 0 to 255 range, or list of integers (or None if inplace).
192188
"""
193189

194190
# 'Denormalizing' math varies slightly from normalize(). This is on
@@ -211,9 +207,10 @@ def denormalize(val, inplace=False):
211207

212208

213209
def pack(val):
214-
""" 'Pack' a CRGB or CHSV color into a 24-bit RGB integer.
215-
ACCEPTS: CRGB or CHSV color.
216-
RETURNS: 24-bit integer a la 0x00RRGGBB.
210+
"""'Pack' a `CRGB` or `CHSV` color into a 24-bit RGB integer.
211+
212+
:param obj val: `CRGB` or `CHSV` color.
213+
:returns: 24-bit integer a la ``0x00RRGGBB``.
217214
"""
218215

219216
# Convert CHSV input to CRGB if needed
@@ -226,9 +223,11 @@ def pack(val):
226223

227224

228225
def unpack(val):
229-
""" 'Unpack' a 24-bit color into a CRGB instance.
230-
ACCEPTS: 24-bit integer a la 0x00RRGGBB.
231-
RETURNS: CRGB color.
226+
"""'Unpack' a 24-bit color into a `CRGB` instance.
227+
228+
:param int val: 24-bit integer a la ``0x00RRGGBB``.
229+
:returns: CRGB color.
230+
:rtype: CRGB
232231
"""
233232

234233
# See notes in normalize() for math explanation. Large constants here
@@ -240,10 +239,10 @@ def unpack(val):
240239

241240

242241
def mix(color1, color2, weight2=0.5):
243-
""" Blend between two colors using given ratio.
244-
ACCEPTS: two colors (each may be CRGB, CHSV or packed integer),
245-
and weighting (0.0 to 1.0) of second color.
246-
RETURNS: CRGB color in most cases, CHSV if both inputs are CHSV.
242+
"""Blend between two colors using given ratio. Accepts two colors (each may be `CRGB`,
243+
`CHSV` or packed integer), and weighting (0.0 to 1.0) of second color.
244+
245+
:returns: `CRGB` color in most cases, `CHSV` if both inputs are `CHSV`.
247246
"""
248247

249248
clamp(weight2, 0.0, 1.0)
@@ -287,32 +286,29 @@ def mix(color1, color2, weight2=0.5):
287286
GFACTOR = 2.5 # Default gamma-correction factor for function below
288287

289288
def gamma_adjust(val, gamma_value=None, brightness=1.0, inplace=False):
290-
""" Provides gamma adjustment for single values, CRGB and CHSV types
291-
and lists of any of these.
292-
293-
ACCEPTS: One of three ways:
294-
1. A single normalized level (0.0 to 1.0) and optional gamma-adjustment
295-
factor (float usu. > 1.0, default if unspecified is GFACTOR) and
296-
brightness (float 0.0 to 1.0, default is 1.0).
297-
2. A single CRGB or CHSV type, optional single gamma factor OR a
298-
(R,G,B) gamma tuple (3 values usu. > 1.0), optional single
299-
brightness factor OR a (R,G,B) brightness tuple. The input tuples
300-
are RGB even when a CHSV color is passed.
301-
3. A list or tuple of normalized levels, CRGB or CHSV types (and
302-
optional gamma and brightness levels or tuples applied to all).
303-
304-
In cases 2 and 3, if the input is a list (NOT a tuple!), the 'inplace'
305-
flag determines whether a new tuple/list is calculated and returned,
306-
or the existing value is modified in-place. By default this is 'False'.
307-
If you try to inplace-modify a tuple, there will be...trouble.
308-
309-
RETURNS: Corresponding to above cases:
310-
1. Single normalized gamma-corrected brightness level (0.0 to 1.0).
311-
2. A normalized gamma-corrected CRGB type (NOT CHSV!).
312-
3. A list of gamma-corrected values or CRGB types (NOT CHSV!).
313-
314-
In cases 2 and 3, there is NO return value if 'inplace' is True --
315-
the original values are modified.
289+
"""Provides gamma adjustment for single values, `CRGB` and `CHSV` types
290+
and lists of any of these.
291+
292+
Works in one of three ways:
293+
1. Accepts a single normalized level (0.0 to 1.0) and optional gamma-adjustment
294+
factor (float usu. > 1.0, default if unspecified is GFACTOR) and
295+
brightness (float 0.0 to 1.0, default is 1.0). Returns a single normalized gamma-corrected brightness level (0.0 to 1.0).
296+
2. Accepts a single `CRGB` or `CHSV` type, optional single gamma factor OR a
297+
(R,G,B) gamma tuple (3 values usu. > 1.0), optional single
298+
brightness factor OR a (R,G,B) brightness tuple. The input tuples
299+
are RGB even when a `CHSV` color is passed. Returns a normalized
300+
gamma-corrected `CRGB` type (NOT `CHSV`!).
301+
3. Accept a list or tuple of normalized levels, `CRGB` or `CHSV` types (and
302+
optional gamma and brightness levels or tuples applied to all). Returns a list
303+
of gamma-corrected values or `CRGB` types (NOT `CHSV`!).
304+
305+
In cases 2 and 3, if the input is a list (NOT a tuple!), the 'inplace'
306+
flag determines whether a new tuple/list is calculated and returned,
307+
or the existing value is modified in-place. By default this is 'False'.
308+
If you try to inplace-modify a tuple, an exception is raised.
309+
310+
In cases 2 and 3, there is NO return value if 'inplace' is True --
311+
the original values are modified.
316312
"""
317313

318314
if isinstance(val, float):
@@ -390,38 +386,42 @@ def gamma_adjust(val, gamma_value=None, brightness=1.0, inplace=False):
390386
pow(val.blue, gamma_blue) * brightness_blue)
391387

392388

393-
def palette_lookup(pal, pos):
394-
""" Fetch color from color palette, with interpolation.
395-
ACCEPTS: color palette (list of CRGB, CHSV and/or packed integers),
396-
palette position (0.0 to 1.0, wraps around).
397-
RETURNS: CRGB or CHSV instance, no gamma correction applied.
389+
def palette_lookup(palette, position):
390+
"""Fetch color from color palette, with interpolation.
391+
392+
:param palette: color palette (list of CRGB, CHSV and/or packed integers)
393+
:param float position: palette position (0.0 to 1.0, wraps around).
394+
395+
:returns: `CRGB` or `CHSV` instance, no gamma correction applied.
398396
"""
399397

400-
pos %= 1.0 # Wrap palette position in 0.0 to <1.0 range
398+
position %= 1.0 # Wrap palette position in 0.0 to <1.0 range
401399

402-
weight2 = pos * len(pal) # Scale position to palette length
400+
weight2 = position * len(palette) # Scale position to palette length
403401
idx = int(floor(weight2)) # Index of 'lower' color (0 to len-1)
404402
weight2 -= idx # Weighting of 'upper' color
405403

406-
color1 = pal[idx] # Fetch 'lower' color
407-
idx = (idx + 1) % len(pal) # Get index of 'upper' color
408-
color2 = pal[idx] # Fetch 'upper' color
404+
color1 = palette[idx] # Fetch 'lower' color
405+
idx = (idx + 1) % len(palette) # Get index of 'upper' color
406+
color2 = palette[idx] # Fetch 'upper' color
409407

410408
return mix(color1, color2, weight2)
411409

412410

413-
def expand_gradient(grad, length):
414-
""" Convert gradient palette into standard equal-interval palette.
415-
ACCEPTS: List or tuple of of 2-element lists/tuples containing position
416-
(0.0 to 1.0) and color (packed int, CRGB or CHSV). It's OK if
417-
the list/tuple elements are either lists OR tuples, but don't
418-
mix and match lists and tuples -- use all one or the other.
419-
RETURNS: CRGB list, can be used with palette_lookup() function.
411+
def expand_gradient(gradient, length):
412+
"""Convert gradient palette into standard equal-interval palette.
413+
414+
:param sequence gradient: List or tuple of of 2-element lists/tuples containing
415+
position (0.0 to 1.0) and color (packed int, CRGB or CHSV). It's OK if the
416+
list/tuple elements are either lists OR tuples, but don't mix and match lists and
417+
tuples -- use all one or the other.
418+
419+
:returns: CRGB list, can be used with palette_lookup() function.
420420
"""
421421

422-
grad = sorted(grad) # Sort list by position values
423-
least = grad[0][0] # Lowest position value (ostensibly 0.0)
424-
most = grad[-1][0] # Highest position value (ostensibly 1.0)
422+
gradient = sorted(gradient) # Sort list by position values
423+
least = gradient[0][0] # Lowest position value (ostensibly 0.0)
424+
most = gradient[-1][0] # Highest position value (ostensibly 1.0)
425425
newlist = []
426426

427427
for i in range(length):
@@ -436,20 +436,20 @@ def expand_gradient(grad, length):
436436
else:
437437
# Seek position between two items in list
438438
below, above = 0, -1
439-
for n, x in enumerate(grad):
439+
for n, x in enumerate(gradient):
440440
if pos >= x[0]:
441441
below = n
442-
for n, x in enumerate(grad[-1:0:-1]):
442+
for n, x in enumerate(gradient[-1:0:-1]):
443443
if pos <= x[0]:
444444
above = -1 - n
445445

446-
r = grad[above][0] - grad[below][0] # Range between below, above
446+
r = gradient[above][0] - gradient[below][0] # Range between below, above
447447
if r <= 0:
448-
newlist.append(grad[below][1]) # Use 'below' color only
448+
newlist.append(gradient[below][1]) # Use 'below' color only
449449
else:
450-
weight2 = (pos - grad[below][0]) / r # Weight of 'above' color
451-
color1 = grad[below][1]
452-
color2 = grad[above][1]
450+
weight2 = (pos - gradient[below][0]) / r # Weight of 'above' color
451+
color1 = gradient[below][1]
452+
color2 = gradient[above][1]
453453
# Interpolate and add to list
454454
newlist.append(mix(color1, color2, weight2))
455455

0 commit comments

Comments
 (0)