Wavefront OBJ Reader/Writer

Transcription

1 FME Readers and Writers 2013 SP1 Wavefront OBJ Reader/Writer The Obj Reader and Writer module enables FME to read and write the Wavefront Obj format. The Obj format, originally developed for use with Wavefront's Advanced Visualizer, is now used primarily to exchange 3D models between different modeling and rendering applications. Overview An Obj file consists of a main.obj file, that can reference an optional Material (.mtl) file. A format specification for Obj and the optional mtl file can be found here: Supported OBJ File Syntax The obj file format supports both polygonal and free-form surface objects. The Obj Reader/Writer currently supports polygonal face (f) objects (l) line and (p) point. Freeform surfaces are typically not used in.obj file exchange and are not supported at this time. For completeness, the syntax supported at this time is summarized below. v <x> <y> <z> Syntax and Description Vertex position. Coordinates are floating point numbers. vn <i> <j> <k> Vertex normal. Coordinates are floating point numbers. vt <u> <v> <w> Texture coordinate. <u> is the horizontal direction, <v> is the vertical direction (optional in the case of a 1D raster/texture, and defaults to 0), <w> is the depth in the case of a 3D raster/texture map (optional in the case of a 2D raster/texture, and defaults to 0). f <v1>/<vt1>/<vn1> <v2>/<vt2>/<vn2> <v3>/<vt3>/<vn3>... Faces are stored as a series of three or more vertices in clockwise order. Vertices are described by their position, optional texture coordinate, and optional normal, encoded as an integer index into the respective coordinate lists. A face is generally limited to triangle or quad planar surface. l <v1>/<vt1> <v2>/<vt2> <v3>/<vt3>... Lines are stored as a series of one ore more vertices and optional texture coor

2 Wavefront OBJ Reader/Writer Syntax and Description dinate. Textures are generally not mapped to lines but may be used to store tabular data or an index. p <v1> <v2> <v3>... Points are stored as a series of one or more vertices. mtllib <filename.mtl> Material (.mtl) file references the material file that defines the materials used in the object that follow. Material files contain color illumination components and texture filename references. usemtl <mtlname> Material name string tag that references the material to use for the faces that follow in the obj file. g <groupname1> <groupname2>... Group name string tag for the elements (faces) that follow. o <objectname> Object name string tag for the elements (faces) that follow. s <smoothgroup> Smoothgroup number to group elements together for smooth shading operations. File Name Extension.obj Contents Geometric data A single.obj file can contain many types of geometry. However, in practice obj files generally contain only faces. Obj files generally contain three-dimensional geometry. 2D data will be represented with one of the coordinates (generally y or z) being 0.0 for all geometry. Wavefront OBJ Quick Facts About Quick Facts Tables Format Type Identifier Reader/Writer Licensing Level Dependencies Dataset Type OBJ Both Professional ne Reader: File Writer: Directory

3 FME Readers and Writers 2013 SP1 Feature Type Typical File Extensions Automated Translation Support User-Defined Attributes Coordinate System Support Generic Color Support Spatial Index Schema Required Transaction Support Enhanced Geometry Encoding Support Geometry Type OBJ_ELEMENT.obj Yes Never Yes obj_type Geometry Support Geometry Supported? Geometry Supported? aggregate yes point yes circles no polygon yes circular arc no raster no donut polygon no solid no elliptical arc no surface yes ellipses no text no line yes z values yes none no Reader Overview The Obj reader produces FME features for geometry data in an obj file. The obj reader extracts all the geometry in an Obj file and then presents the elements one at a time to FME for further processing. Each obj element will create an FME feature. Reader Directives The directives processed by the OBJ reader are listed below. The suffixes shown are prefixed by the current <ReaderKeyword> in a mapping file. By default, the <ReaderKeyword> for the Obj reader is OBJ. DATASET Required/Optional: Required The value for this directive is the path to the obj file. OBJ_DATASET /usr/data/obj/teapot.obj

4 Wavefront OBJ Reader/Writer : Source Wavefront OBJ File MOVE_TO_WORLD_COORDSYS Possible values are 'Yes' and '' with default value being ''. If the value is 'Yes', the companion.prj and.wld files (having the same name as the.obj file) will be read in order to acquire the coordinate system and the data necessary in order to convert points to the world coordinate system. te that in the absence of a companion.wld file with the same name as the.obj file, a file named global.wld will be looked for in the same directory. Similarly for the companion.prj file, only in that case we will only look for a file named global.prj. : Move to World Coordinate System MERGE_MESH_PARTS If the value is Yes, the group name, object name, and smoothing group information will be lost for each face in the source file, and the corresponding FME feature will contain only one mesh that contains all of the faces from the source file. This results in a more efficient representation of the data if the user does not wish to keep the additional face information. The OBJ writer will maintain this information so it is recommended to leave this option set to "" for OBJ to OBJ translations. If the value is set to '', in the case that multiple group names, object names or smoothing groups are used, this information will be preserved as traits on multiple meshes containing faces that have been grouped by these values. Values Yes (default) Merge Mesh Parts SEARCH_ENVELOPE This directive specifies a bounding box used to filter the input features. Only features that interact with the bounding box are returned. Mapping File Syntax <ReaderKeyword>_SEARCH_ENVELOPE <minx> <miny> <maxx> <maxy> te: If all four coordinates of the search envelope are specified as zero, the search envelope will be disabled Required/Optional Optional

5 FME Readers and Writers 2013 SP1 Minimum X, Minimum Y, Maximum X, Maximum Y SEARCH_ENVELOPE_COORDINATE_SYSTEM This directive specifies the coordinate system of the search envelope if it is different than the coordinate system of the data. The COORDINATE_SYSTEM directive, which specifies the coordinate system associated with the data to be read, must always be set if the SEARCH_ENVELOPE_COORDINATE_SYS- TEM directive is set. If this directive is set, the minimum and maximum points of the search envelope are reprojected from the SEARCH_ENVELOPE_COORDINATE_SYSTEM to the reader COOR- DINATE_SYSTEM prior to applying the envelope. Required/Optional Optional Mapping File Syntax <ReaderKeyword>_SEARCH_ENVELOPE_COORDINATE_SYSTEM <coordinate system> Search Envelope Coordinate System CLIP_TO_ENVELOPE This directive specifies whether or not FME should clip features to the envelope specified in the SEARCH_ENVELOPE directive. Values YES NO (default) Mapping File Syntax <ReaderKeyword>_CLIP_TO_ENVELOPE [yes no] Clip To Envelope Writer Overview The Obj writer creates and writes feature data to an obj file. Any old Obj file in the directory is overwritten with the new Obj file with the same name. If the Obj file can not be written the translation fails

6 Wavefront OBJ Reader/Writer te: The maximum number of digits allowed after the decimal is 6. The writer will automatically truncate any extra digits. te: Some viewers may not correctly render OBJ files containing 64-bit precision of coordinates. The data within the OBJ file is still correct; however, if the primary concern is visualization instead of data precision, then offsetting the x,y,z coordinates such that the model's origin is moved to (0,0,0) or another point close to this should resolve the display issue. Writer Directives The directives that are processed by the Obj writer are listed below. The suffixes shown are prefixed by the current <WriterKeyword>_ in a mapping file. By default, the <WriterKeyword> for the Obj writer is OBJ. DATASET The value for this directive is the path to the output directory. If the output directory does not exist, then the writer will create a new directory. An output.obj file will be created for each feature type within the specified directory. For example, if you are writing to feature types named house and barn to dataset c:\data\obj then you will have files c:\data\obj\house.obj and c:\data\obj\barn.obj. One common mtl file will be created for the writer and shared by all output files. Feature type fanout is supported. Mapping File Syntax OBJ_DATASET c:\data\obj MATERIAL_LIB This option specifies a full path to a mtl file to use as the Material Library (mtllib) when creating an obj file during writing. Leave this blank if you do not have an existing material library or do not use materials in your obj model. te: Some obj viewer applications have been known to require that there are no spaces in the material file name. Default: Blank : Material Library File MATERIAL_LIB_LINKAGE This option specifies how the material library (.mtl) file is referenced during writing. Range: Relative Absolute Copy Default: Relative

7 FME Readers and Writers 2013 SP1 Relative - references the mtl file relative to the obj file. In this case, the mtl file will need to be placed in a directory that is relative to the obj file being created. The mtllib directive in the obj file will reference the mtl file using a relative path. Copy - makes a copy of the mtl file and places it in the same directory with the obj file. The mtllib directive in the obj file will reference this copy with no directory in the mtl path reference. te: This option will copy the.mtl file. However, if there are additional files referenced from the.mtl file such as texture files, they will not be copied and will need to be manually copied. Absolute - references the mtl file using a absolute location. The mtllib directive in the obj file will reference the template file using an absolute path. te: The Absolute reference will use the mtl file name as is specified with the MATERIAL_LIB key word which should itself specify an absolute path the the.mtl file. : Material Library Linkage REVERSE_FACE_ORDER This option forces faces and lines to be written in a reverse order. This option is useful when faces are all back faced when rendering only the front side and you need to reverse all faces. Range: Yes Default: : Reverse Face Order TRIANGULATE_FACES This option forces faces to be broken into triangles. Donuts and concave faces are always triangulated, regardless of whether this option is set. Required/Optional Optional Values Yes (default) Triangulate Faces WRITE_FME_VERSION

8 Wavefront OBJ Reader/Writer This option controls whether the writer creates a comment line specifiying the FME version that was used to create the resulting output obj file. Disabeling writing version information is useful to support regression tests. Range: Yes Default: Yes : Write FME Version to OBJ File Header WRITE_POINTS_AND_LINES This option controls whether the writer includes points and lines when writing to the output file. When this is set to, point and line features will be silently dropped. Some applications do not render points and lines and others do not accept the file if it contains them (eg. Autodesk 3ds Max). Range: Yes Default: : Write Points and Lines MOVE_TO_LOCAL_COORDSYS Possible values are 'Yes', '' and PRJ_ONLY with default value being ''. If the value is 'PRJ_ONLY', a companion.prj file containing the coordinate system and having the same name as the.obj file will be written in the same directory as the.obj file. If the value is Yes, in addition to writing the.prj file as in the PRJ_ONLY option, a companion.wld file with the same name as the.obj file will be written in the same directory as the.obj file and the coordinates of all the points in the written features will be normalized to the interval [-0.5, 0.5] on the largest side of their XY-bounding box. The other dimensions will be scaled proportionally. This can be used to improve precision of the written coordinates. : Move To Local Coordinate System TEXTURE_OUTPUT_FORMAT Allows the user to specify the preferred format for associated texture files. This preference will be used as long as the specified format supports the properties of the texture raster; if not, it will be overridden. In Auto mode, the writer will choose the best representation based on the incoming texture raster. Required/Optional Optional

9 FME Readers and Writers 2013 SP1 Values PNG JPEG GIF BMP Auto (default) Preferred Texture Format Feature Representation In addition to the generic FME feature attributes that FME Workbench adds to all features (see About Feature Attributes), this format adds the format-specific attributes described in this section. Obj elements (features) consist of geometry and geometry attributes. All obj elements have one predefined attribute, obj_type, which identifies the type of the geometry. Geometry types are 3D (x,y,z) and obj_face can contain texture and normal coordinates. See the FME Fundamentals help file (FME Architecture > FME 3D Support > Vertex rmalsand FME Architecture > FME 3D Support > Texture Coordinates). The format-specific data obj_group, obj_material_ref, obj_object, and obj_smooth_ group are treated as traits. All obj geometry attributes are optional. Attribute Name obj_type Value The type of geometry read from the table. This attribute will contain one of: obj_point obj_line obj_face obj_collection Default: default FME Geometry Attributes Supported These are attributes that map to the FME geometry model. Attribute Name fme_texture_coordinate_x fme_texture_coordinate_y Value These are named measures that hold texture coordinates on the vertices of obj_face. fme_texture_coordinate_z fme_vertex_normal_x fme_vertex_normal_y These are the named measures that hold obj_face vertex normal components. fme_vertex_normal_z

10