man/man1/rcrop.1

.\" RCSid "$Id: rcrop.1,v 1.8 2023/12/12 16:31:45 greg Exp $"
.TH RCROP 1 3/14/2022 RADIANCE
.SH NAME
rcrop - crop RADIANCE matrix or picture
.SH SYNOPSIS
.B "rcrop row0 col0 nrows ncols"
[
.B input
[
.B output
]
]
.SH DESCRIPTION
.I Rcrop
copies the indicated section of a matrix or RADIANCE picture.
The four required arguments are the initial row (scanline) to copy,
the initial column, the number of rows to copy, and the number of columns
to include per row.
Note that rows are numbered from 0 at the top of a matrix or picture,
and columns are changing fastest in the input, which can have any number
of components per matrix element.
.PP
The input must have a valid header, including dimensions and format,
and a header will always be produced.
This is similar behavior to
.I rmtxop(1).
If the input header is missing, one can usually be added with an
appropriate call to
.I rcollate(1).
If an output header is not desired, it can be removed using
.I getinfo(1).
.PP
One cannot specify crop boundaries outside the matrix dimension limits.
If a 0 value is specified for the number of rows to copy, then all rows
will be copied, starting from row0.
Similarly, a 0 value for the number of columns to copy implies all
columns >= col0 will be copied.
A negative count for the number of rows or columns cuts the
corresponding amount off the end(s).
.PP
Using
.I rcrop
on a RADIANCE picture rather than
.I pcompos(1)
corrects the view parameters if present,
and preserves the exposure in a way that is compatible with
.I evalglare(1).
However, one must remember that rows correspond to Y
coordinates, and the orientation is reversed from a standard
picture, where Y=0 is the bottom scanline.
Spectral pictures, as might be produced by
.I rtrace(1)
or
.I rfluxmtx(1),
are also supported.
.PP
All matrix formats are supported, including text (ASCII), binary float
and double.
The
.I rcrop
tool also works on encoded normal vector files produced by
.I rcode_norm(1)
and encoded depth files produced by
.I rcode_depth(1).
Data is copied verbatim, i.e., there is no internal conversion to
another representation, although white space may change in text files.
.PP
If no input file is given, data will be taken from the standard input.
If no output file is specified, data will be copied to the standard output.
.SH EXAMPLES
To crop a matrix down to 15 rows by 19 columns,
starting at row 10 and column 12:
.IP "" .2i
rcrop 10 12 15 19 input.mtx > output.mtx
.PP
To extract column 35 from a matrix:
.IP "" .2i
rcrop 0 35 0 1 orig.mtx > col35.mtx
.PP
To crop a picture to (X by Y) = (1500 by 1000),
starting from upper-left corner:
.IP "" .2i
rcrop 0 0 1000 1500 orig.hdr cropped.hdr
.PP
Two ways of computing the inner product of row 15 in matrix 1 by
column 27 in matrix 2 and extracting the result without a header,
the second command being more efficient:
.IP "" .2i
rmtxop -fa mat1.mtx mat2.mtx | rcrop 15 27 1 1 | getinfo -
.IP "" .2i
rmtxop -fa '!rcrop 15 0 1 0 mat1.mtx' '!rcrop 0 27 0 1 mat2.mtx' | getinfo -
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
evalglare(1), pcompos(1), rcalc(1), rcode_depth(1), rcode_norm(1),
rcollate(1), rcomb(1), rfluxmtx(1), rmtxop(1), rsplit(1), rtrace(1)
Revision:	1.9
Committed:	Fri May 17 20:50:57 2024 UTC (11 months, 4 weeks ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.8:	+3 -1 lines
Log Message:	feat(rcrop): Negative counts for #rows or #columns cut from the ends
#	User	Rev	Content
1	greg	1.9	.\" RCSid "$Id: rcrop.1,v 1.8 2023/12/12 16:31:45 greg Exp $"
2	greg	1.1	.TH RCROP 1 3/14/2022 RADIANCE
3			.SH NAME
4			rcrop - crop RADIANCE matrix or picture
5			.SH SYNOPSIS
6			.B "rcrop row0 col0 nrows ncols"
7			[
8			.B input
9			[
10			.B output
11			]
12			]
13			.SH DESCRIPTION
14			.I Rcrop
15			copies the indicated section of a matrix or RADIANCE picture.
16			The four required arguments are the initial row (scanline) to copy,
17			the initial column, the number of rows to copy, and the number of columns
18			to include per row.
19			Note that rows are numbered from 0 at the top of a matrix or picture,
20			and columns are changing fastest in the input, which can have any number
21			of components per matrix element.
22			.PP
23	greg	1.3	The input must have a valid header, including dimensions and format,
24			and a header will always be produced.
25			This is similar behavior to
26			.I rmtxop(1).
27			If the input header is missing, one can usually be added with an
28			appropriate call to
29			.I rcollate(1).
30			If an output header is not desired, it can be removed using
31			.I getinfo(1).
32			.PP
33	greg	1.1	One cannot specify crop boundaries outside the matrix dimension limits.
34			If a 0 value is specified for the number of rows to copy, then all rows
35			will be copied, starting from row0.
36			Similarly, a 0 value for the number of columns to copy implies all
37			columns >= col0 will be copied.
38	greg	1.9	A negative count for the number of rows or columns cuts the
39			corresponding amount off the end(s).
40	greg	1.1	.PP
41			Using
42			.I rcrop
43			on a RADIANCE picture rather than
44			.I pcompos(1)
45			corrects the view parameters if present,
46			and preserves the exposure in a way that is compatible with
47			.I evalglare(1).
48			However, one must remember that rows correspond to Y
49			coordinates, and the orientation is reversed from a standard
50			picture, where Y=0 is the bottom scanline.
51	greg	1.6	Spectral pictures, as might be produced by
52			.I rtrace(1)
53			or
54			.I rfluxmtx(1),
55			are also supported.
56	greg	1.1	.PP
57	greg	1.5	All matrix formats are supported, including text (ASCII), binary float
58			and double.
59	greg	1.2	The
60			.I rcrop
61			tool also works on encoded normal vector files produced by
62			.I rcode_norm(1)
63			and encoded depth files produced by
64			.I rcode_depth(1).
65	greg	1.5	Data is copied verbatim, i.e., there is no internal conversion to
66			another representation, although white space may change in text files.
67	greg	1.2	.PP
68	greg	1.1	If no input file is given, data will be taken from the standard input.
69			If no output file is specified, data will be copied to the standard output.
70			.SH EXAMPLES
71			To crop a matrix down to 15 rows by 19 columns,
72			starting at row 10 and column 12:
73			.IP "" .2i
74			rcrop 10 12 15 19 input.mtx > output.mtx
75			.PP
76			To extract column 35 from a matrix:
77			.IP "" .2i
78			rcrop 0 35 0 1 orig.mtx > col35.mtx
79			.PP
80			To crop a picture to (X by Y) = (1500 by 1000),
81			starting from upper-left corner:
82			.IP "" .2i
83			rcrop 0 0 1000 1500 orig.hdr cropped.hdr
84	greg	1.3	.PP
85			Two ways of computing the inner product of row 15 in matrix 1 by
86			column 27 in matrix 2 and extracting the result without a header,
87			the second command being more efficient:
88			.IP "" .2i
89			rmtxop -fa mat1.mtx mat2.mtx \| rcrop 15 27 1 1 \| getinfo -
90			.IP "" .2i
91			rmtxop -fa '!rcrop 15 0 1 0 mat1.mtx' '!rcrop 0 27 0 1 mat2.mtx' \| getinfo -
92	greg	1.1	.SH AUTHOR
93			Greg Ward
94			.SH "SEE ALSO"
95	greg	1.6	evalglare(1), pcompos(1), rcalc(1), rcode_depth(1), rcode_norm(1),
96	greg	1.8	rcollate(1), rcomb(1), rfluxmtx(1), rmtxop(1), rsplit(1), rtrace(1)