Overview

This collection is open to anyone who wishes to contribute their work. You'll need to register and login, but self-registration just takes a few minutes. Work you submit goes straight onto the site and becomes available to others. New submissions are not filtered through a moderator but are monitored and administrators will remove anything deemed inappropriate. Everything is under a standard, open license that authorises use, modification and redistribution, so you need to be willing and able to distribute your submission under such a license.

The 'Contribution' screen guides you through the submission process step-by-step. As you move the cursor from field to field a short piece of context-sensitive help is displayed at the top of the screen. In addition, most of the fields have an individual help button (a question mark '?' in a circle) that takes you straight to the relevant section of this manual. Mandatory fields are marked with an 'M' in a circle and change from Red to Green once you've filled them in. If you do anything wrong an error should immediately display in Red at the bottom of the screen and it won't let you hit the 'Submit Contribution' button until you've fixed such errors.

There are some easy-to-implement standards that help people to use different objects together in a single scene. There's an option that allows you to submit a non-compliant contribution (better than not submitting anything), but it helps people a lot if you can make your work compliant. The standards are mostly about naming things so that file names and identifier names don't clash. This can easily be achieved by prefixing your file names, variable names (both global and local), macro names etc. with a common prefix that consists of the name of your contribution, followed by the underscore '_'. Examples are given below.

All file names are converted to lowercase when they are uploaded onto the server to try to cope better with operating system differences with respect to case sensitivity in file names. Any references to file names within your POV scene and include files (and within any HTML documentation) should therefore consistently use lowercase.

You should test the files that you intend to submit before submitting them. Make sure that the set of files works together and doesn't require anything else. To subsequently update a submission with enhancements or fixes you'll need to create a new version, so that anyone who has downloaded it in between times can tell it's been updated.

Hopefully you will find the submission process pretty clear. If you do get stuck you can display the more detailed descriptions of the fields in the 'Submission Form' section of this document below. There's also a POV-Ray newsgroup dedicated to this collection at http://news.povray.org/povray.object-collection/ where you can ask questions or propose improvements.

Licensing

In order to submit a contribution to this collection you must be willing and able to agree to the terms of use and distribution covering this collection. All of the files from this collection are currently governed by the Creative Commons - Lesser General Purpose License (CC-GNU LGPL). CC-GNU LGPL
Before submitting any files to this collection you must:
  • Verify that you are entitled to grant permission for the distribution and use of all the files you contribute.
  • Grant the right to distribute the files you contribute under the terms of this license in perpetuity.
  • Grant the right in perpetuity for the use without restriction of images generated using the files you contribute.
  • Confirm that you have incorporated the following licensing statement into all .pov and .inc files that you submit:
       // This file is licensed under the terms of the CC-LGPL

The POV-Ray Team reserve the right to change the licensing conditions for the collection in the future, in which case anyone who has downloaded files under the CC-GNU LGPL will continue to be covered by that license or may choose to use the new license.

Preparing Files

We use a very small number of simple-to-implement standards designed to enable objects submitted by different people to be stored together in a single directory and to be used together in a single scene file without conflicting with one another (ie no naming collisions etc.). Although there's an option that allows you to submit non-compliant files it's preferable to submit compliant ones and normally doesn't take much more time to do.
File names should be prefixed with your contribution name or with a prefix name that is unique to your contribution. This needs to be followed directly by either an underscore ('_') or a period/dot ('.'). On this page we use the example of a contribution called 'Netball' where a unique prefix of 'NB' has been defined. See 'Files' below for examples of valid and invalid file names.
Variable names exposed to the user should also be prefixed with the contribution name or the unique prefix and should be directly followed by an underscore ('_'). This includes named objects, textures, pigments, normals etc. For example the 'Netball' object exposes the NB_BallRadius variable to enable the radius of the ball to be controlled. You may use the #local directive to define variables with a local context within macros etc., in which case you are not obliged to adhere to this naming standard within those macros, because the local context should avoid naming conflicts.
Macro names should all be prefixed with the contribution name or the unique prefix and should be directly followed by an underscore ('_'). For example the 'Netball' object exposes the NB_Netball() Macro which takes a single parameter defining the ball type ("Stitched" or "Moulded").
Function names should all be prefixed with the contribution name or the unique prefix and should be directly followed by an underscore ('_').

Files that you should submit

It's possible to just submit a single scene file or a single include file, but it's usually easy to also include a sample image and you can also add a variety of other files that can help people use your submission.

In the following examples it is assumed that you have an object called 'Netball' and have elected to use a unique prefix of 'NB'.
DescriptionExample
Main Contribution Files Most contributions will contain at least one scene file (a '.pov' file) and/or an include file (a '.inc' file). If your submission is really just an example of how to do something, you may choose to put it all in a single scene file. However, it is preferred that you submit Object/Macro/Texture/Function definitions as include files and provide a sample scene file to illustrate how the include file should be used. It is recommended that you use the full object name for the main files, but you can use the unique Prefix if you wish. netball.inc The main file in the contribution, this contains the principal Objects, Textures, Macros, Functions etc.
netball.pov A sample scene file illustrating how the include file can be used.
Other Scene/Include Files You can provide as many other scene files and/or include files as you wish. You could, for example have a macro in the main include file that assembles components from a variety of other include files. You can also provide a range of different scene files illustrating different features of your contribution. netball_valve.inc May be a component of the ball
netball_bag.inc Could be an accessory to the main file
netball_withlogo.pov Could illustrate how to apply an image file to the ball.
nb_example1.pov You can use the unique prefix in place of the contribution name.
Main Image Files You should provide a thumbnail image file with a Height of 120 pixels and a width of 160 pixels that will be displayed on the search results screen. You should also provide a larger sized image file ideally with a resolution of 800x600 or 640x480. Both images should be in a common compressed format (extensions jpg, jpe, jpeg, gif or png). These images are optional, but strongly encouraged.

The rule for getting the thumbnail to appear on the search page is that the file name must be just the contribution name/prefix name followed by '_thumbnail' and the file type for the thumbnail image file.

The rule for getting the thumbnail to hyperlink to a larger image is that the file name of the larger image must be just the contribution name/prefix name followed by the file type for the larger image file.

See the examples to the right.

netball_thumbnail.jpg or nb_thumbnail.jpg The thumbnail image to display on the search screen
netball.jpg or nb.jpg The full-sized image linked to from the thumbnail on the search screen
Other Image Files You can provide additional image files but they won't be displayed on the collection website unless you create an HTML document file to display them (see below). netball_withlogo.jpg or nb_example7.jpg Could be an additional images referenced in your documentation.
Documentation You can provide an HTML file containing additional information about your contribution. If you do (and you name it correctly) the search results for your contribution will incorporate a 'More Detail' link to enable the user to display that page. Your page can incorporate images and hyperlinks to other HTML pages that you submit or to other web sites.

If your HTML skills are not very good you can write plain text into an HTML file and it will still be displayed (you can use the '<P>' tag to throw a new paragraph here and there).

netball.html An optional HTML documentation file.

Other Files

When you download a contribution from the collection you get several files that have been automatically added by the server. When uploading a contribution you can simply ignore these files, but if you are replacing an existing contribution you may find the text files handy. These text files contain the object description, the keywords and the prerequisites (if there are any) defined for this copy of this contribution you downloaded. You cannot submit files with these three names, but there are buttons on the contribution page to allow you to load the text from these files into the relevant fields on the screen. By editing these files in advance you can take your time over them, simplifying the online process of submitting your contribution. This saves you from having to type the text into the form and therefore from the pressure of having to think up good text on the spot. Buttons are provided on the submission page to enable you to pull text in from these files. Alternatively you can cut and paste from any text editor directly into the form if you prefer.
DescriptionExample
Description The desciption of your object is very important as it enables people looking for things to determine whether or not your contribution meets their needs. You should attempt to write a short but detailed English language description. Remembering that English may not be the first language of people reading your description, so structure your sentences properly and make sure that what you write is not ambiguous or otherwise confusing.

For further information about how to use this file see the decription field below.

netball_description.txt A plain text file containing the description of the contribution.
Keywords Keywords and Key Phrases provide an important means by which people can find the files you are submitting when they search the collection. Althouth not visible on the collection web site, careful selection of appropriate words and phrases will significantly increase the likelihood that people will be able to find and use your submission.
As you prepare your contribution for submission, think of different keywords that will be appropriate and jot them down in this file as you go.

For further information about how to use this file see the keywords field below.

netball_keywords.txt A plain text file containing the search keywords and key phrases that will result in this contribution being found.
Prerequisites You should avoid prerequisites and dependencies wherever possible, but you may find that your contribution is dependant upon specific software, a specific operating system, a specific version of POV-Ray or that it relies upon other contributions or files available from other Internet sites. You should keep a note of such dependencies in this file so that you can record them as prerequirsites on the submissions page when you submit your contribution.

For further information about how to use this file see the prerequisites field below.

netball_prereqs.txt A plain text file containing the prerequisites for this contribution.
Readme, Script, Licence Logo These files are automatically copied into each download. You don't need to copy them back up to the server at all when you submit a contribution. README636176.html
Versions636176.js
cc-LGPL-a.png
Readme for this download.
Script file for this download.
Licensing Logo.

Submission Form

The submission form at is used to contribute objects to the collection. It provides step by step, field-level guidance and incorporates links to the field-level help contained in this section of the users guide. Generally you should complete the form by going through the screen fields in sequence as this provides the greatest level of error checking. Certain fields are mandatory and the 'Submit' button at the foot of the page will not activate until all mandatory fields are complete.

The following sections describe the information that needs to be entered into the contribution form field by field.

New/Existing One of the aims of this collection is to encourage the evolution of objects. The licensing permits the use, modification and redistribution of objects from the collection so that, if you find an object useful, you can develop it further and resubmit it to the collection. To keep track of this the server implements a versioning mechanism, so that previous versions are still held unaltered when an altered version of an object is submitted.
If you are submitting a brand new object to the collection that is not based on an earlier contribution, or if it is sufficiently distinct that it should be classed as a separate object, then select 'New' from the New/Existing pull-down.
If you are submitting an altered version of an object that already exists in the collection then select 'Existing' from the New/Existing pull-down.

There may well be times when it's difficult to decide whether to classify a contribution as a new object or whether it should be classed as an updated version of an existing object. Don't forget that you can discuss it with others on the POV-Ray newsgroups.

Contribution Name
Maximum Number of Characters: 40
Permitted Characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
Contributions are identified within the collection using a name that must be unique throughout the collection. For example the contribution name 'Netball' is used to refer to a POV-Ray object that represents a Netball. Different versions of this object can exist on the server, but those versions should all be progressive enhancements to the same object, supporting additional features and options.
When submitting a new object you should pick a new name. If you find an object with that name exists, then, unless you wish to put in the work to make it compatible with the existing object, you should pick a different name. If you, for example, create a netball object that is not based on the object already called Netball, then you could choose a different name e.g. Netball_pgd, or you could look at what the existing object does and combine the best of both to develop something with all of the capabilities of both your Netball and the existing netball, in which case you could upload it using the existing name 'Netball', recording it with a different version number.
Unique Prefix (Optional)
Maximum Number of Characters: 40
Permitted Characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
In order to reduce naming conflicts and to enable different objects to more easily be used in combination within a single scene, your contribution needs to adhere to the naming standards which require file names and externaly exposed macro and variable names (named objects, textures, control variables etc.) to all start with the same prefix, followed by an underscore (or a period for file names - e.g. netball.jpg or netball_thumbnail.jpg).
You can choose to use the full object name as a prefix or you can optionally reserve a separate unique prefix. For example, the Netball contribution uses the full contribution name 'Netball' to prefix all files, but uses the letters 'NB' as a prefix internally, with NB_BallRadius being used to control the radius of the Netball and NB_BallTexture being used to control its surface texture.
Optional Unique Prefixes must be unique across the collection and must not be the same as any contribution name. The name check ignores case (so NB=nb=nB=Nb). If you find that the prefix you would really like to use is already being used for another contribution, consider appending a number to the prefix e.g. NB2.
Using an underscore between the prefix and the rest of the name is require as it makes it possible for abbreviations of existing names to be used for other objects. For example, the name 'Net' could still be used for an object even when 'Netball' is already being used for a different object. Hint - this also makes it very easy to do a global change throughout one or more files.
Standards Compliance You are asked to make a reasonable assessment as to how closely your contribution follows the standards. When searching the collection, anything that is less than a '3', doesn't come up in the results by default. The person doing the search needs to conciously select the 'Search for both standards compliant and non-compliant files' option to display less-compliant files so that they don't accidentally download files that could interfere with files they already have.
If you submit non-compliant files then a lot of people may never bother looking at them. On the other hand, saying they're compliant if they're not is likely to hack people off pretty quickly.
Providing the option to submit non-compliant files is intended to encourage contributions even from those who don't have the time to invest in making it compliant. At least if you do submit a non-compliant file and someone finds it useful then there's always the hope that they'll tidy it up and submit a compliant version.
Version Number
Maximum Number of Characters: 20
Permitted Characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.()
New contributions are usually numbered '1.0'. You may choose to use a different number for a first submission if you wish. If there are already older copies of your files available on other sites you should use a version number consistent with those versions. If it's still a work-in-progress, you may choose to use fractions to indicate how mature it is (e.g. '0.5', or '1.9'). You can use suffixes to describe sub-versions such as '3.2.11b'.
Once you have submitted a contribution it will always be referred to along with your contributor tag name and will usually have the submission date appended to it. You therefore enter only the version number itself. You should not identify yourself in the version number and should not add the date into the number as this is liable to mess up the version number displays and make it more difficult for people to easily find what they want.
Previous Version If you are submitting an updated version of an existing submission you will need to indicate which previous version your updates are based on. This would most normally be the most recent previous submission, which is the default version selected in the pull-down list of previous versions. This information is currently only used by administrators. You should not assume that the person downloading your contribution will already have any files from any previous version of the contribution. You should submit all files that are required to work with the version of the contribution that you are submitting.
Description
Maximum Number of Characters: 600
Permitted Characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-. ()+=,?@;%$!* \'"
plus carriage returns
Whether submitting a new contribution or submitting an update to an existing contribution, the information you add into the 'Description' field will be the information displayed to people looking at the collection. They won't see the descriptions of previous versions unless they go to the trouble of specifically selecting an alternative version.

The description you enter here should therefore cover all you need to say. Make it as clear and concise as you possibly can. Avoid using unnecessary abbreviations that may confuse people and structure your text to assist anyone considering whether to download the item to decide whether it's what they're looking for. Use full english sentences to ensure that the description is clear, remembering that english may not be the first language of many of the people reading it.
To enter your desciption you can type into the input field, cut and paste from another application, or use the 'widget' controls next to the text area to load text into that field:

Keywords or Key Phrases
Maximum Number of Characters: 255
Permitted Characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-
plus carriage returns
The words and phrases you enter into the 'Keywords' field will enable people to find the files you are submitting when they search the collection. These words and phrases won't be visible, but careful selection of appropriate words and phrases will significantly increase the likelihood that people will be able to find and use your submission.

Enter each word or short phrase on each line. Try to think of words or phrases that people looking for this sort of object are likely to enter into the search field on the search screen. This can include words describing both what the object represents and the techniques used to implement it. For example, the 'TheEarth' entry includes the keyphrase 'The Earth' and keywords such as 'Earth', 'Globe', 'Planet', 'Sphere' and 'Image Map'. You don't need to enter the name or the unique prefix of the object as a keyword. These will be automatically added by the server. It may however be worth adding variants of the name (plurals or abbreviations/acronymns).
To enter your keywords you can type into the input field, cut and paste from another application, or use the 'widget' controls next to the text area to load text into the field:

Categories The categories you select from the 'Categories' list will help people to find the files you are submitting when they search the collection. By carefully selecting the most appropriate categories you can help save other people a lot of time.

You can select multiple categories by Ctrl-Clicking items in the list, but you don't need to select successive categories leading down to a lower-level category because inclusion at a lower level automatically implies inclusion in levels above. For example, adding an object into the 'Computers' category automatically implies inclusion in the 'Household/Office Objects' category.

Note: Occasionally with IE6 in Windows the 'Categories' control freezes and it fails to scroll properly. The cause of this is currently unknown, but minimising the browser window and reactivating it from the Windows taskbar seems to fix the problem without losing information entered into the window.

Prerequisites (Optional)
Maximum Number of Characters: 255
Permitted Characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-. ()+=,@;%$!*
plus carriage returns
It's best to avoid prerequisites and dependencies wherever possible, but you may find that your contribution is dependant upon having specific software (e.g. Moray) a specific operating system (e.g. Editor extensions for Windows), that it relies upon other contributions or files available from other Internet sites. It may, for example rely upon image resources that are available for download, but that you do not have the right to load into this site under the licensing conditions of this collection.
This is a free text field that will be displayed to those searching the collection. To record any prerequisites you can type into this input field, cut and paste from another application, or use the 'widget' controls next to the text area to load text into the field:

If there are prerequisites that your contribution needs in order to work, please list them, or point to the location of a file identifying those prequequisites (It is best to avoid pre-reqs if possible).

Files Use the Browse button in the 'Files' input area to select the files that you want to contribute. Clicking the Browse button opens the standard 'Choose File' dialogue box enabling you to select a single file. Once you've selected a file you will see it appear in the list of files (with a 'Remove' button next to it. You can repeat this as many times as you like to identify all of the files that constitute your contribution. If you add one by mistake, clicking the 'Remove' button simply removes it from the list of files to upload.

All file names are converted to lowercase when they are uploaded onto the server to try to cope with operating system differences with respect to case sensitivity in file names.
Certain restrictions apply to the type of file you can submit. The following file types are supported: BMP, CSS, CSV, GIF, HTM, HTML, INC, INI, JPEG, JPG, JS, MAC, MCR, MDL, PGM, PNG, POV, PPM, TGA, TIF, TIFF, TXT .

If you have identified your contribution as being 'Fully Compliant' in the 'Standards Compliance' pull-down, then certain restrictions apply to the file names that you use. All file names for a 'Fully Compliant' submission must be prefixed with either the contribution name or, if you have specified a unique prefix, with that prefix name. This must then be followed either by an underscore ('_') or by a dot/period ('.').

The names XXX_description.txt, XXX_keywords.txt and XXX_prereqs.txt (where XXX is the contribution name or unique prefix) cannot be used for files submitted in the 'Files' input area. These file names are used by the server to generate files based on the description, keywords and prerequisites that you provide in the appropriate input fields. You can however use the 'Browse' buttons next to each of those fields to load text from files with those names into the appropriate input fields.

The following table provides some examples of both valid, standards compliant and invalid or non-standards compliant file names for a contribution called 'Netball' where the optional unique prefix of 'NB' has been specified.
Valid File IDsInvalid File IDs
netball.pov
netball_bag.pov
netball.html
netball.htm
netball_thumbnail.jpg
nb.jpeg
nb_1.gif
netball.exe (Not a valid file type)
a_netball.exe (Doesn't start with 'Netball' or 'NB')
netballbag.pov ('Netball' must be followed by '_' or '.')
nb1.gif ('NB' must be followed by '_' or '.')
netball_description.txt(first of the three text files that will be generated automatically)
netball_keywords.txt (second of the three text files that will be generated automatically)
netball_prereqs.txt (third of the three text files that will be generated automatically)

When you submit the contribution, all of the files that you have identified in the list will be sent to the server.

Unfortunately, if your contribution contains errors you will have to select the contribution files again before resubmitting because the file input areas will be cleared by the browser when the page gets re-displayed. There is one exception to this where the only error is that you've forgotten to add the licensing statement to your .pov or .inc files. In this case you can update your files then hit the browser Refresh button, electing to resubmit the form values when prompted by the browser.

Checklist The purpose of this collection is to build a set of POV-Ray files that can be freely used, modified and redistributed. In order to be able to achieve this it is necessary that the provenance of anything contributed to the collection is clearly understood and that the person submitting the contribution has the rights necessary to authorise the contribution to be used, modified and redistributed.
Once all mandatory fields have been completed the 'Submit Contribution' button becomes active. Check that you have completed all of the information accurately and submitted all of the files you wish to submit with this contribution before hitting this button. You will not be able to edit the entry once you have submitted it.

Many errors are picked up in the submission form before it allows you to submi the form. However, if the submission contains errors when you submit it to the server, the server returns you to the submission form and displays the errors at the top of the screen. Most of your responses will still be there, but, unfortunately, once you have corrected the erroneous field, you will need to reselect your files because the browser won't retain the fileIDs in the file input fields. If the only error reported by the server is that you've forgotten to include the licensing statement in your '.pov' or '.inc' files there's a little trick that works in many browsers to avoid having to re-enter the fileIDs. Once you've updated your '.pov' or '.inc' files you should be able to hit the 'Refresh' or 'Reload Current Page' button on your browser tool bar and it will ask you if you wish to resubmit the field values.

If successful the server will display a list of the files you have submitted along with the entry as it will appear on the search panel. Note: If you have provided a thumbnail and a larger image to illustrate your contribution, the thumbnail will provide a hyperlink to the full-sized image. For reasons as yet unknown, from time to time in IE6 under Windows, following this hyperlink opens an empty window. Simply refreshing this window in the browser usually displays the image correctly.