Colour Vision Models

Description

Colour vision models, colour spaces and colour thresholds. Provides flexibility to build user-defined colour vision models for n number of photoreceptor types. Includes Vorobyev & Osorio (1998) Receptor Noise Limited models <doi:10.1098/rspb.1998.0302>, Chittka (1992) colour hexagon <doi:10.1007/BF00199331>, and Endler & Mielke (2005) model <doi:10.1111/j.1095-8312.2005.00540.x>. Models have been extended to accept any number of photoreceptor types.

Details

The DESCRIPTION file:

Index of help topics:

CTTKhexagon             Chittka (1992) colour hexagon
CTTKhexagon3D           Chittka (1992) colour space for tetrachromatic
                        animals.
CTTKmodel               Chittka (1992) colour vision model
D65                     CIE Standard Illuminant D65 in quantum flux
                        (umol/m2/s)
EMline                  Endler and Mielke (2005) 1-D colour space
EMmodel                 Endler and Mielke (2005) colour vision model
EMtetrahedron           Endler and Mielke (2005) tetrahedron colour
                        space
EMtriangle              Endler and Mielke (2005) triangle colour space
GENmodel                N-dimensional generic colour vision model
GENplot                 Generic model colour space 2D and 1D plot
GENplot3d               Generic model colour space 3D plot
Q                       Total photon capture
Qr                      Photoreceptor relative quantum catch
RNLachrom               Weber achromatic contrast for the Receptor
                        Noise Limited Model (Vorobyev & Osorio 1998)
RNLmodel                Receptor Noise Limited Models (Vorobyev &
                        Osorio 1998)
RNLplot                 Receptor noise limited model 2D and 1D plot
RNLplot3d               Receptor noise limited model 3D plot
RNLthres                Colour thresholds based on the Receptor Noise
                        Limited Model (Vorobyev & Osorio 1998).
Rb                      Brazilian savannah background reflectance
                        spectrum.
bee                     Honeybee photoreceptors
colour_space            N-dimensional colour spaces
colourvision-package    Colour Vision Models
deltaS                  Chromaticity distances
energytoflux            Irradiance from energy to quantum units.
logistic                Logistic curve
noise_e                 Receptor noise
photor                  Photoreceptor sensitivity spectra.
plot.colourvision       Plot colour vision models into chromaticity
                        diagrams
plot3d.colourvision     Plot colour vision models into 3D chromaticity
                        diagrams.
radarplot               Radar plot
spec.denoise            Smooth function for reflectance spectra.

Author(s)

NA

Maintainer: NA

References

Gawryszewski, F.M. 2018. Colour vision models: Some simulations, a general n-dimensional model, and the colourvision R package. Ecology and Evolution, 10.1002/ece3.4288.

Examples

##Honeybee photoreceptor sensitivity curves
data("bee")

##Grey background:
## with 10 percent. reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(10, length(300:700)))

## Read CIE D65 standard illuminant already converted to quantum flux:
data("D65")

##Reflectance data
## with a sigmoid spectrum and midpoint at 500nm and 550 nm
R1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R2<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R<-cbind(R1, R2[,2])

## Run colour vision model:
model<-CTTKmodel(photo="tri", R=R, I=D65, Rb=Rb,
C=bee)

##plot data in the colour space
plot(model)

Chittka (1992) colour hexagon

Description

Plots Chittka (1992) colour hexagon for trichromatic animals and a line plot for dichromatic animals.

Usage

CTTKhexagon(x, y, photo=3,
            vnames=c(expression(E[1]),expression(E[2]),expression(E[3])),
            pch=16, bty="n", yaxt="n",xaxt="n", col="black",
            xlim="auto", ylim="auto", asp=1, ann=FALSE,
            axes=FALSE, vectors=FALSE, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Chittka, L. 1992. The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. J Comp Physiol A 170:533-543.

See Also

CTTKmodel, CTTKhexagon3D

Examples

##Honeybee photoreceptor sensitivity curves
data("bee")

##Grey background:
## with 7 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(7, length(300:700)))

## Read CIE D65 standard illuminant already converted to quantum flux:
data("D65")

##Reflectance data
## with a sigmoid spectrum and midpoint at 500nm and 550 nm
R1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R2<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R<-cbind(R1, R2[,2])

## Run colour vision model:
model<-CTTKmodel(photo="tri", R=R, I=D65, Rb=Rb,
C=bee)

##plot data in the colour space
CTTKhexagon(x=model[,"X1"], y=model[,"X2"])

Chittka (1992) colour space for tetrachromatic animals.

Description

Plots a hexagonal trapezohedron representing Chittka (1992) colour space for tetrachromatic animals (Thery and Casas, 2002).

Usage

CTTKhexagon3D(x, y, z, s.col = "red", f.col = "black",
              vnames = c("E1","E2","E3","E4"), type = "p",
              radius = 0.01, add = F, xlab = "", ylab = "", zlab = "",
              box = F, axes = F, ylim = c(-1, 1), xlim = c(-1, 1),
              zlim = c(-1,1), aspect = T, vectors=F, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Chittka, L. 1992. The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. J Comp Physiol A 170, 533-543.

Thery, M., and J. Casas. 2002. Predator and prey views of spider camouflage. Nature 415, 133-133.

See Also

CTTKmodel, CTTKhexagon

Chittka (1992) colour vision model

Description

Chittka (1992) colour hexagon extended to animals with any number of photoreceptors types.

Usage

CTTKmodel(photo=ncol(C)-1, R, I, Rb, C,
          interpolate=TRUE, nm=seq(300,700,1))

Arguments

Details

The original model is available for trichromatic animals only. Thery and Casas (2002) derived a version for tetrachromatic animals which is implemented here. In colourvision, this model was extended to any number of photoreceptors types (Gawryszewski 2018; see also Pike 2012). The colour hexagon in Chittka (1992) has a vector of length = 1.0 The chromaticity coordinates in colourvision preserve the same vector length.

Photoreceptor outputs (E_i) are calculated by:

E_i = \frac{q_i}{q_i+1}

where q_i is given by Qr.

Then, for trichromatic vision, coordinates in the colour space are found by (Chittka 1992):

X_1 = \frac{\sqrt{3}}{2}(E_3-E_1)

X_2 = E_2-\frac{1}{2}(E_1+E_3)

For tetrachromatic vision (Thery and Casas 2002):

X_1 = \frac{\sqrt{3}\sqrt{2}}{3}(E_3-E_4)

X_2 = E_1-\frac{1}{3}(E_2+E_3+E_4)

X_3 = \frac{2\sqrt{2}}{3}(\frac{1}{2}(E_3+E_4)-E_2)

For a pentachromatic animal following the same vector length:

X_1 = \frac{5}{2\sqrt{2}\sqrt{5}}(E_2-E_1)

X_2 = \frac{5\sqrt{2}}{2\sqrt{3}\sqrt{5}}(E_3-\frac{E_1+E_2}{2})

X_3 = \frac{5\sqrt{3}}{4\sqrt{5}}(E_4-\frac{E_1+E_2+E_3}{3})

X_4 = E_5-\frac{E1+E2+E3+E4}{4}

Value

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Chittka, L. 1992. The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. J Comp Physiol A 170:533-543.

Gawryszewski, F.M. 2018. Colour vision models: Some simulations, a general n-dimensional model, and the colourvision R package. Ecology and Evolution, 10.1002/ece3.4288.

Pike, T.W. 2012. Generalised chromaticity diagrams for animals with n-chromatic colour vision. Journal of Insect Behavior 255: 277-286.

Thery, M., and J. Casas. 2002. Predator and prey views of spider camouflage. Nature 415:133-133.

See Also

CTTKhexagon, CTTKhexagon3D, photor, RNLmodel, EMmodel, deltaS

Examples

##Photoreceptor sensitivity curves
##with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350,450,550))

## Grey background
## with 10 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(10, length(300:700)))

## Read CIE D65 standard illuminant
data("D65")

## Reflectance data
## with a sigmoid spectrum and midpoint at 500nm
R<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)

## Run model 
model<-CTTKmodel(photo=3, R=R, I=D65,
    Rb=Rb, C=C)
 
#plot   
plot(model)

CIE Standard Illuminant D65 in quantum flux (umol/m2/s)

Description

CIE Standard Illuminant D65. Datum has already been converted to quantum flux (umol/m2/s) and therefore can be used in colour vision models directly.

Usage

data("D65")

Format

A data frame with 107 observations on the following 2 variables.

l.nm

a numeric vector

Standard.Illuminant.D65

a numeric vector

Source

https://www.cie.co.at

Examples

data("D65")
plot(D65, type="l")

Endler and Mielke (2005) 1-D colour space

Description

Plots a colour space for dichromatic Endler and Mielke (2005) colour vision model.

Usage

EMline(x,y=rep(0, length(x)), type="length",
         vnames=c("E1","E2"), 
         ylim="auto", xlim="auto",
         ann=FALSE, axes = FALSE, ...)

Arguments

Details

The original model is available for tetrachromatic animals only. Colour space is built either with a vector length = 0.75 or a edge length = sqrt(3/2), to match the tetrahedron proposed by Endler and Mielke (2005).

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Endler, J. A., and P. Mielke. 2005. Comparing entire colour patterns as birds see them. Biol J Linn Soc 86:405-431.

See Also

EMtriangle, EMtetrahedron, EMmodel

Examples

EMline(x=0.1, pch=16, col="red")

Endler and Mielke (2005) colour vision model

Description

Endler and Mielke (2005) colour vision model extended to animals with any number of photoreceptor types.

Usage

EMmodel(photo = ncol(C)-1, type="length", R, I, Rb, C,
        interpolate=TRUE, nm=seq(300,700,1))

Arguments

Details

The original model is available for tetrachromatic animals only. In colourvision, the model was extended to any number of photoreceptors types (see also Pike 2012 formula).

First, relative quantum catches are log-transformed:

f_{i} = \ln{q_i}

where q_i is the relative quantum catch of photoreceptor type i, given by Qr. The model uses only relative output values, so that photoreceptor outputs are given by:

E_i = \frac{f_i}{\sum_{i=1}^n f_i}

For tetrachromatic vision (Endler and Mielke 2005):

X1 = \sqrt{\frac{3}{2}}(\frac{1-2E_2-E_3-E_1}{2})

X2 = \frac{-1+3E_3+E_1}{2\sqrt{2}}

X3 = E_1-\frac{1}{4}

Tetrachromatic chromaticity diagram (tetrahedron) in Endler and Mielke (2005) has a vector of length = 0.75 and and edge length = sqrt(3/2). The chromaticity coordinates for other colour spaces may preserve either the same vector length or edge length.

For instance, for dichromatic vision coordinate (X1) in the colour space preserving the same vector length is found by:

X1 = \frac{3}{4}(E_2-E_1)

Whereas for trichromatic vision coordinates (X1 and X2) are found by:

X1 = \frac{3\sqrt{3}}{8}(E_2-E_1)

X2 = \frac{3}{4}(E_3-\frac{E_2+E_1}{2})

Value

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Endler, J. A., and P. Mielke. 2005. Comparing entire colour patterns as birds see them. Biol J Linn Soc 86:405-431.

Pike, T.W. 2012. Generalised chromaticity diagrams for animals with n-chromatic colour vision. Journal of Insect Behavior 255: 277-286.

See Also

EMline, EMtriangle, EMtetrahedron, photor, CTTKmodel, RNLmodel, GENmodel

Examples

##Photoreceptor sensitivity curves
##with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350,450,550))

##Gray background
##with 7 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(7, length(300:700)))

## Read CIE D65 standard illuminant
data("D65")

##Reflectance data
## with a sigmoid spectrum and midpoint at 500nm and 550 nm
R1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R2<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R<-cbind(R1, R2[,2])
R[,2]<-R[,2]+10
R[,3]<-R[,3]+10

## Run model 
model<-EMmodel(photo=3, type="edge",
       R=R, I=D65, Rb=Rb, C=C)

plot(model)

Endler and Mielke (2005) tetrahedron colour space

Description

Plots Endler and Mielke (2005) tetrahedron colour space for tetrachromatic animals.

Usage

EMtetrahedron(x, y, z, s.col = "red", f.col = "black",
              vnames = c("u","s","m","l"), type = "p",
              radius = 0.01, add = F, xlab = "",
              ylab = "", zlab = "", box = F, axes = F,
              ylim = c(-0.75, 0.75), xlim = c(-0.75, 0.75),
              zlim = c(-0.75, 0.75), aspect = T, vectors=FALSE, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Endler, J. A., and P. Mielke. 2005. Comparing entire colour patterns as birds see them. Biol J Linn Soc 86:405-431.

See Also

EMtriangle, EMmodel

Endler and Mielke (2005) triangle colour space

Description

Plots a triangle colour space for trichromatic Endler and Mielke (2005) colour vision model.

Usage

EMtriangle(x, y, type=c("length", "edge"), vnames=c("u","s","m"),
           ylim=c(-0.9,0.9), xlim=c(-0.9,0.9),
           pch=16, bty="n",yaxt="n",xaxt="n",
           col="black", asp=1, ann=FALSE, vectors=FALSE, ...)

Arguments

Details

The original model is available for tetrachromatic animals only. Trichromatic version is implemented in colourvision based on Pike (2012) formula. The triangle is built either with a vector length = 0.75 or a edge length = sqrt(3/2), to match the tetrahedron proposed by Endler and Mielke (2005). Doris Gomez derived a trichromatic version which is available in software AVICOL (Gomez, 2006) and was previously implemented here (colouvision v0.1).

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Endler, J. A., and P. Mielke. 2005. Comparing entire colour patterns as birds see them. Biol J Linn Soc 86:405-431.

Pike, T.W. 2012. Generalised chromaticity diagrams for animals with n-chromatic colour vision. Journal of Insect Behavior 255: 277-286.

Gomez, D. 2006. AVICOL, a program to analyse spectrometric data. Last update october 2011. Free executable available at:
http://sites.google.com/site/avicolprogram/ or from the author at dodogomez@yahoo.fr

See Also

EMtetrahedron, EMmodel

Examples

EMtriangle(x=0,y=0, type="length", pch=16, col="red")

N-dimensional generic colour vision model

Description

A flexible function to build colour vision models based on any number of photoreceptor types (Gawryszewski 2018).

Usage

GENmodel(photo=ncol(C)-1, type="length", length=NA, edge=NA,
          R, I, Rb=NA, C, vonKries = TRUE, func, unity=FALSE,
          recep.noise=FALSE, noise.given=TRUE, e=NA, v=NA, n=NA,
          interpolate=TRUE, nm=seq(300,700,1))

Arguments

Value

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Gawryszewski, F.M. 2018. Colour vision models: Some simulations, a general n-dimensional model, and the colourvision R package. Ecology and Evolution, 10.1002/ece3.4288.

Pike, T.W. 2012. Generalised chromaticity diagrams for animals with n-chromatic colour vision. Journal of Insect Behavior 255: 277-286.

Renoult, J. P., A. Kelber, and H. M. Schaefer. 2015. Colour spaces in ecology and evolutionary biology. Biol Rev Camb Philos Soc, doi: 10.1111/brv.12230.

See Also

Q, Qr, CTTKmodel, EMmodel, RNLmodel, colour_space

Examples

#A trichromatic colour vision model based on Endler and Mielke (2005)

##Photoreceptor sensitivity curves
##with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350,450,550))

##Gray background
##with 7 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(7, length(300:700)))

## Read CIE D65 standard illuminant
data("D65")

##Reflectance data
## with a sigmoid spectrum and midpoint at 500nm and 550 nm
R1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R2<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R<-cbind(R1, R2[,2])
R[,2]<-R[,2]+10
R[,3]<-R[,3]+10

## Run model 
model<-GENmodel(length=0.75, R=R, I=D65, Rb=Rb, C=C, 
                func=log, unity=TRUE)

plot(model)

Generic model colour space 2D and 1D plot

Description

Plots models based on the GENmodel( ) function for trichromatic and dichromatic animals.

Usage

GENplot(model, photo, col.names=c("X1","X2"),
        vectors=TRUE, vnames=TRUE, vsize="auto",
        ylab="y", xlab="x", xlim="auto", ylim="auto", asp=1, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

See Also

CTTKhexagon, CTTKhexagon3D, EMtriangle, EMtetrahedron, RNLplot, RNLplot3d, GENplot3d, plot.colourvision, plot3d.colourvision

Generic model colour space 3D plot

Description

Plots models based on the GENmodel( ) function for tetrachromatic animals.

Usage

GENplot3d(model, col.names=c("X1","X2","X3"),
          vectors=TRUE, vnames=TRUE, vsize="auto",
          xlab="x", ylab="y", zlab="z",
          xlim="auto", ylim="auto", zlim="auto", asp=1, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

See Also

CTTKhexagon, CTTKhexagon3D, EMtriangle, EMtetrahedron, RNLplot, RNLplot3d, GENplot, plot.colourvision, plot3d.colourvision

Total photon capture

Description

Total photoreceptor photon capture for a given irradiance, reflectance and photoreceptor sensitivity curve. This function is used internally in colour vision models.

Usage

Q(R,I,C,interpolate,nm)

Arguments

Value

Gives the total photoreceptor photon capture.

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Backhaus, W., and R. Menzel. 1987. Color distance derived from a receptor model of color vision in the honeybee. Biological Cybernetics 55:321-331.

Chittka, L. 1992. The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. J Comp Physiol A 170:533-543.

Endler, J. A., and P. Mielke. 2005. Comparing entire colour patterns as birds see them. Biol J Linn Soc 86:405-431.

Vorobyev, M., and D. Osorio. 1998. Receptor noise as a determinant of colour thresholds. Proceedings of the Royal Society B 265:351-358.

See Also

Qr, CTTKmodel, EMmodel, RNLmodel, RNLthres,GENmodel

Photoreceptor relative quantum catch

Description

von Kries transformation. Photoreceptors are assumed to be adapted to the background. This function is used internally in colour vision models.

Usage

Qr(R, I, Rb, C, interpolate, nm)

Arguments

Details

For the von Kries transformation, first the quantum catches of the observed reflectance and the environmental background are calculated (see Q). Then:

qi = \frac{Q_i}{Q_{bi}}

where Q_i is the quantum catch arising from the observed object and Q_{bi} is the quantum catch from the background, for each one of the photoreceptor types (i).

Value

Photoreceptor relative quantum catch.

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Backhaus, W. 1991. Color opponent coding in the visual system of the honeybee. Vision Res 31:1381-1397.

Chittka, L. 1992. The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. J Comp Physiol A 170:533-543.

Endler, J. A., and P. Mielke. 2005. Comparing entire colour patterns as birds see them. Biol J Linn Soc 86:405-431.

Vorobyev, M., and D. Osorio. 1998. Receptor noise as a determinant of colour thresholds. Proceedings of the Royal Society B 265:351-358.

See Also

CTTKmodel, EMmodel, RNLmodel, RNLthres, GENmodel

Weber achromatic contrast for the Receptor Noise Limited Model (Vorobyev & Osorio 1998)

Description

Weber achromatic contrast for the Receptor noise limited model (Vorobyev & Osorio 1998; Vorobyev et al. 1998).

Usage

RNLachrom(R1, R2=Rb, Rb, I, C, e,
         interpolate = TRUE, nm = seq(300, 700, 1))

Arguments

Details

The Weber achromatic contrast for a single photoreceptor is calculated by:

\Delta S = |\frac{\ln(Qr_1)-\ln(Qr_2)}{e}|

where Qr_1 and Qr_2 are the relative photoreceptor quantum catches from stimulus 1 (R1) and stimulus 2 (R2).

Noise may be dependent of the intensity, but this possibility is not implement in colourvision yet. Noise dependent of intensity usually holds for low light conditions only (Vorobyev et al. 1998).

Value

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Vorobyev, M., and D. Osorio. 1998. Receptor noise as a determinant of colour thresholds. Proceedings of the Royal Society B 265:351-358.

Vorobyev, M., D. Osorio, A. T. D. Bennett, N. J. Marshall, and I. C. Cuthill. 1998. Tetrachromacy, oil droplets and bird plumage colours. J Comp Physiol A 183:621-633.

See Also

RNLmodel, photor, RNLthres, CTTKmodel, EMmodel, GENmodel

Examples

#1
## Photoreceptor sensitivity spectra
##with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350))

##Grey background
##with 7 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(7, length(300:700)))

## Read CIE D65 standard illuminant:
data("D65")

##Reflectance data of R1 and R2
R1.1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R1.2<-logistic(x=seq(300,700,1), x0=400, L=50, k=0.04)
w<-R1.1[,1]
R1.1<-R1.1[,2]+10
R1.2<-R1.2[,2]+10
R1<-data.frame(w=w, R1.1=R1.1, R1.2=R1.2)

R2<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R2[,2]<-R2[,2]+10

plot(R1[,c(1,2)],type="l",
     ylim=c(0,60))
lines(R1[,c(1,3)])
lines(R2[,c(1,2)],col="red")
lines(Rb,col="green")

## Run model 
RNLachrom(R1=R1, R2=R2, Rb=Rb, I=D65, C=C,
          e = 0.16)

Receptor Noise Limited Models (Vorobyev & Osorio 1998)

Description

Receptor noise limited colour vision models (Vorobyev & Osorio 1998; Vorobyev et al. 1998) extended to any number of photoreceptor types.

Usage

RNLmodel(model = c("linear", "log"), photo=ncol(C)-1,
         R1, R2=Rb, Rb, I, C,
         noise = FALSE, v=NA, n=NA, e=NA,
         interpolate = TRUE, nm = seq(300, 700, 1),
         coord="colourvision")

Arguments

Details

The receptor noise limited model was originally developed to calculate \Delta S between two reflectance curves directly, without finding colour locus coordinates (e.g. x,y; Vorobyev and Osorio 1998). This function uses later formulae to find colour loci in a chromaticity diagram (similarly to Hempel de Ibarra et al. 2001; Renoult et al. 2015).

In lack of a direct measurement, receptor noise (e_i) can be estimated by the relative abundance of photoreceptor types in the retina, and a measurement of a single photoreceptor noise-to-signal ratio:

e_i=\frac{\nu}{\sqrt{\eta _i}}

where \nu is the noise-to-signal ratio of a single photoreceptor, and \eta is the relative abundance of photoreceptor i in the retina. Alternatively, noise may be dependent of the intensity, but this possibility is not implement in colourvision yet. Noise dependent of intensity usually holds for low light conditions only (Vorobyev et al. 1998).

Value

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Gawryszewski, F.M. 2018. Colour vision models: Some simulations, a general n-dimensional model, and the colourvision R package. Ecology and Evolution, 10.1002/ece3.4288.

Hempel de Ibarra, N., M. Giurfa, and M. Vorobyev. 2001. Detection of coloured patterns by honeybees through chromatic and achromatic cues. J Comp Physiol A 187:215-224.

Renoult, J. P., A. Kelber, and H. M. Schaefer. 2017. Colour spaces in ecology and evolutionary biology. Biol Rev Camb Philos Soc, doi: 10.1111/brv.12230

Vorobyev, M., and D. Osorio. 1998. Receptor noise as a determinant of colour thresholds. Proceedings of the Royal Society B 265:351-358.

Vorobyev, M., D. Osorio, A. T. D. Bennett, N. J. Marshall, and I. C. Cuthill. 1998. Tetrachromacy, oil droplets and bird plumage colours. J Comp Physiol A 183:621-633.

See Also

RNLachrom, photor, RNLthres, CTTKmodel, EMmodel, GENmodel

Examples

#1
## Photoreceptor sensitivity spectra
##with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350,450,550))

##Grey background
##with 7 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(7, length(300:700)))

## Read CIE D65 standard illuminant:
data("D65")

##Reflectance data of R1 and R2
R1.1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R1.2<-logistic(x=seq(300,700,1), x0=400, L=50, k=0.04)
w<-R1.1[,1]
R1.1<-R1.1[,2]+10
R1.2<-R1.2[,2]+10
R1<-data.frame(w=w, R1.1=R1.1, R1.2=R1.2)

R2<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R2[,2]<-R2[,2]+10

## Run model 
model<-RNLmodel(photo=3, model="log",
       R1=R1, R2=R2, Rb=Rb, I=D65, C=C,
       noise=TRUE, e = c(0.13, 0.06, 0.12))
       
#plot       
plot(model)

#2
#Pentachromatic animal
## Photoreceptor sensitivity spectra
##with lambda max at 350,400,450,500,and 550nm:
C<-photor(lambda.max=c(350,400,450,500,550))

##Grey background
##with 7 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(7, length(300:700)))

## Read CIE D65 standard illuminant:
data("D65")

##Reflectance data of R1
R1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R1[,2]<-R1[,2]+10

#RNL model
RNLmodel(photo=5, model="log",
       R1=R1, R2=Rb, Rb=Rb, I=D65, C=C,
       noise=TRUE, e = c(0.13, 0.06, 0.12, 0.07, 0.08))

#3
## Photoreceptor sensitivity spectra
##with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350,450,550))

##Grey background
##with 7 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(7, length(300:700)))

## Read CIE D65 standard illuminant:
data("D65")

##Reflectance data of R1 and R2
R1.1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R1.2<-logistic(x=seq(300,700,1), x0=400, L=50, k=0.04)
w<-R1.1[,1]
R1.1<-R1.1[,2]+10
R1.2<-R1.2[,2]+10
R1<-data.frame(w=w, R1.1=R1.1, R1.2=R1.2)

R2<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R2[,2]<-R2[,2]+10

## Run model 
model<-RNLmodel(photo=3, model="log",
       R1=R1, R2=R2, Rb=Rb, I=D65, C=C,
       noise=FALSE, v = c(NA, 0.06, NA),
       n = c(1,2,2))

Receptor noise limited model 2D and 1D plot

Description

Plots receptor noise limited model (RNL) for trichromatic and dichromatic animals.

Usage

RNLplot(model, photo, item="R1",
        vectors=TRUE, vnames=TRUE, vsize="auto",
        xlab="x", ylab="y", xlim="auto", ylim="auto", asp=1, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

See Also

CTTKhexagon, CTTKhexagon3D, EMtriangle, EMtetrahedron, RNLplot3d, plot.colourvision, plot3d.colourvision

Examples

#dichromat
C<-photor(lambda.max=c(450,550))
Rb <- data.frame(300:700, rep(7, length(300:700)))
data("D65")
R1.1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R1.2<-logistic(x=seq(300,700,1), x0=400, L=50, k=0.04)
w<-R1.1[,1]
R1.1<-R1.1[,2]+10
R1.2<-R1.2[,2]+10
R1<-data.frame(w=w, R1.1=R1.1, R1.2=R1.2)
model<-RNLmodel(model="log",
       R1=R1, Rb=Rb, I=D65, C=C,
       noise=TRUE, e = c(0.13, 0.06))
plot(model)

#trichromat
C<-photor(lambda.max=c(350,450,550))
Rb <- data.frame(300:700, rep(7, length(300:700)))
data("D65")
R1.1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R1.2<-logistic(x=seq(300,700,1), x0=400, L=50, k=0.04)
w<-R1.1[,1]
R1.1<-R1.1[,2]+10
R1.2<-R1.2[,2]+10
R1<-data.frame(w=w, R1.1=R1.1, R1.2=R1.2)
model<-RNLmodel(model="log",
       R1=R1, Rb=Rb, I=D65, C=C,
       noise=TRUE, e = c(0.13, 0.06, 0.12))
plot(model)

Receptor noise limited model 3D plot

Description

Plots receptor noise limited model (RNL) for tetrachromatic animals.

Usage

RNLplot3d(model, item="R1",
          vectors=TRUE, vnames=TRUE, vsize="auto",
          xlab="x", ylab="y", zlab="z",
          xlim="auto", ylim="auto", zlim="auto", asp=1, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

See Also

CTTKhexagon, CTTKhexagon3D, EMtriangle, EMtetrahedron, RNLplot, plot.colourvision, plot3d.colourvision

Colour thresholds based on the Receptor Noise Limited Model (Vorobyev & Osorio 1998).

Description

Colour thresholds based on receptor noise for any number of photoreceptor types (Vorobyev & Osorio 1998).

Usage

RNLthres(photo=ncol(C)-1, Rb, I, C, noise=TRUE, v=NA, n=NA, e=NA,
         interpolate=TRUE, nm=seq(300,700,1))

Arguments

Details

Colour thresholds based on receptor noise limited model as in Vorobyev and Osorio (1998). In lack of a direct measurement, receptor noise (e_i) can be estimated by the relative abundance of photoreceptor types in the retina, and a measurement of a single photoreceptor noise-to-signal ratio:

e_i=\frac{\nu}{\sqrt{\eta _i}}

where \nu is the noise-to-signal ratio of a single photoreceptor, and \eta is the relative abundance of photoreceptor i in the retina. Alternatively, noise may be dependent of the intensity, but this possibility is not implement in colourvision yet. Noise dependent of intensity usually holds for low light conditions only (Vorobyev et al. 1998).

Value

A data.frame with the following columns:

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Vorobyev, M., and D. Osorio. 1998. Receptor noise as a determinant of colour thresholds. Proceedings of the Royal Society B 265:351-358.

See Also

photor, RNLmodel

Examples

###Bee photoreceptors normalized to max=1.
data("bee")
C<-bee
C[,2]<-C[,2]/max(C[,2])
C[,3]<-C[,3]/max(C[,3])
C[,4]<-C[,4]/max(C[,4])

##Grey background:
Rb <- data.frame(300:700, rep(0.1, length(300:700)))

## CIE D65 illuminant:
data("D65")

#Thresholds
thres<-RNLthres(photo=3, Rb=Rb, I=D65, C=C,
       noise=TRUE, e = c(0.13, 0.06, 0.12))

plot(thres)     

Brazilian savannah background reflectance spectrum.

Description

Brazilian savannah background reflectance spectrum calculated by the average reflectance of leaf, leaf litter, tree bark and twigs.

Usage

data("Rb")

Format

A data frame with 401 observations on the following 2 variables.

X300.700

a numeric vector

cerrado

a numeric vector

Source

Gawryszewski, F. M., and P. C. Motta. 2012. Colouration of the orb-web spider Gasteracantha cancriformis does not increase its foraging success. Ethol Ecol Evol 24:23-38.

Honeybee photoreceptors

Description

Honeybee (Apis mellifera) photoreceptor sensitivity curves.

Usage

data("bee")

Format

A data frame with 401 observations on the following 4 variables.

Wavelength

a numeric vector

UV

a numeric vector

Blue

a numeric vector

Green

a numeric vector

Details

Original data were interpolated to 1nm intervals from 300 to 700nm.

Source

Chittka, L., and P. Kevan. 2005. Flower colour as advertisement. Pp. 157-196 in Practical pollination biology.

Examples

data("bee")
plot(bee[,2]~bee[,1], col = "violet", type="l", xlab="Wavelength(nm)", ylab= "Absorbance")
lines(bee[,3]~bee[,1], col = "blue", type="l")
lines(bee[,4]~bee[,1], col = "green", type="l")

N-dimensional colour spaces

Description

Generates a colour space based on any number of photoreceptor types and finds a colour locus for a given photoreceptor output.

Usage

colour_space(n, type="length", length=NA, edge=NA,
          q=rep(1,n), recep.noise=FALSE, e=NA)

Arguments

Details

This function is used internally in colour vision models.

Value

A list with the following dimensions:

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Pike, T.W. 2012. Generalised chromaticity diagrams for animals with n-chromatic colour vision. Journal of Insect Behavior 255: 277-286.

Renoult, J. P., A. Kelber, and H. M. Schaefer. 2015. Colour spaces in ecology and evolutionary biology. Biol Rev Camb Philos Soc, doi: 10.1111/brv.12230.

See Also

Q, Qr, CTTKmodel, EMmodel, RNLmodel, GENmodel

Examples

#A trichromatic colour space based on Endler and Mielke (2005) 
tri<-colour_space(n=3, length=0.75, q=c(0.5,0.2,0.3))

#showing:
#(1) Limits of the colour space (triangle)
plot(0, ylim=c(-1,1), xlim=c(-1,1), asp=1, ylab="X2", xlab="X1", type="n")
polygon(x=tri$vector_matrix[1,], y=tri$vector_matrix[2,], lty=2)

#(2) Vectors (length=0.75) used to build the colour space (arrows)
arrows(x0=0,y0=0, x1=tri$vector_matrix[1,1], y1=tri$vector_matrix[2,1], col="red")
arrows(x0=0,y0=0, x1=tri$vector_matrix[1,2], y1=tri$vector_matrix[2,2], col="red")
arrows(x0=0,y0=0, x1=tri$vector_matrix[1,3], y1=tri$vector_matrix[2,3], col="red")

#(3) Colour loci of given photoreceptor outputs
points(x=tri$coordinates[[1]], y=tri$coordinates[[2]], pch=21, col="blue", bg="blue")

Chromaticity distances

Description

Calculates a matrix with all possible pairwise comparison between stimulus reflectance spectra based on a given colour vision model output.

Usage

deltaS(model)

Arguments

.

Value

A matrix with pairwise chromaticity distances.

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

See Also

CTTKmodel, RNLmodel, EMmodel,GENmodel

Examples

##Photoreceptor sensitivity curves
##with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350,450,550))

## Grey background
## with 10 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(10, length(300:700)))

## Read CIE D65 standard illuminant
data("D65")

## Reflectance data
## with a sigmoid spectrum and midpoint at 500nm
R1<-logistic(x=seq(300,700,1), x0=450, L=50, k=0.04)
R2<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R3<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R<-cbind(R1,R2[,2],R3[,2])

## Run model 
model<-CTTKmodel(photo=3, R=R, I=D65,
    Rb=Rb, C=C)

#Chromaticity distances between R1, R2 and R3
deltaS(model)

Irradiance from energy to quantum units.

Description

Convert Irradiance datum from energy units (uW/cm2/nm) to quantum flux units (umol/m2/s)

Usage

energytoflux(datum)

Arguments

Value

A data frame with first column corresponding to wavelength values and second column with irradiance values in umol/m2/s.

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

Logistic curve

Description

Generates a logistic curve.

Usage

logistic(x = seq(300, 700, 1), x0, L, k)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

https://en.wikipedia.org/wiki/Logistic_function

Examples

l<-logistic(x=seq(300,700,1), x0=650, L=50, k=0.04)
plot(l, type="l")

Receptor noise

Description

Receptor noise either provided by the user or based on noise-to-signal ratio of a single photoreceptor and the relative abundance of photoreceptor types in the retina. This function is used internally in Receptor Noise Limited models.

Usage

noise_e(noise, e, v, n)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Vorobyev, M., and D. Osorio. 1998. Receptor noise as a determinant of colour thresholds. Proceedings of the Royal Society B 265:351-358.

See Also

RNLmodel, RNLthres, GENmodel, colour_space

Photoreceptor sensitivity spectra.

Description

Generates photoreceptor sensitivity spectra based on lambda-max values.

Usage

photor(lambda.max, lambda = seq(300, 700, 1), beta.band = FALSE)

Arguments

Value

A data frame with first column corresponding to wavelength values and following columns with photoreceptor sensitivity values

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Govardovskii, V. I., N. Fyhrquist, T. Reuter, D. G. Kuzmin, and K. Donner. 2000. In search of the visual pigment template. Vis. Neurosci. 17:509-528.

See Also

CTTKmodel, EMmodel, RNLmodel, RNLthres

Examples

## Generates photoreceptor sensitivity
## values with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350,450,550))

plot(C[,2]~C[,1], type="l", col="violet")
lines(C[,3]~C[,1], type="l", col="blue")
lines(C[,4]~C[,1], type="l", col="green")

Plot colour vision models into chromaticity diagrams

Description

Plotting method for objects of class colourvision. Plotting method for animals with two or three photoreceptor types.

Usage

## S3 method for class 'colourvision'
plot(x, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Chittka, L. 1992. The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. J Comp Physiol A 170:533-543.

Endler, J. A., and P. Mielke. 2005. Comparing entire colour patterns as birds see them. Biol J Linn Soc 86:405-431.

See Also

plot3d.colourvision, EMtriangle, CTTKhexagon, EMmodel, CTTKmodel, RNLmodel, RNLthres

Examples

#trichromatic
##Photoreceptor sensitivity curves
C<-photor(lambda.max=c(350,450,550))

##Gray background
Rb <- data.frame(300:700, rep(7, length(300:700)))

## Read CIE D65 standard illuminant
data("D65")

##Reflectance data
R1<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R1[,2]<-R1[,2]+10

##Run models
model<-EMmodel(photo=3,
       R=R1, I=D65, Rb=Rb, C=C)
plot(model)

model<-CTTKmodel(photo=3,
       R=R1, I=D65, Rb=Rb, C=C)
plot(model)

model<-RNLmodel(model="log", photo=3,
       R1=R1, I=D65, Rb=Rb, C=C, noise=TRUE, e=c(0.13, 0.06, 0.12))
plot(model)

#colour threshold
model<-RNLthres(photo=3, I=D65, Rb=Rb, C=C,
         noise=TRUE, e=c(0.13, 0.06, 0.12))
plot(model)

#dichromatic
##Photoreceptor sensitivity curves
C<-photor(lambda.max=c(400,550))

##Run models
model<-EMmodel(photo=2,
       R=R1, I=D65, Rb=Rb, C=C)
plot(model)

model<-EMmodel(photo=2, type="edge",
       R=R1, I=D65, Rb=Rb, C=C)
plot(model)

model<-CTTKmodel(photo=2,
       R=R1, I=D65, Rb=Rb, C=C)
plot(model)

model<-RNLmodel(model="log", photo=2,
       R1=R1, I=D65, Rb=Rb, C=C, noise=TRUE, e=c(0.13, 0.06))
plot(model)

#colour threshold
model<-RNLthres(photo=2, I=D65, Rb=Rb, C=C,
         noise=TRUE, e=c(0.13, 0.06))
plot(model)

Plot colour vision models into 3D chromaticity diagrams.

Description

'plot3d' method for objects of class colourvision. Plotting method for animals with four photoreceptor types.

Usage

## S3 method for class 'colourvision'
plot3d(x, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

References

Chittka, L. 1992. The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. J Comp Physiol A 170:533-543.

Endler, J. A., and P. Mielke. 2005. Comparing entire colour patterns as birds see them. Biol J Linn Soc 86:405-431.

Thery, M., and J. Casas. 2002. Predator and prey views of spider camouflage. Nature 415:133-133.

See Also

plot.colourvision, EMtetrahedron, CTTKhexagon3D, EMmodel, CTTKmodel, RNLmodel

Radar plot

Description

Plots quantum catches or E-values (photoreceptor outputs) into a radar plot.

Usage

radarplot(model, item=c("Qr", "E"), item.labels=FALSE, item.lwd=1,
           border=NULL, radar.lwd=1, radar.col="grey",
           length="auto", xlim="auto", ylim="auto",
           xlab="", ylab="", asp=1, add = FALSE, ...)

Arguments

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com

Examples

##Photoreceptor sensitivity curves
##with lambda max at 350nm, 450nm and 550nm:
C<-photor(lambda.max=c(350,450,550))

## Grey background
## with 10 percent reflectance from 300 to 700nm:
Rb <- data.frame(300:700, rep(10, length(300:700)))

## Read CIE D65 standard illuminant
data("D65")

## Reflectance data
## with a sigmoid spectrum and midpoint at 500nm
R1<-logistic(x=seq(300,700,1), x0=450, L=50, k=0.04)
R2<-logistic(x=seq(300,700,1), x0=500, L=50, k=0.04)
R3<-logistic(x=seq(300,700,1), x0=550, L=50, k=0.04)
R<-cbind(R1,R2[,2],R3[,2])

## Run model 
model<-CTTKmodel(photo=3, R=R, I=D65,
    Rb=Rb, C=C)

#Radarplot
radarplot(model, border=c("violet", "red", "blue"), item="E", item.labels=TRUE)

Smooth function for reflectance spectra.

Description

Applies a smooth.spline for data frame containing spectrometric data.

Usage

spec.denoise(specfiles, spar = 0.7, ...)

Arguments

Value

A data frame with first column representing wavelength values and following columns with reflectance data.

Author(s)

Felipe M. Gawryszewski f.gawry@gmail.com