POV-Stairs license

POV-Stairs consists primarily of the POV-Ray include file StairCase.inc and the POV-Ray example scene files. It also includes the StairCaseDoc.pov scene file which is used to generate the graphics included in this documentation. All of these files were written with the intention of making them freely available for future re-use in original or modified form. The original author retains copyright over the original work, but grants you a license to re-use the work in original or modified form. That license permits you to use the POV-Stairs files for recreational or commercial purposes, with or without credit being given to the author, provided that such re-use does not in any way prevent anybody else from using or modifying the original work and re-using the original work or a combination of the original work and their own modifications.

This means that you cannot claim original authorship of these files or the intellectual capital that they contain. Neither can you apply a copyright or conditions that would imply that others are not free to use the original files or the intellectual capital that they contain.

If you wish to retain ownership of changes that you make to the supplied files or of files that you add into POV-Stairs you should explicitly identify your contribution within the files. You are authorised to use images that are generated using these files and you are not required to give any credit to the original author for the contribution that the POV-Stairs files made to your work, although it is generally polite to do so where practicable.

POV-Stairs also includes HTML documentation describing the utility and its use. This documentation, the CSS (Cascading Style Sheets) and the JS (Javascript) files have also been written with the intention of making them freely available for future re-use in original or modified form. The original author retains copyright over the original work, but grants you a license to re-use the work in original or modified form. That license permits you to use the POV-Stairs documentation files for recreational or commercial purposes, with or without credit being given to the author, provided that such re-use does not in any way prevent anybody else from using or modifying the original work and re-using the original work or the original work with their own modifications.

Contributing files

The POV-Stairs distribution is designed to be extendable. It is hoped that others will add definitions for alternative shapes and forms to enable users to generate additional styles of staircase. You can contribute your own files for inclusion into the distribution. To enable your work to be included you will need to assert that you are the genuine author of the contributions that you are making and explicitly agree for your contributions to be distributed under the terms of the POV-Stairs license in perpetuity.

How POV-Stairs Works

The StairCase.inc file contains comments that are intended to help you to read the POV-Ray SDL (Scene Description Language). This section of the documentation is intended to provide a higher level view of the function. All of the staircase components described below are optional. Their presence or absence being controlled using the Control Switches described in the variables section of this documentation.

When you include the StairCase.inc file in your POV-Ray scene file it declares a number of objects, sets a number of variables and defines a couple of macros. The objects are the default components that will be used to create a staircase when you invoke the StairCase macro. When you invoke the StairCase macro it checks for the existence of various object definitions, texture definitions and control settings and sets default values for any variables it does not find. This includes default object definitions for any objects that you have not explicitly defined.

At each of the positions that you specify in the SCPostPositions array, the macro 'logically' positions a newel post. Based upon the newel post positions and the width of the stairs specified in the SCStairWidth variable it then add stairs and a banister rail on the opposite side of those stairs.

If more than two newel post positions are specified, the macro will repeat the process, creating the corresponding flights of stairs (2 flights for 3 newel posts, 3 flights for 4 newel posts). To fill any gaps between these flights of stairs the macro defines a prism object to represent a landing, calculating a shape based upon the three newel posts that define the ends of the two flights of stairs. If the angle between the two flights of stairs is above the threshold specified in the SCLandingThreshold variable then it adds a fourth newel post to help the landing to turn the corner.

Additional bannister rails are added around the edge of the landing.

Documentation Utilities

This HTML documentation uses cascading style sheets and the 'scdoc.js' file to simplify maintenance. Standard page component are generated using Javascript, including most of the table of contents entries. This enables the table of contents entries to be re-used in the main table of contents and in the table of contents for each section. The cascading style sheets support different formatting for displaying the document in a browser and for printing. For example, the text elements used to link back to the table of contents are suppressed in the printed version.

Updating this documentation is best accomplished using a standard text editor, taking care to respect the standards used. For example, the header level 2 tags are usually included in the table of contents (defined in the 'scdoc.js' file). The section numbers are generated as the contents of an 'A' tag, therefore the 'A' tag used to give a name to the heading should be empty, because any contents will be overwritten when the page loads and the section number is written into the tag.

The graphics for this document are all defined in the 'StairCaseDoc.pov' scene file to facilitate their regeneration. This scene file contains a scene for each image wrapped by an '#if () #end' statement. The following example shows the SDL for generating the image of the default newel post:

#if (ImageNumber = 45)
  #declare Image = "SCDefaultNewelPost";
  camera {location <1.45,1.2,-0.1> look_at <0,0.5,0>}
  light_source {AreaLight}

  #include "StairCase.inc"
  StairCase()
#end

The 'ImageNumber' variable is declared at the top of the file and can either be specified as a particular number to regenerate a single image:

#declare ImageNumber = 50;

or it can be assigned the value of the 'frame_number' variable to enable it to be used in conjunction with the command line options '+kfi0 +kff50' to regenerate all of the defined images in sequence.

#declare ImageNumber = frame_number;

In both cases the scene file writes out a windows batch file 'RenameImages.bat' that can be used to rename the images to give them meaningful names. The names defined in this batch file are taken from the image name as defined in the 'Image' variable for each image.