1138 lines
37 KiB
HTML
1138 lines
37 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta name="description" content="The RPly Homepage">
|
|
<meta name="keywords" content="open source, C, Library, PLY, file format,
|
|
input, output, tools">
|
|
<title>
|
|
RPly: ANSI C library for PLY file format input and output
|
|
</title>
|
|
<link rel="stylesheet" href="reference.css" type="text/css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<div class=header>
|
|
<hr>
|
|
<center>
|
|
<table summary="RPly logo">
|
|
<tr><td align=center>
|
|
<img border=0 alt="RPly" src="rply.png">
|
|
</td></tr>
|
|
<tr><td align=center valign=top>ANSI C Library for PLY file format input and output
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
</div>
|
|
|
|
|
|
<!-- Introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h1>Introduction</h1>
|
|
|
|
<p>RPly is a library that lets applications read and write PLY files. The
|
|
PLY file format is widely used to store geometric information, such as 3D
|
|
models, but is general enough to be useful for other purposes.
|
|
</p>
|
|
|
|
<p>There are other libraries out there, of course. I tried using them and
|
|
finally decided to write my own. The result is RPly, and I
|
|
hope you are as happy with it as I am. </p>
|
|
|
|
<p>RPly is easy to use, well documented, small, free,
|
|
open-source, ANSI C, efficient, and well tested. I will keep supporting it
|
|
for a while because all my tools use the library for input/output. The highlights are: </p>
|
|
<ul>
|
|
<li> A callback mechanism that makes PLY file input straightforward;
|
|
<li> Support for the full range of numeric formats though the user only
|
|
deals with doubles;
|
|
<li> Binary (big and little endian) and text modes are fully supported;
|
|
<li> Input and output are buffered for efficiency;
|
|
<li> Available under the
|
|
<a href=http://www.opensource.org/licenses/mit-license.html>MIT license</a>
|
|
for added freedom.
|
|
</ul>
|
|
|
|
<p>
|
|
The format was developed at <a
|
|
href=http://graphics.stanford.edu/data/3Dscanrep/>Stanford University</a>
|
|
for use with their 3D scanning projects. Greg Turk's PLY library, available
|
|
from <a href=http://www.cc.gatech.edu/projects/large_models>
|
|
Georgia Institute of Technology</a>, seems to be the standard reference
|
|
to the PLY file format, although there are some variations out there.
|
|
</p>
|
|
|
|
<p> Whatever documentation and examples were found, were taken into
|
|
consideration to create RPly. In theory, since RPly doesn't try to interpret
|
|
the meaning of the data in a PLY file, it should be able to read any PLY file.
|
|
In practice, the library works with all PLY files that I could find. </p>
|
|
|
|
<h2>Download</h2>
|
|
|
|
<p>
|
|
Version 1.1.4 of RPly is available for download in source
|
|
code from <a href=rply-1.1.4.tar.gz>this link</a>. Examples and documentation
|
|
are packed inside the tarball. Have fun!
|
|
</p>
|
|
|
|
<p>
|
|
Copyright © 2003-2015 Diego Nehab. All rights reserved. <br>
|
|
Author: <A href="http://www.impa.br/~diego">Diego Nehab</a>
|
|
</p>
|
|
|
|
<h2>What's new?</h2>
|
|
|
|
<ul>
|
|
<li> Fixed bug that prevented reading of ASCII files that
|
|
are not terminated by a whitespace;
|
|
<li> Added <tt>ply_open_from_file</tt> and
|
|
<tt>ply_create_to_file</tt> variants to <tt>ply_open</tt>
|
|
and <tt>ply_create</tt>, respectively, that receive file
|
|
pointers instead of file names.
|
|
</ul>
|
|
|
|
<h2> RPly's idea of what a PLY file is </h2>
|
|
|
|
<p> A PLY file contains the description of one object. This object is
|
|
composed by <em>elements</em>, each element type
|
|
being defined by a group of <em>properties</em>. The PLY file
|
|
format specifies a syntax for the description of element types and the
|
|
properties that compose them, as well as comments and meta-information.
|
|
</p>
|
|
|
|
<p> The element type descriptions come in a header, which is followed by
|
|
element instances. Element instances come grouped by their type, in the
|
|
order of declaration. Each element instance is defined by the value
|
|
of its properties. Properties values also appear in the order of their
|
|
declaration. Here is a sample PLY file describing a triangle: </p>
|
|
|
|
<pre class=example>
|
|
ply
|
|
format ascii 1.0
|
|
comment this is a simple file
|
|
obj_info any data, in one line of free form text
|
|
element vertex 3
|
|
property float x
|
|
property float y
|
|
property float z
|
|
element face 1
|
|
property list uchar int vertex_indices
|
|
end_header
|
|
-1 0 0
|
|
0 1 0
|
|
1 0 0
|
|
3 0 1 2
|
|
</pre>
|
|
|
|
<p> The header goes from the first line to the line marked by
|
|
<tt>end_header</tt>. The first line contains only <tt>ply\n</tt> and is
|
|
used to detect whether a file is in PLY format or not (RPly
|
|
also accepts files that start with <tt>ply\r\n</tt>, in
|
|
which case the end-of-line terminator is assumed to be
|
|
<tt>\r\n</tt> throughout.) The second line
|
|
specifies the <tt>format</tt> number (which is always <tt>1.0</tt>) and the
|
|
storage mode (<tt>ascii</tt>, <tt>binary_big_endian</tt> or
|
|
<tt>binary_little_endian</tt>). </p>
|
|
|
|
<p> Lines that start with <tt>comment</tt> are just comments, of course.
|
|
Lines that start with <tt>obj_info</tt> contain meta-information about the
|
|
object. <tt>Comment</tt>s and <tt>obj_info</tt>s are optional and their
|
|
relative order in the header is irrelevant. </p>
|
|
|
|
<p> In the sample PLY file, the first element type is declared with name
|
|
<tt>vertex</tt>, and on the same line we learn that there will be 3
|
|
instances of this element type. The properties following describe what a
|
|
<tt>vertex</tt> element looks like. Each <tt>vertex</tt> is declared to
|
|
consist of 3 scalar properties, named <tt>x</tt>, <tt>y</tt> and
|
|
<tt>z</tt>. Each scalar property is declared to be of type <tt>float</tt>.
|
|
</p>
|
|
|
|
<p> Scalar types can be any of the following: <tt>int8</tt>,
|
|
<tt>uint8</tt>, <tt>int16</tt>, <tt>uint16</tt>, <tt>int32</tt>,
|
|
<tt>uint32</tt>, <tt>float32</tt>, <tt>float64</tt>, <tt>char</tt>,
|
|
<tt>uchar</tt>, <tt>short</tt>, <tt>ushort</tt>, <tt>int</tt>,
|
|
<tt>uint</tt>, <tt>float</tt>, <tt>double</tt>. They consist of signed
|
|
and unsigned integer types of sizes 8, 16 and 32 bits, as well as floating
|
|
point types of 32 and 64bits.
|
|
|
|
<p> Next, the <tt>face</tt> element type is declared, of which only 1
|
|
instance will be given. This element consists of a <tt>list</tt> property,
|
|
named <tt>vertex_indices</tt>. Lists are sequences on which the
|
|
first value, the <em>length</em>, gives the number of remaining values. List properties are described by the scalar
|
|
type of their length field and the scalar type of the remaining fields.
|
|
In the case of <tt>vertex_indices</tt>, the length field
|
|
is of type <tt>uchar</tt> and the remaining values are of type
|
|
<tt>int</tt>. </p>
|
|
|
|
<p> Following the header, come the elements, in the order they were
|
|
declared in the header. First come the 3 elements of type <tt>vertex</tt>,
|
|
each represented by the value of their properties <tt>x</tt>, <tt>y</tt>
|
|
and <tt>z</tt>. Then comes the single <tt>face</tt> element, composed by a
|
|
single list of type <tt>vertex_indices</tt> containing 3 values
|
|
(0 1 2).</p>
|
|
|
|
<h2> How to read a file with RPly </h2>
|
|
|
|
<p> Most users that want to read a PLY file already know which elements and
|
|
properties they are interested in. In the following example, we will
|
|
implement a simple program that dumps the contents of a PLY file to the
|
|
terminal, in a different, simpler format that only works for triangles.
|
|
</p>
|
|
|
|
<p> This simple format has a header that gives the number of vertices in the
|
|
first line and the number of triangles in the second line. Following the
|
|
header come the vertices, and finally the triangles. Here is the sample
|
|
code for the program:</p>
|
|
|
|
<pre class=example>
|
|
#include <stdio.h>
|
|
#include "rply.h"
|
|
|
|
static int vertex_cb(p_ply_argument argument) {
|
|
long eol;
|
|
ply_get_argument_user_data(argument, NULL, &eol);
|
|
printf("%g", ply_get_argument_value(argument));
|
|
if (eol) printf("\n");
|
|
else printf(" ");
|
|
return 1;
|
|
}
|
|
|
|
static int face_cb(p_ply_argument argument) {
|
|
long length, value_index;
|
|
ply_get_argument_property(argument, NULL, &length, &value_index);
|
|
switch (value_index) {
|
|
case 0:
|
|
case 1:
|
|
printf("%g ", ply_get_argument_value(argument));
|
|
break;
|
|
case 2:
|
|
printf("%g\n", ply_get_argument_value(argument));
|
|
break;
|
|
default:
|
|
break;
|
|
}
|
|
return 1;
|
|
}
|
|
|
|
int main(void) {
|
|
long nvertices, ntriangles;
|
|
p_ply ply = ply_open("input.ply", NULL, 0, NULL);
|
|
if (!ply) return 1;
|
|
if (!ply_read_header(ply)) return 1;
|
|
nvertices = ply_set_read_cb(ply, "vertex", "x", vertex_cb, NULL, 0);
|
|
ply_set_read_cb(ply, "vertex", "y", vertex_cb, NULL, 0);
|
|
ply_set_read_cb(ply, "vertex", "z", vertex_cb, NULL, 1);
|
|
ntriangles = ply_set_read_cb(ply, "face", "vertex_indices", face_cb, NULL, 0);
|
|
printf("%ld\n%ld\n", nvertices, ntriangles);
|
|
if (!ply_read(ply)) return 1;
|
|
ply_close(ply);
|
|
return 0;
|
|
}
|
|
</pre>
|
|
|
|
<p> RPly uses callbacks to pass data to an application. Independent callbacks
|
|
can be associated with each property of each element. For scalar
|
|
properties, the callback is invoked once for each instance. For list
|
|
properties, the callback is invoked first with the number of
|
|
entries in the instance, and then once for each of the data entries.
|
|
<em>This is exactly the order in which the data items appear in the
|
|
file.</em></p>
|
|
|
|
<p> To keep things simple, values are always passed as <tt>double</tt>,
|
|
regardless of how they are stored in the file. From its parameters,
|
|
callbacks can find out exactly which part of the file is being processed
|
|
(including the actual type of the value), plus access custom information
|
|
provided by the user in the form of a pointer and an integer constant. </p>
|
|
|
|
<p> In our example, we start with a call to <tt>ply_open</tt> to open a
|
|
file for reading. Then we get RPly to parse it's header, with a call to
|
|
<tt>ply_read_header</tt>. After the header is parsed, RPly knows which
|
|
element types and properties are available. We then set callbacks for each
|
|
of the <tt>vertex</tt> element properties and the <tt>face</tt> property
|
|
(using <tt>ply_set_read_cb</tt>). Finally, we invoke the main RPly reading
|
|
function, <tt>ply_read</tt>. This function reads all data in the file,
|
|
passing the data to the appropriate callbacks. After all reading is done,
|
|
we call <tt>ply_close</tt> to release any resources used by RPly.</p>
|
|
|
|
<p>There are some details, of course. <tt>Ply_set_read_cb</tt> returns the
|
|
number of instances of the target property (which is the same as the number
|
|
of element instances). This is how the program obtains the number of
|
|
vertices and faces in the file. </p>
|
|
|
|
<p>RPly lets us associate one pointer <em>and</em> one integer to each
|
|
callback. We are free to use either or both to link some context to our
|
|
callbacks. Our example uses the integer placeholder to tell
|
|
<tt>vertex_cb</tt> that it has to break the line after the <tt>z</tt>
|
|
property (notice the last argument of <tt>ply_set_read_cb</tt>).</p>
|
|
|
|
<p><tt>Vertex_cb</tt> gets the user data and the property value from it's
|
|
argument and prints accordingly. The <tt>face_cb</tt> callback is a bit
|
|
more complicated because lists are more complicated. Since the
|
|
simple file format only supports triangles, it only prints the first
|
|
3 list values, after which it breaks the line. </p>
|
|
|
|
<p> The output of the program, as expected, is: </p>
|
|
|
|
<pre class=example>
|
|
3
|
|
1
|
|
-1 0 0
|
|
0 1 0
|
|
1 0 0
|
|
0 1 2
|
|
</pre>
|
|
|
|
<h2> Writing files with RPly </h2>
|
|
|
|
<p> The next example is somewhat more involved. We will create a program
|
|
that converts our simple PLY file to binary mode. Besides showing how to
|
|
write a PLY file, this example also illustrates the query functions. We
|
|
do not know a priori which elements and properties, comments and obj_infos
|
|
will be in the input file, so we need a way to find out. Although our simple
|
|
program would work on any PLY file, a better version of this program is
|
|
available from the RPly distribution. For simplicity, the simple version
|
|
omits error messages and command line parameter processing. </p>
|
|
|
|
<p> In practice, writing a file is even easier than reading one. First we
|
|
create a file in binary mode, with a call to <tt>ply_create</tt> (notice
|
|
the argument <tt>PLY_LITTLE_ENDIAN</tt> that gives the storage mode). Then,
|
|
we define the elements using <tt>ply_add_element</tt>. After each element, we
|
|
define its properties using <tt>ply_add_scalar_property</tt> or
|
|
<tt>ply_add_list_property</tt>. When we are done with elements and
|
|
properties, we add comments and obj_infos. We then write the header with
|
|
<tt>ply_write_header</tt> and send all data items. The data items are sent
|
|
one by one, with calls to <tt>ply_write</tt>, <em>in the same order they
|
|
are to appear in the file</em>. Again, to simplify things, this function
|
|
receives data as <tt>double</tt> and performs the needed conversion. Here
|
|
is the code for the example: </p>
|
|
|
|
<pre class=example>
|
|
#include <stdio.h>
|
|
#include "rply.h"
|
|
|
|
static int callback(p_ply_argument argument) {
|
|
void *pdata;
|
|
/* just pass the value from the input file to the output file */
|
|
ply_get_argument_user_data(argument, &pdata, NULL);
|
|
ply_write((p_ply) pdata, ply_get_argument_value(argument));
|
|
return 1;
|
|
}
|
|
|
|
static int setup_callbacks(p_ply iply, p_ply oply) {
|
|
p_ply_element element = NULL;
|
|
/* iterate over all elements in input file */
|
|
while ((element = ply_get_next_element(iply, element))) {
|
|
p_ply_property property = NULL;
|
|
long ninstances = 0;
|
|
const char *element_name;
|
|
ply_get_element_info(element, &element_name, &ninstances);
|
|
/* add this element to output file */
|
|
if (!ply_add_element(oply, element_name, ninstances)) return 0;
|
|
/* iterate over all properties of current element */
|
|
while ((property = ply_get_next_property(element, property))) {
|
|
const char *property_name;
|
|
e_ply_type type, length_type, value_type;
|
|
ply_get_property_info(property, &property_name, &type,
|
|
&length_type, &value_type);
|
|
/* setup input callback for this property */
|
|
if (!ply_set_read_cb(iply, element_name, property_name, callback,
|
|
oply, 0)) return 0;
|
|
/* add this property to output file */
|
|
if (!ply_add_property(oply, property_name, type, length_type,
|
|
value_type)) return 0;
|
|
}
|
|
}
|
|
return 1;
|
|
}
|
|
|
|
int main(int argc, char *argv[]) {
|
|
const char *value;
|
|
p_ply iply, oply;
|
|
iply = ply_open("input.ply", NULL, 0, NULL);
|
|
if (!iply) return 1;
|
|
if (!ply_read_header(iply)) return 1;
|
|
oply = ply_create("output.ply", PLY_LITTLE_ENDIAN, NULL, 0, NULL);
|
|
if (!oply) return 1;
|
|
if (!setup_callbacks(iply, oply)) return 1;
|
|
/* pass comments and obj_infos from input to output */
|
|
value = NULL;
|
|
while ((value = ply_get_next_comment(iply, value)))
|
|
if (!ply_add_comment(oply, value)) return 1;
|
|
value = NULL;
|
|
while ((value = ply_get_next_obj_info(iply, value)))
|
|
if (!ply_add_obj_info(oply, value)) return 1;;
|
|
/* write output header */
|
|
if (!ply_write_header(oply)) return 1;
|
|
/* read input file generating callbacks that pass data to output file */
|
|
if (!ply_read(iply)) return 1;
|
|
/* close up, we are done */
|
|
if (!ply_close(iply)) return 1;
|
|
if (!ply_close(oply)) return 1;
|
|
return 0;
|
|
}
|
|
</pre>
|
|
|
|
<p> RPly uses iterators to let the user loop over a PLY file header. A
|
|
function is used to get the first item of a given class (element, property
|
|
etc). Passing the last returned item to the same function produces the next
|
|
item, until there are no more items. Examples of iterator use can be seen
|
|
in the <tt>main</tt> function, which uses them to loop over comments and
|
|
obj_infos, and in the <tt>setup_callbacks</tt> function, which loops over
|
|
elements and properties. </p>
|
|
|
|
<p> In the <tt>setup_callbacks</tt> function, for each element in the
|
|
input, an equivalent element is defined in the output. For each property in
|
|
each element, an equivalent property is defined in the output. Notice that
|
|
the same callback is specified for all properties. It is given the output
|
|
PLY handle as the context pointer. Each time it is called, it passes the
|
|
received value to <tt>ply_write</tt> on the output handle. It is as simple
|
|
as that. </p>
|
|
|
|
<h2> A note on locale </h2>
|
|
|
|
<p> ASCII PLY files are supposed to use the <tt>C</tt>
|
|
locale for numeric formatting. RPly relies on library
|
|
functions (such as <tt>fprintf</tt> and <tt>strtod</tt>)
|
|
that are affected by the current locale. If your software
|
|
modifies the locale (or if it uses another library/toolkit that
|
|
does) and you use RPly under the modified locale, you may be
|
|
unable to read or write properly formatted ASCII PLY files.
|
|
</p>
|
|
|
|
<p> Modifying RPly internally to hedge against different
|
|
locales would be complicated, particularly in multi-threaded
|
|
applications. Therefore, RPly leaves this as your
|
|
responsibility. To protect against locale problems in the
|
|
simplest scenario, you should bracket RPly I/O as follows: </p>
|
|
|
|
<pre class="example">
|
|
#include <locale.h>
|
|
/* Save application locale */
|
|
const char *old_locale = setlocale(LC_NUMERIC, NULL);
|
|
/* Change to PLY standard */
|
|
setlocale(LC_NUMERIC, "C");
|
|
/* Use the RPly library */
|
|
...
|
|
|
|
/* Restore application locale when done */
|
|
setlocale(LC_NUMERIC, old_locale);
|
|
</pre>
|
|
|
|
<h1>Reference Manual</h1>
|
|
|
|
<!-- ply_open ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_open>
|
|
p_ply <b>ply_open</b>(const char *name, p_ply_error_cb error_cb, long idata, void *pdata)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Opens a PLY file for reading, checks if it is a valid PLY file
|
|
and returns a handle to it.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Name</tt> is the file name, and <tt>error_cb</tt> is a function to
|
|
be called when an error is found.
|
|
Arguments <tt>idata</tt>
|
|
and <tt>pdata</tt> are available to the error callback via the
|
|
<a href=#ply_get_ply_user_data><tt>ply_get_ply_user_data</tt></a>
|
|
function.
|
|
If <tt>error_cb</tt> is NULL, the default
|
|
error callback is used. It prints a message to the standard error stream.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns a handle to the file or NULL on error.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: <tt>Error_cb</tt> is of type <tt>void
|
|
(*p_ply_error_cb)(p_ply ply, const char *message)</tt>.
|
|
</p>
|
|
|
|
<!-- ply_open_from_file ++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_open_from_file>
|
|
p_ply <b>ply_open_from_file</b>(FILE *file_pointer, p_ply_error_cb error_cb, long idata, void *pdata)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Checks if the FILE pointer points to a valid PLY file and returns a
|
|
handle to it. The handle can be used wherever a handle returned by <a
|
|
href=#ply_open><tt>ply_open</tt></a> is accepted.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>File_pointer</tt> is the FILE pointer open for reading, and <tt>error_cb</tt> is a function to be called when an error is found.
|
|
Arguments <tt>idata</tt>
|
|
and <tt>pdata</tt> are available to the error callback via the
|
|
<a href=#ply_get_ply_user_data><tt>ply_get_ply_user_data</tt></a>
|
|
function.
|
|
If <tt>error_cb</tt> is NULL, the default
|
|
error callback is used. It prints a message to the standard error stream.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns a handle to the file or NULL on error.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: <tt>Error_cb</tt> is of type <tt>void
|
|
(*p_ply_error_cb)(p_ply ply, const char *message)</tt>.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: This function is declared in header <tt>rplyfile.h</tt>.
|
|
</p>
|
|
|
|
<!-- ply_get_ply_user_data ++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_ply_user_data>
|
|
int <b>ply_get_ply_user_data</b>(p_ply_ply ply, void *pdata, long *idata)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Retrieves user data from the ply handle.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is the handle passed to the error callback.
|
|
<tt>Pdata</tt> receives the user data pointer.
|
|
<tt>Idata</tt> receives the user data integer.
|
|
<tt>Pdata</tt> and <tt>idata</tt> can be NULL.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
|
|
<!-- ply_read_header +++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_read_header>
|
|
int <b>ply_read_header</b>(p_ply ply)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Reads and parses the header of a PLY file.
|
|
After a call to this function, the query functions
|
|
<a href=#ply_get_next_element><tt>ply_get_next_element</tt></a>,
|
|
<a href=#ply_get_next_property><tt>ply_get_next_property</tt></a>,
|
|
<a href=#ply_get_next_comment><tt>ply_get_next_comment</tt></a>, and
|
|
<a href=#ply_get_next_obj_info><tt>ply_get_next_obj_info</tt></a> can be
|
|
called. Callbacks can also be set with the
|
|
<a href=#ply_set_read_cb><tt>ply_set_read_cb</tt></a> function.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by <a
|
|
href=#ply_open><tt>ply_open</tt></a>.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_set_read_cb +++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_set_read_cb>
|
|
long <b>ply_set_read_cb</b>(<br>
|
|
p_ply ply,<br>
|
|
const char *element_name,<br>
|
|
const char *property_name,<br>
|
|
p_ply_read_cb read_cb,<br>
|
|
void *pdata,<br>
|
|
long idata<br>
|
|
)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Sets up the callback to be invoked when the value of a property is read.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by <a href=#ply_open><tt>ply_open</tt></a>.
|
|
<tt>Element_name</tt> and <tt>property_name</tt> are the names of the
|
|
element and property of interest. <tt>Read_cb</tt> is the callback
|
|
function. <tt>Pdata</tt> and <tt>idata</tt> are user data to be passed to
|
|
the callback function.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns the number of instances of the element of interest.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: <tt>Read_cb</tt> is of type
|
|
<tt>int (*p_ply_read_cb)(p_ply_argument argument)</tt>.
|
|
The callback should return 1 to continue the reading process,
|
|
or return 0 to abort.
|
|
|
|
<!-- ply_get_argument_element ++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_argument_element>
|
|
int <b>ply_get_argument_element</b>(<br>
|
|
p_ply_argument argument,<br>
|
|
p_ply_element *element,<br>
|
|
long *instance_index<br>
|
|
)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Retrieves element information from the callback argument.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Argument</tt> is the handle passed to the callback.
|
|
<tt>Element</tt> receives a handle to the element
|
|
originating the callback. <tt>Instance_index</tt> receives
|
|
the index of the instance of the element
|
|
being read. <tt>Element</tt> and <tt>instance_index</tt> can be NULL.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: further information can be obtained from <tt>element</tt> with a
|
|
call to <a href=#ply_get_element_info>ply_get_element_info</a>.
|
|
</p>
|
|
|
|
<!-- ply_get_argument_property +++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_argument_property>
|
|
int <b>ply_get_argument_property</b>(<br>
|
|
p_ply_argument argument,<br>
|
|
p_ply_property *property,<br>
|
|
long *length,<br>
|
|
long *value_index<br>
|
|
)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Retrieves property information from the callback argument.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Argument</tt> is the handle passed to the callback.
|
|
<tt>Property</tt> receives a handle to the property
|
|
originating the callback. <tt>Length</tt> receives the number
|
|
of values in the list property (1 for scalar properties).
|
|
<tt>Value_index</tt> receives the index of the current property entry (0 for
|
|
scalar properties, -1 for the first value of a list property, the one that
|
|
gives the number of entries). <tt>Property</tt>, <tt>length</tt> and
|
|
<tt>value_index</tt> can be NULL.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: further information can be obtained from <tt>property</tt> with a
|
|
call to <a href=#ply_get_property_info>ply_get_property_info</a>.
|
|
</p>
|
|
|
|
<!-- ply_get_argument_user_data +++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_argument_user_data>
|
|
int <b>ply_get_argument_user_data</b>(p_ply_argument argument, void *pdata,
|
|
long *idata)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Retrieves the user data from the callback argument.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Argument</tt> is the handle passed to the callback.
|
|
<tt>Pdata</tt> receives the user data pointer.
|
|
<tt>Idata</tt> receives the user data integer.
|
|
<tt>Pdata</tt> and <tt>idata</tt> can be NULL.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_get_argument_value +++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_argument_value>
|
|
double <b>ply_get_argument_value</b>(p_ply_argument argument)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Retrieves the property value from the callback argument.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Argument</tt> is the handle passed to the callback.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns the property value.
|
|
</p>
|
|
|
|
<!-- ply_read +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_read>
|
|
int <b>ply_read</b>(p_ply ply)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Reads all data in file, calling appropriate callbacks.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by <a href=#ply_open><tt>ply_open</tt></a>.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_get_next_element ++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_next_element>
|
|
p_ply_element <b>ply_get_next_element</b>(p_ply ply, p_ply_element last)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Iterates over all elements on the header of a PLY file.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by <a href=#ply_open><tt>ply_open</tt></a>.
|
|
<a href=#ply_read_header><tt>Ply_read_header</tt></a> must have been called
|
|
on the handle otherwise no elements will be found.
|
|
<tt>Last</tt> is NULL to retrieve the first element, and an element to
|
|
retrieve the next element.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns the next element, or NULL if no more elements.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: further information can be obtained from an element with a
|
|
call to <a href=#ply_get_element_info>ply_get_element_info</a>.
|
|
</p>
|
|
|
|
<!-- ply_get_next_property +++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_next_property>
|
|
p_ply_property <b>ply_get_next_property</b>(p_ply_element element, p_ply_property last)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Iterates over all properties of an element.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Element</tt> is an element handle.
|
|
<tt>Last</tt> is NULL to retrieve the first property, and a property to
|
|
retrieve the next property.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns the next property, or NULL if no more properties.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: further information can be obtained from a property with a
|
|
call to <a href=#ply_get_property_info>ply_get_property_info</a>.
|
|
</p>
|
|
|
|
<!-- ply_get_next_comment ++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_next_comment>
|
|
const char *<b>ply_get_next_comment</b>(p_ply ply, const char *last)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Iterates over all comments on the header of a PLY file.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by <a href=#ply_open><tt>ply_open</tt></a>.
|
|
<a href=#ply_read_header><tt>Ply_read_header</tt></a> must have been called
|
|
on the handle otherwise no comments will be found.
|
|
<tt>Last</tt> is NULL to retrieve the first comment, and a comment to
|
|
retrieve the next comment.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns the next comment, or NULL if no more comments.
|
|
</p>
|
|
|
|
<!-- ply_get_next_obj_info +++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_next_obj_info>
|
|
const char *<b>ply_get_next_obj_info</b>(p_ply ply, const char *last)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Iterates over all obj_infos on the header of a PLY file.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by <a href=#ply_open><tt>ply_open</tt></a>.
|
|
<a href=#ply_read_header><tt>Ply_read_header</tt></a> must have been called
|
|
on the handle otherwise no obj_infos will be found.
|
|
<tt>Last</tt> is NULL to retrieve the first obj_info, and a obj_info to
|
|
retrieve the next obj_info.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns the next obj_info, or NULL if no more obj_infos.
|
|
</p>
|
|
|
|
<!-- ply_get_element_info ++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_element_info>
|
|
int <b>ply_get_element_info</b>(p_ply_element element, const char** name,
|
|
long *ninstances)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Retrieves information from an element handle.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Element</tt> is the handle of the element of interest.
|
|
<tt>Name</tt> receives the internal copy of the element name.
|
|
<tt>Ninstances</tt> receives the number of instances of this element
|
|
in the file. Both <tt>name</tt> and <tt>ninstances</tt> can be NULL.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_get_property_info +++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_get_property_info>
|
|
int <b>ply_get_property_info</b>(<br>
|
|
p_ply_property property,<br>
|
|
const char** name,<br>
|
|
e_ply_type *type,<br>
|
|
e_ply_type *length_type,<br>
|
|
e_ply_type *value_type<br>
|
|
)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Retrieves information from a property handle.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Property</tt> is the handle of the property of interest.
|
|
<tt>Name</tt> receives the internal copy of the property name.
|
|
<tt>Type</tt> receives the property type.
|
|
<tt>Length_type</tt> receives the scalar type of the first entry
|
|
in a list property (the one that gives the number of entries).
|
|
<tt>Value_type</tt> receives the scalar type of the remaining list entries.
|
|
<tt>Name</tt>, <tt>type</tt>, <tt>length_type</tt>, and
|
|
<tt>value_type</tt> can be NULL.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: <tt>Length_type</tt> and <tt>value_type</tt> can
|
|
receive any of the constants for scalar types defined in
|
|
<tt>e_ply_type</tt>. <tt>Type</tt> can, in addition, be <tt>PLY_LIST</tt>,
|
|
in which case the property is a list property and the fields
|
|
<tt>length_type</tt> and <tt>value_type</tt> become meaningful.
|
|
</p>
|
|
|
|
<!-- ply_create ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_create>
|
|
p_ply <b>ply_create</b>(const char *name, e_ply_storage_mode storage_mode,
|
|
p_ply_error_cb error_cb)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates a PLY file for writing.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Name</tt> is the file name, <tt>storage_mode</tt> is the file storage mode
|
|
(<tt>PLY_ASCII</tt>, <tt>PLY_LITTLE_ENDIAN</tt>,
|
|
<tt>PLY_BIG_ENDIAN</tt>, or <tt>PLY_DEFAULT</tt> to
|
|
automatically detect host endianess).
|
|
<tt>Error_cb</tt> is a function to be called when an error is found.
|
|
Arguments <tt>idata</tt>
|
|
and <tt>pdata</tt> are available to the error callback via the
|
|
<a href=#ply_get_ply_user_data><tt>ply_get_ply_user_data</tt></a>
|
|
function.
|
|
If <tt>error_cb</tt> is NULL, the default
|
|
error callback is used. It prints a message to the standard error stream.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns a handle to the file or NULL on error.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: <tt>Error_cb</tt> is of type <tt>void
|
|
(*p_ply_error_cb)(const char *message)</tt>
|
|
</p>
|
|
|
|
<!-- ply_create_to_file ++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_create_to_file>
|
|
p_ply <b>ply_create_to_file</b>(FILE *file_pointer, e_ply_storage_mode storage_mode, p_ply_error_cb error_cb)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates a PLY file to be written to a FILE pointer and
|
|
returns a handle to it.
|
|
The handle can be used wherever a handle returned by <a
|
|
href=#ply_create><tt>ply_create</tt></a> is accepted.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>File_pointer</tt> a pointer to a file open for writing, <tt>storage_mode</tt> is the file storage mode
|
|
(<tt>PLY_ASCII</tt>, <tt>PLY_LITTLE_ENDIAN</tt>,
|
|
<tt>PLY_BIG_ENDIAN</tt>, or <tt>PLY_DEFAULT</tt> to
|
|
automatically detect host endianess).
|
|
<tt>Error_cb</tt> is a function to be called when an error is found.
|
|
Arguments <tt>idata</tt>
|
|
and <tt>pdata</tt> are available to the error callback via the
|
|
<a href=#ply_get_ply_user_data><tt>ply_get_ply_user_data</tt></a>
|
|
function.
|
|
If <tt>error_cb</tt> is NULL, the default
|
|
error callback is used. It prints a message to the standard error stream.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns a handle to the file or NULL on error.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: <tt>Error_cb</tt> is of type <tt>void
|
|
(*p_ply_error_cb)(const char *message)</tt>
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: This function is declared in header <tt>rplyfile.h</tt>.
|
|
</p>
|
|
|
|
<!-- ply_add_element +++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_add_element>
|
|
int <b>ply_add_element</b>(p_ply ply, const char *name, long ninstances)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Adds a new element to the ply file.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by
|
|
<a href=#ply_create><tt>ply_create</tt></a>, <tt>name</tt> is the element
|
|
name and <tt>ninstances</tt> is the number of instances of this element that
|
|
will be written to the file.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_add_property ++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_add_property>
|
|
int <b>ply_add_property</b>(<br>
|
|
p_ply ply,<br>
|
|
const char *name,<br>
|
|
e_ply_type type,<br>
|
|
e_ply_type length_type,<br>
|
|
e_ply_type value_type<br>
|
|
)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Adds a new property to the last element added to the ply file.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by
|
|
<a href=#ply_create><tt>ply_create</tt></a> and <tt>name</tt> is the
|
|
property name.
|
|
<tt>Type</tt> is the property type.
|
|
<tt>Length_type</tt> is the scalar type of the first entry
|
|
in a list property (the one that gives the number of entries).
|
|
<tt>Value_type</tt> is the scalar type of the remaining list entries.
|
|
If <tt>type</tt> is not <tt>PLY_LIST</tt>, <tt>length_type</tt> and
|
|
<tt>value_type</tt> are ignored.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: <tt>Length_type</tt> and <tt>value_type</tt> can
|
|
be any of the constants for scalar types defined in
|
|
<tt>e_ply_type</tt>. <tt>Type</tt> can, in addition, be <tt>PLY_LIST</tt>,
|
|
in which case the property is a list property and the fields
|
|
<tt>length_type</tt> and <tt>value_type</tt> become meaningful.
|
|
</p>
|
|
|
|
<!-- ply_add_list_property ++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_add_list_property>
|
|
int <b>ply_add_list_property</b>(<br>
|
|
p_ply ply,<br>
|
|
const char *name,<br>
|
|
e_ply_type length_type,<br>
|
|
e_ply_type value_type<br>
|
|
)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Same as <a href=#ply_add_property><tt>ply_add_property</tt></a> if
|
|
<tt>type</tt> is <tt>PLY_LIST</tt>.
|
|
</p>
|
|
|
|
<!-- ply_add_scalar_property +++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_add_scalar_property>
|
|
int <b>ply_add_scalar_property</b>(p_ply ply, const char *name, e_ply_type type)
|
|
</p>
|
|
|
|
<p class=description>
|
|
Same as <a href=#ply_add_property><tt>ply_add_property</tt></a> if
|
|
<tt>type</tt> is <em>not</em> <tt>PLY_LIST</tt>.
|
|
</p>
|
|
|
|
<!-- ply_add_comment +++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_add_comment>
|
|
int <b>ply_add_comment</b>(p_ply ply, const char *comment);
|
|
</p>
|
|
|
|
<p class=description>
|
|
Adds a comment to a PLY file.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by
|
|
<a href=#ply_create><tt>ply_create</tt></a> and <tt>comment</tt> is the
|
|
comment text.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_add_obj_info ++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_add_obj_info>
|
|
int <b>ply_add_obj_info</b>(p_ply ply, const char *obj_info);
|
|
</p>
|
|
|
|
<p class=description>
|
|
Adds a obj_info to a PLY file.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by
|
|
<a href=#ply_create><tt>ply_create</tt></a> and <tt>obj_info</tt> is the
|
|
obj_info text.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_write_header ++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_write_header>
|
|
int <b>ply_write_header</b>(p_ply ply);
|
|
</p>
|
|
|
|
<p class=description>
|
|
Writes the PLY file header to disk, after all elements, properties,
|
|
comments and obj_infos have been added to the handle.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by
|
|
<a href=#ply_create><tt>ply_create</tt></a> and <tt>comment</tt> is the
|
|
comment text.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_write +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_write>
|
|
int <b>ply_write</b>(p_ply ply, double value);
|
|
</p>
|
|
|
|
<p class=description>
|
|
Passes a value to be stored in the PLY file.
|
|
Values must be passed in the order they will appear in the file.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by
|
|
<a href=#ply_create><tt>ply_create</tt></a> and <tt>value</tt> is the
|
|
value to be stored. For simplicity, values are always passed as
|
|
<tt>double</tt> and conversion is performed as needed.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- ply_close +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=ply_close>
|
|
int <b>ply_close</b>(p_ply ply);
|
|
</p>
|
|
|
|
<p class=description>
|
|
Closes the handle and ensures that all resources have been freed and data
|
|
have been written.
|
|
</p>
|
|
|
|
<p class=arguments>
|
|
<tt>Ply</tt> is a handle returned by
|
|
<a href=#ply_create><tt>ply_create</tt></a> or by
|
|
<a href=#ply_open><tt>ply_open</tt></a>.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns 1 in case of success, 0 otherwise.
|
|
</p>
|
|
|
|
<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<div class=footer>
|
|
<hr>
|
|
<center>
|
|
<p>
|
|
<small>
|
|
Last modified by Diego Nehab on <br>
|
|
Fri Aug 21 17:11:09 BRT 2015
|
|
</small>
|
|
</p>
|
|
</center>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|