man/man1/pcompos.1

.\" RCSid "$Id: pcompos.1,v 1.8 2022/03/15 00:25:50 greg Exp $"
.TH PCOMPOS 1 12/18/97 RADIANCE
.SH NAME
pcompos - composite RADIANCE pictures.
.SH SYNOPSIS
.B pcompos
[
.B \-h
][
.B "\-x xres"
][
.B "\-y yres"
][
.B "\-b r g b"
][
.B "\-lh h"
][
.B \-la
]
[
.B "\-t min1"
][
.B "\+t max1"
][
.B "\-l lab"
][
.B "=SS"
]
.B "pic1 x1 y1 .."
.br
or
.br
.B pcompos
[
.B "\-a ncols"
][
.B "\-s spacing"
][
.B "\-o x0 y0"
][
options
]
.B "pic1 pic2 .."
.SH DESCRIPTION
.I Pcompos
arranges and composites RADIANCE pictures and sends the result to the
standard output.
Each input picture must be accompanied by an anchor point (unless the
.I \-a
option is used, see below).
This anchor point is the usually position of the picture's
left lower corner in the final output, but can be changed
for individual pictures with an 
.I =SS
option, where
.I S
is one of '-', '+' or '0', indicating the minimum, maximum or center
of the image, respectively.
(For example,
.I =+-
would indicate the anchor is relative to the right lower corner, and
.I =-0
would indicate the anchor is relative to the center of the left
edge.)\0
Negative anchor coordinates result in the input being cropped at the origin.
By default, the size of the output picture will be just large enough
to encompass all the input files.
By specifying a smaller dimension using the
.I \-x
and
.I \-y
options, input files can be cropped at the upper boundary.
Specifying a larger dimension produces a border.
The
.I \-b
option specifies a background color to appear wherever input
files do not cover.
The default value is black (0 0 0).
The
.I \-h
option may be used to reduce the information header size, which
can grow disproportionately after multiple runs of
.I pcompos
and/or
.I pcomb(1).
.PP
If input files overlap, later pictures will overwrite earlier ones.
By default, input files are copied unconditionally within the output
boundaries.
The
.I \-t
option specifies a lower threshold intensity under which input pixels
will not be copied to the output.
The
.I \+t
option specifies an upper threshold.
These options are useful for cutting around irregular boundaries in
the input.
.PP
The
.I \-l
option can be used to specify a label for a specific picture, which
will be given a height determined by the
.I \-lh
option (default 24 pixels) and placed in the upper left corner of
the picture.
This label is generated by the program
.I psign(1).
The
.I \-la
option instructs
.I pcompos
to label each picture automatically by its name.
This is particularly useful in conjunction with the
.I \-a
option for producing a catalog of images (see example below).
The
.I \-l
option may still be used to override the default label
for a picture.
.PP
The
.I \-a
option can be used to automatically compute anchor points
that place successive pictures next to each other in
.I ncols
columns.
The ordering will place the first picture in the lower left corner,
the next just to the right of it, and so on for
.I ncols
pictures.
Then, the next row up repeats the pattern until all the input
pictures have been added to the output.
If the pictures are of different size,
.I pcompos
will end up leaving some background areas in the output picture.
There will also be an unfinished row at the top if the number
of pictures is not evenly divided by
.I ncols.
The
.I "\-s N"
option will cause each image to be separated by at least N pixels.
The
.I "\-o x0 y0"
option specifies a nonzero anchor point for the bottom left image.
If a negative value is given for ncols, then the rows are reversed,
so they start from the top rather than the bottom.
This gives a more natural ordering in most cases, but has the
side-effect of moving any labels from the upper-left of each placed
subimage to the lower-left.
Also, the
.I \-o
option is interpreted differently, where the y0 value is number of
pixels from the top (rather than the bottom).
.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 
by preceeding it with an exclamation point ('!').
.SH EXAMPLE
To put a copyright label at the bottom of a picture:
.IP "" .2i
psign Copyright 1987 | pcompos inp.hdr 0 0 +t .5 - 384 64 > out.hdr
.PP
To make a catalog of images separated by white 10-pixel borders and
ordered four images per row starting from the top-left:
.IP "" .2i
pcompos -la -a -4 -s 10 -b 1 1 1 dog*.hdr > alldogs.hdr
.SH NOTES
Since there is a limit to the number of open files and processes,
large collections of images must be created in stages.
Even if the system limit on open files is large,
.I pcompos
places an artificial limit of 1024 on the number of open files and/or
processes.
.PP
The EXPOSURE= line is ignored on the input except when there is only
a single input picture, or mutliple pictures all have the same
exposure value.
In such cases,
.I pcompos
will echo the exposure line to the output header appropriately,
so that absolute calibration is maintained.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), pcomb(1), pfilt(1), psign(1), rcrop(1), rpict(1)
Revision:	1.9
Committed:	Fri Mar 18 21:09:16 2022 UTC (3 years, 7 months ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, rad5R4, HEAD
Changes since 1.8:	+9 -1 lines
Log Message:	docs(pcomb, pcompos): Added remarks about EXPOSURE settings
#	Content
1	.\" RCSid "$Id: pcompos.1,v 1.8 2022/03/15 00:25:50 greg Exp $"
2	.TH PCOMPOS 1 12/18/97 RADIANCE
3	.SH NAME
4	pcompos - composite RADIANCE pictures.
5	.SH SYNOPSIS
6	.B pcompos
7	[
8	.B \-h
9	][
10	.B "\-x xres"
11	][
12	.B "\-y yres"
13	][
14	.B "\-b r g b"
15	][
16	.B "\-lh h"
17	][
18	.B \-la
19	]
20	[
21	.B "\-t min1"
22	][
23	.B "\+t max1"
24	][
25	.B "\-l lab"
26	][
27	.B "=SS"
28	]
29	.B "pic1 x1 y1 .."
30	.br
31	or
32	.br
33	.B pcompos
34	[
35	.B "\-a ncols"
36	][
37	.B "\-s spacing"
38	][
39	.B "\-o x0 y0"
40	][
41	options
42	]
43	.B "pic1 pic2 .."
44	.SH DESCRIPTION
45	.I Pcompos
46	arranges and composites RADIANCE pictures and sends the result to the
47	standard output.
48	Each input picture must be accompanied by an anchor point (unless the
49	.I \-a
50	option is used, see below).
51	This anchor point is the usually position of the picture's
52	left lower corner in the final output, but can be changed
53	for individual pictures with an
54	.I =SS
55	option, where
56	.I S
57	is one of '-', '+' or '0', indicating the minimum, maximum or center
58	of the image, respectively.
59	(For example,
60	.I =+-
61	would indicate the anchor is relative to the right lower corner, and
62	.I =-0
63	would indicate the anchor is relative to the center of the left
64	edge.)\0
65	Negative anchor coordinates result in the input being cropped at the origin.
66	By default, the size of the output picture will be just large enough
67	to encompass all the input files.
68	By specifying a smaller dimension using the
69	.I \-x
70	and
71	.I \-y
72	options, input files can be cropped at the upper boundary.
73	Specifying a larger dimension produces a border.
74	The
75	.I \-b
76	option specifies a background color to appear wherever input
77	files do not cover.
78	The default value is black (0 0 0).
79	The
80	.I \-h
81	option may be used to reduce the information header size, which
82	can grow disproportionately after multiple runs of
83	.I pcompos
84	and/or
85	.I pcomb(1).
86	.PP
87	If input files overlap, later pictures will overwrite earlier ones.
88	By default, input files are copied unconditionally within the output
89	boundaries.
90	The
91	.I \-t
92	option specifies a lower threshold intensity under which input pixels
93	will not be copied to the output.
94	The
95	.I \+t
96	option specifies an upper threshold.
97	These options are useful for cutting around irregular boundaries in
98	the input.
99	.PP
100	The
101	.I \-l
102	option can be used to specify a label for a specific picture, which
103	will be given a height determined by the
104	.I \-lh
105	option (default 24 pixels) and placed in the upper left corner of
106	the picture.
107	This label is generated by the program
108	.I psign(1).
109	The
110	.I \-la
111	option instructs
112	.I pcompos
113	to label each picture automatically by its name.
114	This is particularly useful in conjunction with the
115	.I \-a
116	option for producing a catalog of images (see example below).
117	The
118	.I \-l
119	option may still be used to override the default label
120	for a picture.
121	.PP
122	The
123	.I \-a
124	option can be used to automatically compute anchor points
125	that place successive pictures next to each other in
126	.I ncols
127	columns.
128	The ordering will place the first picture in the lower left corner,
129	the next just to the right of it, and so on for
130	.I ncols
131	pictures.
132	Then, the next row up repeats the pattern until all the input
133	pictures have been added to the output.
134	If the pictures are of different size,
135	.I pcompos
136	will end up leaving some background areas in the output picture.
137	There will also be an unfinished row at the top if the number
138	of pictures is not evenly divided by
139	.I ncols.
140	The
141	.I "\-s N"
142	option will cause each image to be separated by at least N pixels.
143	The
144	.I "\-o x0 y0"
145	option specifies a nonzero anchor point for the bottom left image.
146	If a negative value is given for ncols, then the rows are reversed,
147	so they start from the top rather than the bottom.
148	This gives a more natural ordering in most cases, but has the
149	side-effect of moving any labels from the upper-left of each placed
150	subimage to the lower-left.
151	Also, the
152	.I \-o
153	option is interpreted differently, where the y0 value is number of
154	pixels from the top (rather than the bottom).
155	.PP
156	The standard input can be specified with a hyphen ('-').
157	A command that produces a RADIANCE picture can be given in place of a file
158	by preceeding it with an exclamation point ('!').
159	.SH EXAMPLE
160	To put a copyright label at the bottom of a picture:
161	.IP "" .2i
162	psign Copyright 1987 \| pcompos inp.hdr 0 0 +t .5 - 384 64 > out.hdr
163	.PP
164	To make a catalog of images separated by white 10-pixel borders and
165	ordered four images per row starting from the top-left:
166	.IP "" .2i
167	pcompos -la -a -4 -s 10 -b 1 1 1 dog*.hdr > alldogs.hdr
168	.SH NOTES
169	Since there is a limit to the number of open files and processes,
170	large collections of images must be created in stages.
171	Even if the system limit on open files is large,
172	.I pcompos
173	places an artificial limit of 1024 on the number of open files and/or
174	processes.
175	.PP
176	The EXPOSURE= line is ignored on the input except when there is only
177	a single input picture, or mutliple pictures all have the same
178	exposure value.
179	In such cases,
180	.I pcompos
181	will echo the exposure line to the output header appropriately,
182	so that absolute calibration is maintained.
183	.SH AUTHOR
184	Greg Ward
185	.SH "SEE ALSO"
186	getinfo(1), pcomb(1), pfilt(1), psign(1), rcrop(1), rpict(1)