man/man1/rsplit.1

.\" RCSid "$Id: rsplit.1,v 1.12 2022/03/16 00:06:08 greg Exp $"
.TH RSPLIT 1 7/8/97 RADIANCE
.SH NAME
rsplit - splits standard input into multiple output files or streams
.SH SYNOPSIS
.B rsplit
[
.B \-tS
][
.B \-ih
][
.B \-iH
][
.B \-oh
][
.B \-oH
][
.B "\-x xres \-y yres"
][
.B \-oaN
|
.B \-ofN
|
.B \-odN
|
.B \-oiN
|
.B \-owN
|
.B \-obN
][
.B \-f
][
.B \-a
][
.B "\-on M"
]
output1 [options] output2 ..
.SH DESCRIPTION
.I Rsplit
writes lines or fields from the standard input to one or more output
streams.
By default, fields are separated by a
newline character (i.e., input is distributed by lines),
but the terminator can be changed using the
.I \-t
option.
If a space is specified as the terminator, then fields are separated by
any number of white spaces, including tabs, returns, and newlines.
Different terminators may be given for different fields by specifying
additional
.I \-t
options between each output specification.
Note that there is no space between this option and its argument, and
certain arguments, such as a space or a tab, must be quoted or escaped
with a backslash in most shells.
If no argument is given, the default newline terminator is re-established.
.PP
Output is either to a file, to a command, to the standard output, or to discard.
If a named output file exists, it will not be overwritten unless the
.I \-f
option is given, or it is being appended using the
.I \-a
option.
The same output file may not appear more than once.
Commands are given in quotes, and begin with an exclamantion point ('!').
At most, one command may reliably write to its standard output, and
doing so is incompatible with
.I rsplit
also writing to standard output.
A hyphen ('-') by itself tells
.I rsplit
to write directly to its standard output, and may appear multiple times.
The options before the first appearance determine the
standard output header parameters.
A period ('.') tells
.I rsplit
to discard the corresponding data, and also may appear multiple times.
.PP
The
.I \-oa
option may be used to specify ASCII data (the default), or the
.I \-of
option may be used to indicated binary IEEE 32-bit floats.
Similarly, the
.I \-od
and
.I \-oi
options may be used to indicate binary 64-bit doubles or integer words,
respectively.
The
.I \-ow
option specifies 2-byte short words, and the
.I \-ob
option specifies bytes.
If a number immediately follows any of these options, then it
indicates that multiple such values are expected for each record.
For example,
.I \-of3
indicates three floats per output record for the next named output.
In the case of the
.I \-oa
option, no number writes one line or field per stream, and numbers
greater than zero write multiple fields per record to the same stream.
If the terminating character is set to something other than newline ('\\n'),
a newline is added after each record (in addition to the terminator).
For binary output formts, no number implies one value per output.
No terminator characters are expected or written for binary outputs.
.PP
If a
.I \-on
option is given with a positive integer argument, this will be the
maximum number of records that will be written by
.I rsplit.
.PP
The
.I \-ih
option tells
.I rsplit
to expect a Radiance header on its input.
The
.I \-iH
option says to expect a resolution string for an image or similar.
The
.I \-x
and
.I \-y
options may alternatively be used to specify the input dimensions.
The
.I \-oh
option tells
.I rsplit
to produce a Radiance header on the next output stream.
The
.I \-oH
option will write a resolution string.
These options toggle the associated mode on and off,
so it is possible to have one output include a header or
resolution string and not the next by specifying the option(s) again.
Neither
.I \-oh
nor
.I \-oH
may be used with the append mode ('-a'), which may also be toggled.
.SH EXAMPLES
To alternate 5 lines between two output files:
.IP "" .2i
rsplit -oa5 output1.txt output2.txt < input.txt
.PP
To send the first of each double precision triplet to one file, and the second
and third to a second file, stopping after 500 triplets:
.IP "" .2i
rsplit -on 500 -od firstvals.dbl -od2 followingpairs.dbl < triplets.dbl
.PP
To convey material, color and distance information from rtrace to
separate files:
.IP "" .2i
vwrays [viewspec] | rtrace [options] -x 1024 -y 768 -h+ -oMlv octree | rsplit -ih -iH -t^I mats.txt -of depth.zbf -oh -oH -of3 '!pvalue -r -df > image.hdr'
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
cnt(1), histo(1), neaten(1), rcalc(1), rcode_depth(1),
rcode_ident(1), rcode_norm(1), rcode2bmp(1), rcrop(1),
rlam(1), rtpict(1), rtrace(1), split(1), tabfunc(1), total(1)
Revision:	1.13
Committed:	Wed May 15 18:58:54 2024 UTC (12 months ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.12:	+1 -3 lines
Log Message:	fix: removed non-existent -ocN option from usage
#	User	Rev	Content
1	greg	1.13	.\" RCSid "$Id: rsplit.1,v 1.12 2022/03/16 00:06:08 greg Exp $"
2	greg	1.1	.TH RSPLIT 1 7/8/97 RADIANCE
3			.SH NAME
4			rsplit - splits standard input into multiple output files or streams
5			.SH SYNOPSIS
6			.B rsplit
7			[
8			.B \-tS
9			][
10			.B \-ih
11			][
12			.B \-iH
13			][
14			.B \-oh
15			][
16			.B \-oH
17			][
18	greg	1.3	.B "\-x xres \-y yres"
19			][
20	greg	1.1	.B \-oaN
21			\|
22			.B \-ofN
23			\|
24			.B \-odN
25			\|
26			.B \-oiN
27			\|
28			.B \-owN
29			\|
30			.B \-obN
31			][
32			.B \-f
33			][
34			.B \-a
35			][
36			.B "\-on M"
37			]
38			output1 [options] output2 ..
39			.SH DESCRIPTION
40			.I Rsplit
41			writes lines or fields from the standard input to one or more output
42			streams.
43			By default, fields are separated by a
44	greg	1.3	newline character (i.e., input is distributed by lines),
45			but the terminator can be changed using the
46	greg	1.1	.I \-t
47			option.
48	greg	1.8	If a space is specified as the terminator, then fields are separated by
49			any number of white spaces, including tabs, returns, and newlines.
50	greg	1.3	Different terminators may be given for different fields by specifying
51	greg	1.1	additional
52			.I \-t
53	greg	1.3	options between each output specification.
54	greg	1.8	Note that there is no space between this option and its argument, and
55			certain arguments, such as a space or a tab, must be quoted or escaped
56			with a backslash in most shells.
57			If no argument is given, the default newline terminator is re-established.
58	greg	1.1	.PP
59	greg	1.11	Output is either to a file, to a command, to the standard output, or to discard.
60			If a named output file exists, it will not be overwritten unless the
61	greg	1.1	.I \-f
62			option is given, or it is being appended using the
63			.I \-a
64			option.
65	greg	1.11	The same output file may not appear more than once.
66	greg	1.1	Commands are given in quotes, and begin with an exclamantion point ('!').
67	greg	1.11	At most, one command may reliably write to its standard output, and
68			doing so is incompatible with
69			.I rsplit
70			also writing to standard output.
71			A hyphen ('-') by itself tells
72			.I rsplit
73			to write directly to its standard output, and may appear multiple times.
74			The options before the first appearance determine the
75			standard output header parameters.
76			A period ('.') tells
77			.I rsplit
78			to discard the corresponding data, and also may appear multiple times.
79	greg	1.1	.PP
80			The
81			.I \-oa
82			option may be used to specify ASCII data (the default), or the
83			.I \-of
84			option may be used to indicated binary IEEE 32-bit floats.
85			Similarly, the
86			.I \-od
87			and
88			.I \-oi
89			options may be used to indicate binary 64-bit doubles or integer words,
90			respectively.
91			The
92			.I \-ow
93			option specifies 2-byte short words, and the
94			.I \-ob
95			option specifies bytes.
96			If a number immediately follows any of these options, then it
97			indicates that multiple such values are expected for each record.
98			For example,
99			.I \-of3
100			indicates three floats per output record for the next named output.
101			In the case of the
102			.I \-oa
103			option, no number writes one line or field per stream, and numbers
104	greg	1.3	greater than zero write multiple fields per record to the same stream.
105			If the terminating character is set to something other than newline ('\\n'),
106			a newline is added after each record (in addition to the terminator).
107	greg	1.1	For binary output formts, no number implies one value per output.
108	greg	1.7	No terminator characters are expected or written for binary outputs.
109	greg	1.1	.PP
110			If a
111			.I \-on
112			option is given with a positive integer argument, this will be the
113			maximum number of records that will be written by
114			.I rsplit.
115			.PP
116			The
117			.I \-ih
118			option tells
119			.I rsplit
120			to expect a Radiance header on its input.
121			The
122			.I \-iH
123			option says to expect a resolution string for an image or similar.
124			The
125			.I \-x
126			and
127			.I \-y
128			options may alternatively be used to specify the input dimensions.
129			The
130			.I \-oh
131			option tells
132			.I rsplit
133			to produce a Radiance header on the next output stream.
134			The
135			.I \-oH
136			option will write a resolution string.
137			These options toggle the associated mode on and off,
138			so it is possible to have one output include a header or
139			resolution string and not the next by specifying the option(s) again.
140			Neither
141			.I \-oh
142			nor
143			.I \-oH
144	greg	1.6	may be used with the append mode ('-a'), which may also be toggled.
145	greg	1.5	.SH EXAMPLES
146	greg	1.1	To alternate 5 lines between two output files:
147			.IP "" .2i
148	greg	1.2	rsplit -oa5 output1.txt output2.txt < input.txt
149	greg	1.1	.PP
150			To send the first of each double precision triplet to one file, and the second
151			and third to a second file, stopping after 500 triplets:
152			.IP "" .2i
153	greg	1.2	rsplit -on 500 -od firstvals.dbl -od2 followingpairs.dbl < triplets.dbl
154	greg	1.1	.PP
155			To convey material, color and distance information from rtrace to
156			separate files:
157			.IP "" .2i
158			vwrays [viewspec] \| rtrace [options] -x 1024 -y 768 -h+ -oMlv octree \| rsplit -ih -iH -t^I mats.txt -of depth.zbf -oh -oH -of3 '!pvalue -r -df > image.hdr'
159			.SH AUTHOR
160			Greg Ward
161			.SH "SEE ALSO"
162	greg	1.6	cnt(1), histo(1), neaten(1), rcalc(1), rcode_depth(1),
163	greg	1.12	rcode_ident(1), rcode_norm(1), rcode2bmp(1), rcrop(1),
164	greg	1.10	rlam(1), rtpict(1), rtrace(1), split(1), tabfunc(1), total(1)