Update of /cvsroot/cgkit/cgkit2/doc/tex
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4748/tex
Modified Files:
cgkit.tex flockofbirds.tex polyhedrongeom.tex rmmaterial.tex
slots.tex worldobject.tex
Added Files:
mayaascii.tex plyexport.tex plyimport.tex rmlightsource.tex
Log Message:
Update
--- NEW FILE: rmlightsource.tex ---
% SpotLight3DS
\section{\class{RMLightSource} ---
RenderMan light source}
\begin{classdesc}{RMLightSource}{name = "RMLightSource",\\
shader = None
}
\var{shader} specifies the light shader that should be used. It
can either be a string containing the shader name or a \class{RMShader}
instance representing the shader (see section \ref{rmshader}).
\end{classdesc}
The parameters of the shader is made available as attributes of the
light source object. The corresponding slots can be obtained by adding
the suffix \code{_slot} to the name.
Index: worldobject.tex
===================================================================
RCS file: /cvsroot/cgkit/cgkit2/doc/tex/worldobject.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** worldobject.tex 10 Feb 2005 17:56:23 -0000 1.2
--- worldobject.tex 3 May 2005 13:42:39 -0000 1.3
***************
*** 174,178 ****
\begin{methoddesc}{setOffsetTransform}{P}
Set the offset transformation. The transformation has to be given
! relative to the local object transformation.
\end{methoddesc}
--- 174,181 ----
\begin{methoddesc}{setOffsetTransform}{P}
Set the offset transformation. The transformation has to be given
! relative to the local object transformation. After setting the offset
! transformation, the transform slot will be updated so that
! \method{localTransform()} returns the same matrix as before, i.e. the
! world position/orientation of the object does not change.
\end{methoddesc}
--- NEW FILE: mayaascii.tex ---
\section{\module{mayaascii} ---
Reading Maya ASCII files}
\declaremodule{extension}{cgkit.mayaascii}
\modulesynopsis{Reading Maya ASCII files}
This module contains the \class{MAReader} class which can be used as a
base class for reading Maya ASCII files. The class reads the file
and invokes callback methods with the corresponding data in the
file. Derived classes have to implement those callback methods and
process the data as appropriate.
%----------------------------------------------------------------
\subsection{MAReader class}
The \class{MAReader} class reads Maya ASCII files and calls
appropriate methods which have to be implemented in a derived class.
The content of the file is actually a subset of the {\em Maya Embedded
Language} (MEL) which is the scripting language implemented inside
Maya. The \class{MAReader} parses the file, breaks down the content
of the file in commands and their arguments and options (expressions
are not evaluated). Each MEL command will then trigger a callback
method that has to execute the command. These callback methods have
to be implemented in a derived class.
There are 11 MEL commands that can appear in a Maya ASCII
file\footnote{Actually, there could appear any MEL command, but at least
Maya will only export files containing the above commands.}:
\begin{itemize}
\item {\tt file}
\item {\tt requires}
\item {\tt fileInfo}
\item {\tt currentUnit}
\item {\tt createNode}
\item {\tt setAttr}
\item {\tt addAttr}
\item {\tt connectAttr}
\item {\tt disconnectAttr}
\item {\tt parent}
\item {\tt select}
\end{itemize}
Each command has a number of arguments and can also take options. The
callback methods receive the arguments as regular arguments to the
method and the options as an additional argument \code{opts} which is
a dictionary containing the options that were specified in the
file. The key is the long name of the option (without leading dash)
and the value is a list of strings containing the option values. The
number of values and how they have to be interpreted depend on the
actual option.
\begin{classdesc}{MAReader}{}
Creates an instance of the reader.
\end{classdesc}
\begin{methoddesc}{read}{f}
Read the content of a file. \var{f} must be a file like object that
can be used to read the content of the file.
\end{methoddesc}
\begin{methoddesc}{begin}{}
Callback method that is called before the file is read.
\end{methoddesc}
\begin{methoddesc}{end}{}
Callback method that is called after the file was read.
\end{methoddesc}
\begin{methoddesc}{onFile}{filename, opts}
Reference an external file.
\end{methoddesc}
\begin{methoddesc}{onRequires}{product, version}
Specify a requirement that is needed to load the file properly.
\var{product} is a string containing the required software component
and \var{version} is a string containing the required version of that
component.
\end{methoddesc}
\begin{methoddesc}{onFileInfo}{keyword, value, opts}
Specifies information about the file. \var{keyword} and \var{value}
are both strings.
\end{methoddesc}
\begin{methoddesc}{onCurrentUnit}{opts}
Specify the units (linear, angular, time) used in the file.
\end{methoddesc}
\begin{methoddesc}{onCreateNode}{nodetype, opts}
Create a new node. \var{nodetype} is a string specifying the type of node
that is to be created. The new node will automatically be selected (i.e.
subsequent setAttr commands refer to this node).
\end{methoddesc}
\begin{methoddesc}{onSetAttr}{attr, vals, opts}
Set a node attribute. \var{attr} is a string containing the attribute
to be set. \var{vals} is a list of values. The number of elements and
the type of each element depends on the attribute.
\end{methoddesc}
\begin{methoddesc}{onAddAttr}{opts}
Add a new attribute to the node.
\end{methoddesc}
\begin{methoddesc}{onConnectAttr}{srcattr, dstattr, opts}
Connect two attributes. \var{srcattr} is a string specifiying the
attribute that serves as a source and \var{dstattr} is the name of
the attribute that will receive the value.
\end{methoddesc}
\begin{methoddesc}{onDisconnectAttr}{srcattr, dstattr, opts}
Break the attribute connection between two attributes.
\end{methoddesc}
\begin{methoddesc}{onParent}{objects, parent, opts}
Set the parent of one or more nodes. \var{objects} is a list of node names
and \var{parent} the name of the parent.
\end{methoddesc}
\begin{methoddesc}{onSelect}{objects, opts}
Select a node from a referenced file. \var{objects} is a list of strings
containing the node names.
\end{methoddesc}
%----------------------------------------------------------------
\subsection{Node class}
\begin{classdesc}{Node}{nodetype, opts}
\var{nodetype} and \var{opts} are the arguments of the
\method{onCreateNode()} callback of the \class{MAReader} class.
\end{classdesc}
\begin{methoddesc}{getName}{}
Return the name of the node or \code{None} if no name was specified.
\end{methoddesc}
\begin{methoddesc}{getParentName}{}
Return the name of the parent node or \code{None} if no parent was specified.
\end{methoddesc}
\begin{methoddesc}{setAttr}{attr, vals, opts}
\var{attr}, \var{vals} and \var{opts} are the arguments of the
\method{onSetAttr()} callback of the \class{MAReader} class. The Python
value of an attribute can be obtained by calling \method{getAttrValue()}.
\end{methoddesc}
\begin{methoddesc}{addAttr}{opts}
\var{opts} is the arguments of the \method{onAddAttr()} callback of
the \class{MAReader} class.
\end{methoddesc}
\begin{methoddesc}{addInConnection}{localattr, node, attrname}
\end{methoddesc}
\begin{methoddesc}{addOutConnection}{localattr, node, nodename, attrname}
\end{methoddesc}
\begin{methoddesc}{getAttrValue}{lname, sname, type, n=1, default=None}
\end{methoddesc}
\begin{methoddesc}{getInNode}{lname, sname}
\end{methoddesc}
\begin{methoddesc}{getOutAttr}{lname, sname, dstnodetype}
\end{methoddesc}
%----------------------------------------------------------------
\subsection{Attribute class}
\begin{classdesc}{Attribute}{attr, vals, opts}
\var{attr}, \var{vals} and \var{opts} are the arguments of the
\method{onSetAttr()} callback of the \class{MAReader} class.
\end{classdesc}
\begin{methoddesc}{getBaseName}{}
Return the base name of the attribute. This is the first part of the
attribute name (and may actually refer to another attribute).
\begin{verbatim}
".t" -> "t"
".ed[0:11]" -> "ed"
".uvst[0].uvsn" -> "uvst"
\end{verbatim}
\end{methoddesc}
\begin{methoddesc}{getFullName}{}
Return the full attribute specifier.
\end{methoddesc}
\begin{methoddesc}{getValue}{type=None, n=None}
Return the value of the attribute as appropriate Python value.
\var{type} is a string containing the required type of the value.
If \code{None} is passed, the method tries to retrieve the value from
the attribute itself. If it fails, an exception is thrown. The following
table lists the valid type strings and their corresponding Python type:
\begin{tableii}{l|l}{code}{type}{Python type}
\lineii{"bool"}{bool}
\lineii{"int"}{int}
\lineii{"float"}{float}
\lineii{"string"}{str}
\lineii{"short2"}{(int, int)}
\lineii{"short3"}{(int, int, int)}
\lineii{"long2"}{(int, int)}
\lineii{"long3"}{(int, int, int)}
\lineii{"int32Array"}{[int, ...]}
\lineii{"float2"}{(float, float)}
\lineii{"float3"}{(float, float, float)}
\lineii{"double2"}{(float, float)}
\lineii{"double3"}{(float, float, float)}
\lineii{"doubleArray"}{[float, ...]}
\lineii{"polyFaces"}{PolyFace (see \ref{polyface})}
\end{tableii}
The argument \var{n} specifies how many values are expected. An exception
is thrown if the number of values that were set by the \code{setAttr} call
doesn't match the required number. If \code{None} is passed, an arbitrary
number of values is allowed. The value of \var{n} also influences the
return type. If the value is 1 the method will return one of the types
in the above table, otherwise it will return a list of the above types.
\end{methoddesc}
%----------------------------------------------------------------
\subsection{PolyFace class}
\label{polyface}
\begin{classdesc*}{PolyFace}
This class stores the data of a polygonal face. \class{PolyFace} objects
are returned when the value of a \code{polyFaces} attribute is requested.
\end{classdesc*}
The class has the following data members:
\begin{memberdesc}{f}
This is a list of integers containing the edge indices of the edges
making up the face. If an index is negative the edge has to be
reversed (the edge index then is -i-1).
\end{memberdesc}
\begin{memberdesc}{h}
This is a list of integers containing the edge indices of the edges
making up a hole in the face. If an index is negative the edge has to be
reversed (the edge index then is -i-1).
\end{memberdesc}
\begin{memberdesc}{mf}
Texture coordinate ids of the face. This data type is obsolete as of
Maya version 3.0. It is replaced by "mu".
\end{memberdesc}
\begin{memberdesc}{mh}
Texture coordinate ids of the hole. This data type is obsolete as of
Maya version 3.0. It is replaced by "mu".
\end{memberdesc}
\begin{memberdesc}{mu}
This is a 2-tuple (\var{uvset}, \var{ids})....
...(todo: this should be a list as there can be more than one uv sets)...
\end{memberdesc}
\begin{memberdesc}{fc}
Color index values for the face.
\end{memberdesc}
--- NEW FILE: plyimport.tex ---
% PLY import
\subsection{Polygon (PLY) import}
\begin{notice}[note]
The plugin uses the RPly library which is available at \url{http://www.cs.princeton.edu/~diego/professional/rply/}.
\begin{verbatim}
RPly 1.01 license
Copyright © 2003-2005 Diego Nehab.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
\end{verbatim}
\end{notice}
Index: slots.tex
===================================================================
RCS file: /cvsroot/cgkit/cgkit2/doc/tex/slots.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** slots.tex 15 Apr 2005 13:32:50 -0000 1.3
--- slots.tex 3 May 2005 13:42:39 -0000 1.4
***************
*** 99,102 ****
--- 99,112 ----
Connect the output of this slot with the input of \var{slot}.
Calling this method is equivalent to calling \code{slot.setController(self)}.
+ The method has no effect if \var{slot} is \code{None}.
+ \end{methoddesc}
+
+ % disconnect
+ \begin{methoddesc}{disconnect}{slot}
+ Breaks an existing connection between this slot and \var{slot}.
+ Calling this method is equivalent to calling \code{slot.setController(None)}.
+ The method checks if the connection actually exists before breaking it.
+ If it does not exist, a \exception{ValueError} exception is raised.
+ The method has no effect if \var{slot} is \code{None}.
\end{methoddesc}
Index: polyhedrongeom.tex
===================================================================
RCS file: /cvsroot/cgkit/cgkit2/doc/tex/polyhedrongeom.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** polyhedrongeom.tex 15 Apr 2005 13:32:50 -0000 1.1
--- polyhedrongeom.tex 3 May 2005 13:42:39 -0000 1.2
***************
*** 38,41 ****
--- 38,46 ----
\end{methoddesc}
+ \begin{methoddesc}{getNumVerts}{poly, loop}
+ Return the number of vertex indices in one particular loop. \var{poly}
+ is the polygon index and \var{loop} the loop index.
+ \end{methoddesc}
+
\begin{methoddesc}{setNumPolys}{num}
Allocate space for \var{num} polygons.
Index: cgkit.tex
===================================================================
RCS file: /cvsroot/cgkit/cgkit2/doc/tex/cgkit.tex,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
*** cgkit.tex 15 Apr 2005 13:54:06 -0000 1.13
--- cgkit.tex 3 May 2005 13:42:38 -0000 1.14
***************
*** 104,107 ****
--- 104,108 ----
\input{bvh.tex}
\input{objmtl.tex}
+ \input{mayaascii.tex}
%---
***************
*** 173,176 ****
--- 174,178 ----
\input{glfreedistantlight.tex}
\input{spotlight3ds.tex}
+ \input{rmlightsource.tex}
\input{ribarchive.tex}
\input{odejoints.tex}
***************
*** 211,214 ****
--- 213,217 ----
\input{offexport.tex}
\input{objexport.tex}
+ \input{plyexport.tex}
\section{Import plugins \label{importplugins}}
***************
*** 222,225 ****
--- 225,229 ----
\input{asfamcimport.tex}
\input{bvhimport.tex}
+ \input{plyimport.tex}
%---------------------------------------------------------
--- NEW FILE: plyexport.tex ---
% PLY export
\subsection{Polygon (PLY) export}
The PLY format that this plugin exports is the format that was developed at
Stanford University and that stores a polygonal model together with arbitrary
user attributes.
The plugin supports the following options that can be passed to
the \function{save()} command:
\begin{tableiii}{l|l|l}{code}{Option}{Default}{Description}
\lineiii{object}{\code{None}}{The object to export}
\lineiii{mode}{\code{"ascii"}}{The output mode}
\end{tableiii}
\var{object} is the name of an object or the object itself that will
be exported. If no object is given, the plugin examines the scene and
if there is only one object this object is exported. If there are several
objects, an exception is thrown.
\var{mode} is a string specifying whether the output file will be ascii or
binary. It can be one of "ascii", "little_endian" or "big_endian".
\begin{notice}[note]
The plugin uses the RPly library which is available at
\url{http://www.cs.princeton.edu/~diego/professional/rply/}.
\begin{verbatim}
RPly 1.01 license
Copyright © 2003-2005 Diego Nehab.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
\end{verbatim}
\end{notice}
Index: flockofbirds.tex
===================================================================
RCS file: /cvsroot/cgkit/cgkit2/doc/tex/flockofbirds.tex,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** flockofbirds.tex 12 Dec 2004 14:31:46 -0000 1.1.1.1
--- flockofbirds.tex 3 May 2005 13:42:39 -0000 1.2
***************
*** 9,12 ****
--- 9,16 ----
sensor values of the individual birds via slots.
+ Note: Currently, the class assumes that an extended range controller is
+ used! (this means the position values have to be adjusted if you use the
+ tracker without an extended range controller)
+
\begin{classdesc}{FlockOfBirds}{name = "FlockOfBirds",\\
com_port = 0,\\
***************
*** 58,62 ****
\begin{itemize}
! \item \code{pos<n>_slot} (\code{Vec3Slot}) -- Position
\item \code{angle<n>_slot} (\code{Vec3Slot}) -- Euler angles
\item \code{matrix<n>_slot} (\code{Mat3Slot}) -- Rotation matrix
--- 62,66 ----
\begin{itemize}
! \item \code{pos<n>_slot} (\code{Vec3Slot}) -- Position (in cm)
\item \code{angle<n>_slot} (\code{Vec3Slot}) -- Euler angles
\item \code{matrix<n>_slot} (\code{Mat3Slot}) -- Rotation matrix
Index: rmmaterial.tex
===================================================================
RCS file: /cvsroot/cgkit/cgkit2/doc/tex/rmmaterial.tex,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** rmmaterial.tex 12 Dec 2004 14:31:54 -0000 1.1.1.1
--- rmmaterial.tex 3 May 2005 13:42:39 -0000 1.2
***************
*** 54,58 ****
The parameters of the shaders are made available as attributes of the
material objects. The corresponding slots can be obtained by adding
! the suffix \code{_slot} to the name. Attribut names in the surface shader
have priority over the attributes in the displacement shader which in
turn has priority over the interior shader. This means, if there are
--- 54,58 ----
The parameters of the shaders are made available as attributes of the
material objects. The corresponding slots can be obtained by adding
! the suffix \code{_slot} to the name. Attribute names in the surface shader
have priority over the attributes in the displacement shader which in
turn has priority over the interior shader. This means, if there are
***************
*** 80,83 ****
--- 80,84 ----
%------------------------------------------------------------
\subsection{\class{RMShader} --- RenderMan shader}
+ \label{rmshader}
The \class{RMShader} class encapsulates a single RenderMan shader.
|