man/man1/gensurf.1

.\" RCSid "$Id: gensurf.1,v 1.9 2025/01/21 01:56:27 greg Exp $"
.TH GENSURF 1 11/15/93 RADIANCE
.SH NAME
gensurf - generate a RADIANCE or Wavefront description of a curved surface
.SH SYNOPSIS
.B "gensurf mat name 'x(s,t)' 'y(s,t)' 'z(s,t)' m n"
[
.B "\-e expr"
][
.B "\-f file"
][
.B \-s
][
.B \-i
][
.B \-o
]
.br
.B "gensurf mat name 'x(s,t)' 'y(s,t)' dfile m n"
[
.B "\-e expr"
][
.B "\-f file"
][
.B \-i
][
.B \-s
][
.B \-o
]
.br
.B "gensurf mat name dfile dfile dfile m n"
[
.B \-i
][
.B \-s
][
.B \-o
]
.SH DESCRIPTION
.I Gensurf
produces either a RADIANCE scene description or a Wavefront .OBJ
file of a functional surface defined by the parametric equations
.I x(s,t),
.I y(s,t),
and
.I z(s,t).
The surface normal is defined by the right hand rule as
applied to
.I (s,t).
.I S
will vary from 0 to 1 in steps of
.I 1/m,
and
.I t
will vary from 0 to 1 in steps of
.I 1/n.
The surface will be composed of
.I 2*m*n
or fewer triangles and quadrilaterals.
The expressions are of the same type used in RADIANCE
function files.
Auxiliary expressions and/or files may be specified
in any number of
.I \-e
and
.I \-f
options.
The variable and function definitions in each
.I \-f source
file are read and compiled from the RADIANCE library where it is found.
The
.I \-i
option reverses surface normal directions relative to the (s,t) parameters, applying
a left-hand rule, instead.
The
.I \-s
option adds smoothing (surface normal interpolation) to the surface.
The
.I \-o
option produces a Wavefront .OBJ file rather than a RADIANCE
scene description.
This is most useful as input to the
.I obj2mesh(1)
program for producing a compiled mesh.
A single "usemtl" statement will appear at the beginning
of the .OBJ output, echoing the modifier given on the command line.
.PP
Rough holes may be cut in the mesh by defining a valid(s,t) function.
Where this function is positive, polygon vertices will be produced.
Where it is negative, no geometry will be output.
Surface normal interpolation will ignore any invalid vertices.
.PP
The second invocation form reads z data values from the file
.I dfile.
This file must give either m*n or (m+1)*(n+1) floating point z
values.
If m*n values are given, then the values correspond to the centroid
of each quadrilateral region.
If (m+1)*(n+1) values are given, then the values correspond to the
vertices of each quadrilateral region.
The ordering of the data in the file is such that the s values are
changing faster than the t values.
If a minus ('-') is given for
.I dfile,
then the values are read from the standard input.
.PP
The third invocation form is used to read coordinate triplets from a
file or the standard input.
The three
.I dfile
arguments must all be the same, and the corresponding file must
contain three floating point values for each point location.
The ordering and other details are the same as those described
for z value files above.
.SH EXAMPLE
To generate a tesselated sphere:
.IP "" .2i
gensurf crystal ball 'sin(PI*s)*cos(2*PI*t)' 'cos(PI*s)' 'sin(PI*s)*sin(2*PI*t)' 7 10
.PP
To generate a 10x20 smoothed height field from 12 recorded vertex
z values:
.IP "" .2i
gensurf dirt ground '10*s' '20*t' height.dat 2 3 \-s
.SH ENVIRONMENT
RAYPATH         the directories to check for auxiliary files.
.SH AUTHOR
Greg Ward
.SH BUGS
The smoothing operation requires that functions be defined
beyond the [0,1] boundaries of s and t.
.SH "SEE ALSO"
genbox(1), genrev(1), genworm(1), icalc(1),
obj2mesh(1), obj2rad(1), robjutil(1), rpict(1), rvu(1), xform(1)
Revision:	1.10
Committed:	Fri Jun 27 23:46:06 2025 UTC (4 months ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, HEAD
Changes since 1.9:	+9 -9 lines
Log Message:	docs(gensurf): Slight wording improvements
#	User	Rev	Content
1	greg	1.10	.\" RCSid "$Id: gensurf.1,v 1.9 2025/01/21 01:56:27 greg Exp $"
2	greg	1.1	.TH GENSURF 1 11/15/93 RADIANCE
3			.SH NAME
4	greg	1.2	gensurf - generate a RADIANCE or Wavefront description of a curved surface
5	greg	1.1	.SH SYNOPSIS
6			.B "gensurf mat name 'x(s,t)' 'y(s,t)' 'z(s,t)' m n"
7			[
8			.B "\-e expr"
9			][
10			.B "\-f file"
11			][
12			.B \-s
13	greg	1.2	][
14	greg	1.9	.B \-i
15			][
16	greg	1.2	.B \-o
17	greg	1.1	]
18			.br
19			.B "gensurf mat name 'x(s,t)' 'y(s,t)' dfile m n"
20			[
21			.B "\-e expr"
22			][
23			.B "\-f file"
24			][
25	greg	1.10	.B \-i
26			][
27	greg	1.1	.B \-s
28	greg	1.2	][
29			.B \-o
30	greg	1.1	]
31			.br
32			.B "gensurf mat name dfile dfile dfile m n"
33			[
34	greg	1.10	.B \-i
35			][
36	greg	1.1	.B \-s
37	greg	1.2	][
38			.B \-o
39	greg	1.1	]
40			.SH DESCRIPTION
41			.I Gensurf
42	greg	1.2	produces either a RADIANCE scene description or a Wavefront .OBJ
43			file of a functional surface defined by the parametric equations
44	greg	1.1	.I x(s,t),
45			.I y(s,t),
46			and
47			.I z(s,t).
48			The surface normal is defined by the right hand rule as
49			applied to
50			.I (s,t).
51			.I S
52			will vary from 0 to 1 in steps of
53			.I 1/m,
54			and
55			.I t
56			will vary from 0 to 1 in steps of
57			.I 1/n.
58			The surface will be composed of
59			.I 2mn
60			or fewer triangles and quadrilaterals.
61			The expressions are of the same type used in RADIANCE
62			function files.
63			Auxiliary expressions and/or files may be specified
64			in any number of
65			.I \-e
66			and
67			.I \-f
68			options.
69	greg	1.7	The variable and function definitions in each
70			.I \-f source
71			file are read and compiled from the RADIANCE library where it is found.
72	greg	1.1	The
73	greg	1.10	.I \-i
74			option reverses surface normal directions relative to the (s,t) parameters, applying
75			a left-hand rule, instead.
76			The
77	greg	1.1	.I \-s
78			option adds smoothing (surface normal interpolation) to the surface.
79	greg	1.2	The
80			.I \-o
81			option produces a Wavefront .OBJ file rather than a RADIANCE
82			scene description.
83			This is most useful as input to the
84			.I obj2mesh(1)
85			program for producing a compiled mesh.
86	greg	1.3	A single "usemtl" statement will appear at the beginning
87			of the .OBJ output, echoing the modifier given on the command line.
88	greg	1.1	.PP
89			Rough holes may be cut in the mesh by defining a valid(s,t) function.
90			Where this function is positive, polygon vertices will be produced.
91			Where it is negative, no geometry will be output.
92			Surface normal interpolation will ignore any invalid vertices.
93			.PP
94			The second invocation form reads z data values from the file
95			.I dfile.
96			This file must give either mn or (m+1)(n+1) floating point z
97			values.
98			If m*n values are given, then the values correspond to the centroid
99			of each quadrilateral region.
100			If (m+1)*(n+1) values are given, then the values correspond to the
101			vertices of each quadrilateral region.
102			The ordering of the data in the file is such that the s values are
103			changing faster than the t values.
104			If a minus ('-') is given for
105			.I dfile,
106			then the values are read from the standard input.
107			.PP
108			The third invocation form is used to read coordinate triplets from a
109			file or the standard input.
110			The three
111			.I dfile
112			arguments must all be the same, and the corresponding file must
113			contain three floating point values for each point location.
114			The ordering and other details are the same as those described
115			for z value files above.
116			.SH EXAMPLE
117			To generate a tesselated sphere:
118			.IP "" .2i
119			gensurf crystal ball 'sin(PIs)cos(2PIt)' 'cos(PIs)' 'sin(PIs)sin(2PI*t)' 7 10
120			.PP
121			To generate a 10x20 smoothed height field from 12 recorded vertex
122			z values:
123			.IP "" .2i
124	greg	1.6	gensurf dirt ground '10s' '20t' height.dat 2 3 \-s
125	greg	1.7	.SH ENVIRONMENT
126			RAYPATH the directories to check for auxiliary files.
127	greg	1.1	.SH AUTHOR
128			Greg Ward
129			.SH BUGS
130			The smoothing operation requires that functions be defined
131			beyond the [0,1] boundaries of s and t.
132			.SH "SEE ALSO"
133	greg	1.5	genbox(1), genrev(1), genworm(1), icalc(1),
134	greg	1.8	obj2mesh(1), obj2rad(1), robjutil(1), rpict(1), rvu(1), xform(1)