--- ray/doc/man/man1/pcomb.1	2003/10/21 15:08:19	1.3
+++ ray/doc/man/man1/pcomb.1	2023/12/11 01:00:27	1.16
@@ -1,12 +1,16 @@
-.\" RCSid "$Id"
+.\" RCSid "$Id: pcomb.1,v 1.16 2023/12/11 01:00:27 greg Exp $"
 .TH PCOMB 1 8/31/96 RADIANCE
 .SH NAME
-pcomb - combine RADIANCE pictures
+pcomb - combine RADIANCE pictures and/or float matrices
 .SH SYNOPSIS
 .B pcomb
 [
+.B -h
+][
 .B -w
 ][
+.B -ff
+][
 .B "\-x xres"
 ][
 .B "\-y yres"
@@ -27,10 +31,10 @@ pcomb - combine RADIANCE pictures
 ]
 .SH DESCRIPTION
 .I Pcomb
-combines equal-sized RADIANCE pictures and sends the result to the
-standard output.
+combines equal-sized RADIANCE pictures or raw float matrices
+and sends the result to the standard output.
 By default, the result is just a linear combination of
-the input pictures multiplied by
+the input pixels multiplied by
 .I \-s
 and
 .I \-c
@@ -39,10 +43,18 @@ but an arbitrary mapping can be assigned with the
 .I \-e
 and
 .I \-f
-options.
+options, similar to
+.I rcalc(1).
+(The variable and function definitions in each
+.I \-f source
+file are read and compiled from the RADIANCE library
+where it is found.)\0
 Negative coefficients and functions are allowed, and
 .I pcomb
-will produce color values of zero where they would be negative.
+will produce color values of zero where they would be negative
+unless the
+.I \-ff
+option is used to specify floating-point matrix output.
 .PP
 The variables
 .I ro,
@@ -58,17 +70,17 @@ The predefined functions
 .I gi(n)
 and
 .I bi(n)
-give the red, green and blue input values for
-picture
+give the red, green and blue values for
+input
 .I n.
 To access a pixel that is nearby the current one, these functions
 also accept optional x and y offsets.
 For example,
 .I ri(3,-2,1)
-would return the red component of the pixel from picture 3
+would return the red component of the pixel from input 3
 that is left 2 and up 1 from the current position.
-Although x offsets may be as large as width of the picture,
-y offsets are limited to a small window (+/- 8 pixels) due to efficiency
+Although x offsets may be as large as width of the input,
+y offsets are limited to a small window (+/- 32 pixels) due to efficiency
 considerations.
 However, it is not usually necessary to worry about this problem --
 if the requested offset is not available, the next best pixel is
@@ -76,7 +88,7 @@ returned instead.
 .PP
 For additional convenience, the function
 .I li(n)
-is defined as the input brightness for picture
+is defined as the input brightness for input
 .I n.
 This function also accepts x and y offsets.
 .PP
@@ -108,18 +120,21 @@ The constant functions
 .I "re(n), ge(n), be(n),"
 and
 .I le(n)
-give the exposure values for picture
+give the exposure values for input
 .I n,
 and
 .I pa(n)
 gives the corresponding pixel aspect ratio.
-Finally, for pictures with stored view parameters,
+Exposure values will be set to 1.0 for inputs with the
+.I \-o
+option set.
+Finally, for inputs with stored view parameters,
 the functions
 .I "Ox(n), Oy(n)"
 and
 .I Oz(n)
 return the ray origin in world coordinates for the current pixel
-in picture
+in input
 .I n,
 and
 .I "Dx(n), Dy(n)"
@@ -138,15 +153,24 @@ If the current pixel is outside the view region,
 will return a negative value, and
 .I S(n)
 will return zero.
+The first input input with a view is assumed to correspond to the
+view of the output, which is written into the header.
 .PP
 The
+.I \-h
+option may be used to reduce the information header size, which
+can grow disproportionately after multiple runs of
+.I pcomb
+and/or
+.I pcompos(1).
+The
 .I \-w
 option can be used to suppress warning messages about invalid
 calculations.
 The
 .I \-o
 option indicates that original pixel values are to be used for the next
-picture, undoing any previous exposure changes or color correction.
+input, undoing any previous exposure changes or color correction.
 .PP
 The
 .I \-x
@@ -178,35 +202,48 @@ the definitions of
 and
 .I bo
 will be used to compute each output pixel.
-This is useful for producing simple test pictures for various
+This is useful for producing simple test inputs for various
 purposes.
 (Theoretically, one could write a complete renderer using just the
 functional language...)
 .PP
 The standard input can be specified with a hyphen ('-').
-A command that produces a RADIANCE picture can be given in place of a file 
+A command that produces a RADIANCE picture or float matrix
+can be given in place of a file 
 by preceeding it with an exclamation point ('!').
 .SH EXAMPLES
 To produce a picture showing the difference between pic1 and pic2:
 .IP "" .2i
-pcomb -e 'ro=ri(1)-ri(2);go=gi(1)-gi(2);bo=bi(1)-bi(2)' pic1 pic2 > diff
+pcomb \-e 'ro=ri(1)\-ri(2);go=gi(1)\-gi(2);bo=bi(1)\-bi(2)' pic1 pic2 > diff
 .PP
 Or, more efficiently:
 .IP "" .2i
-pcomb pic1 -s -1 pic2 > diff
+pcomb pic1 \-s \-1 pic2 > diff
 .PP
 To precompute the gamma correction for a picture:
 .IP "" .2i
-pcomb -e 'ro=ri(1)^.4;go=gi(1)^.4;bo=bi(1)^.4' pic > pic.gam
+pcomb \-e 'ro=ri(1)^.4;go=gi(1)^.4;bo=bi(1)^.4' inp.hdr > gam.hdr
 .PP
 To perform some special filtering:
 .IP "" .2i
-pcomb -f myfilt.cal -x xmax/2 -y ymax/2 input.pic > filtered.pic
+pcomb \-f myfilt.cal \-x xmax/2 \-y ymax/2 input.hdr > filtered.hdr
 .PP
 To make a picture of a dot:
 .IP "" .2i
-pcomb -x 100 -y 100 -e 'ro=b;go=b;bo=b;b=if((x-50)^2+(y-50)^2-25^2,0,1)' > dot
+pcomb \-x 100 \-y 100 \-e 'ro=b;go=b;bo=b;b=if((x-50)^2+(y-50)^2\-25^2,0,1)' > dot
+.PP
+Use a depth buffer to superimpose 3-D gridlines on rendered image:
+.IP "" .2i
+rcollate -hi -ff -o 3000x3000 raw_orig.zbf
+| pcomb -e 't=gi(2);Px=Ox(1)+t*Dx(1);Py=Oy(1)+t*Dy(1);Pz=Oz(1)+t*Dz(1)'
+-e 'frac(x):x-floor(x)' -e 'Rg:0;Gg:0;Bg:1;gsiz:0.04' 
+-e 'ingr=gsiz-min(frac(Px),frac(Py),frac(Pz))' 
+-e 'ro=if(ingr,Rg,ri(1));go=if(ingr,Gg,gi(1));bo=if(ingr,Bg,bi(1))'
+raw_orig.hdr - > trans_def_grid.hdr
+.SH ENVIRONMENT
+RAYPATH		the directories to check for auxiliary files.
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"
-calc(1), getinfo(1), pcompos(1), pfilt(1), rpict(1)
+getinfo(1), icalc(1), pcompos(1), pfilt(1), rcalc(1),
+rmtxcomb(1), rmtxop(1), rpict(1)