vrml1to97/README.md

# vrml1to97

JavaScript converter from VRML 1.0 to VRML97 file format.

This converter was originally a JavaScript reimplementation of the algorithm
of the "token rearranger" found in the
[Wings 3D x3d importer](https://github.com/dgud/wings/blob/master/plugins_src/import_export/x3d_import.erl)
(which was written in Erlang).

However, from version 0.3, it adds support for a significantly larger subset of
VRML 1.0. Overall, it recognizes and converts

  * Title, SceneInfo, BackgroundColor, and View "Info" nodes [this node type
    was removed in VRML97].
  * All Light nodes
  * Grouping nodes including Separator, Group, Switch, and WWWAnchor
  * ShapeHints
  * Transformation nodes including Translation, Rotation, Scale, and Transform
  * All shape nodes including Cube, Cone, Cylinder, Sphere, IndexedFaceSet,
    IndexedLineSet, PointSet, Coordinate3, and Normal
  * All material nodes including Material, TextureCoordinate2, and Texture2
  * DEF and USE constructs to share subtrees

## Usage

From an es6 module under Node (for example)

```js
import {convert} from 'vrml1to97'
const vrml1spec = '# VRML 1.0 ....'
const vrml97spec = convert(vrml1spec)
```

or from a script in a webpage

```js
(async () => {
   const vrml1to97 = await import('./dist/vrml1to97/index.js')
   const vrml1spec = '# VRML 1.0 ....'
   const vrml97spec = vrml1to97.convert(vrml1spec)
})()
```

or from the command line via node

```shell
npx vrml1to97 < old.wrl > shinynew.wrl
```

## API

Currently this package exports just two functions:

 * convert(vrml1: string, source?: string): string

   The main function, takes in VRML 1 syntax (note that it does not
   actually check that its input is VRML 1, so its behavior is undefined
   if given anything but valid VRML 1 syntax). Returns VRML 97 syntax for
   the same scene, as nearly as it can translate. Note that not all of
   VRML 1 is recognized (see above for a list of constructs that should
   be handled), and some of the translations may be somewhat approximate.

   If the optional second argument `source` is supplied, `convert` adds
   a comment indicating that the original vrml1 came from the specified
   source, before conversion to VRML97.

 * tree97(vrml1: string): Tree

   Takes the same input as convert, but rather than returning a string, it
   returns a very rough syntax tree for the converted VRML97 scene. The
   returned Tree data structure is an object whose keys are property names
   and whose values are lists of either strings or sub-Trees. Note however
   that this syntax tree does not represent a complete parse; since VRML 1
   and VRML97 are close, whole blocks of syntax are left as strings rather
   than broken into node names and property values. If there is a need to
   generate XML syntax output, for example, the code would need to be
   modified to break the tree down further to be ready for conversion to XML.

## Conversion notes

One sort of geometry common to VRML 1 and VRML97 is the IndexedFaceSet. These
entities are often used to render solids. Indeed, the default in VRML97 is to
assume they do represent a solid, with the normals pointing outward. Unusual
visual effects ensue if the normals are not properly directed (basically, you
see through the "front" of the solid and see the "backs" of the faces on the
opposite side).

As a result, unless the input VRML 1 explicitly includes an explicit
vertexOrdering of CLOCKWISE or COUNTERCLOCKWISE, the default solid treatment
will be turned off in the VRML97 output, meaning that all faces will be
rendered opaque in both directions.