Cover

Documentation

KrystalShaper

Crystal Morphology Editor/Viewer

Version 1.4.0

© JCrystalSoft, 2016


What's New ?

Version 1.4.0

AppletViewer

Modern web browsers do not run Java applets anymore and starting with JRE 7u51 most existing applets are prohibited from running even in browsers like Internet Explorer. Before that one could fix this by setting the Java security level to "Medium" in the Java control panel. Because of these changes none of the included applets are deployable anymore.

In order to be able to run the educational applets at least locally I bundled an older JDK with KrystalShaper. The menu [Applets] now shows the checkbox "Launch AppletViewer". When it is checked the AppletViewer EXE from the older JDK1.4 is launched for displaying the applet.

Please note that the educational applets under the menu [Applets] have nothing to do with KrystalShaper and were taken from my website and added for convenience.

The only applet that is impacted is the KrystalShaper applet that was used for embedding the shape rendering in a web page. Please use animated PNGs if you wish to embed animations in a webpage using the menu [File][3D Export][Animated GIF].

Version 1.3.0

Line Drawings

The black/white drawing style has been improved. Use menu [View][Drawing (Transparent)] or [View][Drawing (Solid)]

Form Editor

Use menu [Edit][Edit Form] to open the new form editor, which lets you delete or replace a whole form. A crystal class must be selected to enable this function.

Pop-up Menu

Right-click the editor's hkl-table will now show the edit menu as a context menu

Version 1.2.2

Mono-Color Display

Right-mouse-button click/drag on the editor's color palette to change all face colors to a single color. Undo by recalculating the shape.

Multi-Form Generator

Click the ">>" button on the form generator to see the new multi-form input option

Version 1.2.1

  • Improved Animated GIF export. Use menu [File][Export 3D][Animated GIF (*.gif)] or [Options][Save Image Sequence] with filetype "Animated GIF Image"

Version 1.2.0

  • Fixed bug in form generator
  • Fixed bug in image browser
  • Added color swatches in form generator
  • Added [Editor][Select All Faces]
  • Added [File][Export 3D][JCrystal File (*.jcr)]
  • Added sample files in folder "Erich_Offermann"


Introduction

KrystalShaper is not an upgrade of JCrystal. It is a separate program, which is written in a different language and with a different feature set and file format, although a certain overlap in functionality and GUI design exists between both programs. Please read the comparison for more details on the differences between both programs.

KrystalShaper draws crystal shapes for normal crystals and icosahedral quasicrystals. It is possible to export webpages in the HTML language, which use the provided Applet, so that crystal shapes can be viewed within a Java-enabled webbrowser, such as Microsoft Internet Explorer (MSIE). KrystalShaper itself has more rendering options than the applet. It might thus be used as an interface for the creation of interactive webpages. Please note that webbrowsers do usually not support the latest Java language version, which is why the rendering options in the Applet are not the same as in KrystalShaper.

Main Features

  • Easy-to-use interface with real time rotations
  • Display of Hauy Block Models
  • BFDH Morphology Prediction
  • Stereo Pairs and Anaglyphs (red/blue stereo)
  • Print Foldable Nets for Crystal Models
  • Export of GIF, JPG, BMP, PNG, PDF, VRML, POV files
  • Import of CIF files (will be improved in future)
  • Integrated Image Browser
  • Integrated Applet Preview
  • Integrated Webbrowser for Photo Download
  • Snowflake Generator
  • Export Animated GIFs
  • Form Generator & Form Editor

Sample Files

All sample data in the directory "data\Dave_Barthelmy" are provided by Dave Barthelmy . The sample data in the directory "data\Udo_Behner" were provided by Udo Behner .

Disclaimer

The software KrystalShaper is sold on an "as is" basis without any warranty either expressed or implied as to its performance, quality, or fitness for any particular purpose. The entire risk is with the buyer. JCrystalSoft's liability for any damage arising out of the use of this software shall be limited to the price for this product. In no event shall JCrystalSoft be liable for indirect, special or consequential damages resulting from the use of the KrystalShaper software. This software product is copyrighted and all rights are reserved by JCrystalSoft and the program's author Dr. Steffen Weber. The software is licensed by JCrystalSoft to the original purchaser. Copying and duplicating (except for purposes of backup), selling, or otherwise distributing this product is not allowed.

JCrystalSoft reserves the right to make changes or improvements in this software at any time and without notice.

Mission Statement

I have written this newer program in a different language, because it will enable me to include future features more easily, since programming in Java (see JCrystal) is quite cumbersome. Please email me any suggestions for improvements that you may have.

Steffen Weber , Ph.D.


Comparison

Comparison of KrystalShaper and JCrystal

KrystalShaper (KRS) is not an upgrade of JCrystal (JCR), but a separate program though a certain overlap in functionality and GUI design exists between both programs. Since KrystalShaper is written in a Windows programming language it will start up faster than JCrystal. The rendering types also differ between both programs.

Feature Comparison

 | KRS | JCR
Windows Language | X |
Java Language |  | X
Binary File Format | X |
Foldable Crystal Models | X |
Image Browser | X |
Save Transparent PNG | X |
Save Image Sequences | X |
Embedded Webbrowser | X |
Embedded Applet Preview | X |
BFDH Prediction | X |
Hauy Block Model | X |
Snowflake Generator | X |
Includes Applet Export | X | X
Export VRML Files | X | X
Export PovRay Files | X | X
Export Acrobat PDF Files | X |
Export PostScript Files |  | X
Wulff Module |  | X
Laue Module |  | X
Periodic Table Module |  | X
Webdatabase Link |  | X
DEMO Available | X |
OpenGL Graphics | X |
Export Animated GIF | X |

Windows Vista Compatibility

JCrystal

Since this is a Java program the Windows Aereo look will change to the Windows Basic look and the gadget sidebar may flicker. It is best to install JCrystal in a user folder and not under "Program Files", otherwise one has to run it "as administrator", since Vista may prohibit programs from writing to folders under the "Program Files" directory.

KrystalShaper

No known problems. It is written with the multi-user setup in mind and uses a dedicated user folder.


Getting Started

If you have already purchased a license you may want to unlock all export functions now.

Step 1: Open a Sample Data File

  1. Select the "Browse" tab for viewing the file browser
  2. Select one of the sample data folders from drop-down list
  3. Select a KrystalShaper data file (*.krs) for viewing
  4. Select the "Display" tab for exploring the display options

Note: All data folders should reside under the "..\KrystalShaper\data\" folder as first-level sub-folders, in order to be listed in the drop-down list. If you wish to open data from a folder outside the "data\" folder use the menu [File][Open] or the toolbar button for opening the data file.

Step 2: Explore Display Options

  1. Display mode switches
  2. Color options
  3. Light source (drag position in circle)
  4. Polygon transparency and cylinder width
  5. Toolbar shortcuts


Main Window

The main window offers several layouts by using the tab selectors. The controls on the left can be turned on/off and the display can be chosen to be the crystal display, applet preview or webbrowser. The registered version also allows you to import of ASCII data files, such as JCrystal's datafiles with the filename extension *.jcr, *.hkl or *.txt.

Main Toolbar

  1. Create a new crystal shape
  2. Open a data file
  3. Save current shape as a KrystalShaper file (*.krs)
  4. Copy image to the clipboard
  5. Print image
  6. Calculate/Recalculate shape from HKL table
  7. Animate about horizontal axis (right-click for single 90 deg rotation)
  8. Animate about vertical axis (right-click for single 90 deg rotation)
  9. Animate about screen normal (right-click for single 90 deg rotation)
  10. Reset view (right-click for clinographic view)
  11. Show/Hide controls
  12. Toggle projection type (default=orthonormal)
  13. 4 Stereo modes (right-click for reverse order)
  14. Show/Hide crystal axes
  15. Show/Hide face numbers
  16. Show/Hide hkl-labels
  17. Show/Hide face normals

Main Window

  1. Menu bar
  2. Main Toolbar
  3. Tab selector 1 (Controls)
  4. Editor with HKL table
  5. Status bar
  6. Message area
  7. Tab selector 2 (Displays)
  8. Rotatable crystal display (left/right-mouse button for zoom/rotation)

Rotation :
Drag crystal with left-mouse-button depressed or use arrow-keys. For rotation about the screen normal drag with right-mouse-button up/down on left side of the display center.

Zooming :
Drag with right-mouse-button up/down on right side of the display center ! (or use plus/minus keys)


Form Editor

The editor enables the user to create new crystal models from scratch by defining a list of hkl indices (for all present faces; i.e. the form of the crystal) and their corresponding central distances (d-values), which determine the habit of the crystal. One may directly type the hkl list into the editor, but it is easier to use the dialog window for adding a face/form, since in most cases one wishes to generate the equivalent hkls for a given starting hkl. The editor is automatically cleared when another datafile is loaded.

In order to create a new crystal shape follow these steps:

Step 1: Clear hkl-table and add faces/forms

  1. Start new shape
  2. Set point group symmetry (crystal class)
  3. Enter a title
  4. Enter unit cell parameters (Angstrom and degrees)
  5. Add a face/form/multiple forms
  6. Click to select desired color for new face/form
  7. Enter input hkl ("h SPACE k SPACE l", or "hkl" if three positive one-digit integers)
  8. Enter desired distance
  9. Create equivalent hkl
  10. Editable list of generated equivalents
  11. Add form to hkl editor's hkl-list
  12. Multiple forms input
  13. Add all specified forms
  14. Show/hide multiple forms input

Step 2: Calculate shape

  1. Newly created hkl-list with assigned colors and distances
  2. Calculate shape from hkl-list
  3. Turn on face numbers for comparison with table

Step 3: Modify shape and colors

  1. Click at first column cell for selecting/unselecting a face
  2. Distance slider for modifying the distances of the selected faces
  3. If a face is absent (outside the crystal hull) its distance cell is marked in red. The face numbers are also listed on the statusbar. Those faces could be either deleted or their distances adjusted to make them visible again.
  4. Color selector for current editor color
  5. Current editor color (click to bring up Windows color chooser)
  6. You may click at a row's color cell, in order to assign to it the current editor color. If you wish to copy another row's color click at its color cell with the Ctrl-key pressed. This will set it as the editor color. Then you can click at another row's color cell for the assignment.

When the shape is completed save the new datafile by clicking at the save button on the main toolbar or by selecting menu [File][Save]. The behavior of the editor will be improved in future updates .

Select/Unselect a whole Form

The editor table does not keep track of what form a face (row) belongs to. When you add new forms it is good practice to assign different colors to each form. That way the editor can use the face color as a distinguishing criterion. If your forms in the hkl-list have different colors assigned to them you may select/unselect the whole form by pressing a Control key (Ctrl / Shift / Alt) when clicking at the first column (face number) !

Editing the Table directly

If you want to type directly into the hkl-table for adding faces or for changing the hkl indices or distance of a face, click at the cell until the yellow text field appears in which you may type the new value. You may then use the arrow keys on your keyboard to move to other cells. When done recalculate the shape by using the toolbar button or bu selecting the menu [Edit][Recalculate].

Using the Distance Slider

If at least one face is selected the distance slider will be visible. It can be used to dynamically adjust the distance values of the selected faces and see the result in the updated shape. It is useful to turn on the face number labels in the crystal display, so that one can easily locate the selected faces.

Copy and Paste

One can use the Ctrl+v key for copying selected faces to the clipboard. Then when starting a new document (Ctrl+n) one can paste those faces back with Ctrl+v. Instead of the key combinations one can also use the corresponding menu items in the menus [File] and [Edit]

Other Editor Options

  • Selected rows can be deleted with the Del-key or with the menu [Edit][Delete Selected Faces]
  • To delete absent faces (marked red) from the list use menu [Edit][Delete Absent Faces]
  • To try to automatically fix absent faces use menu [Edit][Auto-Adjust Distances]
  • To create random hand pieces use menu [Edit][Randomize Distances]
  • For an automatic shape prediction use menu [Edit][BFDH Prediction]. This performs a prediction based on the d-values called the Bravais-Friedel/Donnay-Harker criterion. This feature may be improved in future updates.


Applet Preview

The KrystalShaperApplet is derived from the JCrystalApplet, but they are not identical, since the data format for importing the crystal shape data is different. However the usage is very much the same. Your computer must have a Java Runtime Environment (JRE, aka Java Plugin) installed, so that your webbrowser can display Java Applets. Some newer PC may come without a preinstalled JRE. You can download the latest JRE from Sun Microsystems at http://www.java.com/en/download/index.jsp .

In order to export an HTML document with the applet use the menu [File][3D Export][Webpage (*.htm)]

User Interface

  1. Html properties for applet export (size and colors)
  2. Optional background image (click to change)
  3. Optional annotation used as applet subtitle
  4. Java Applet display (see options below)
  5. Click to open in external webbrowser

Applet Options (Mouse)

  • Drag crystal with left/right mouse button
  • Zoom with right mouse button on right side of applet
  • Change display modes by clicking with right mouse button
  • Click on top left corner for menu

Applet Options (Keyboard)


Webbrowser

Integrated Web Browser

The webbrowser is provided for convenience. One may perform Google image searches or go to other websites by entering a URL. When a webpage contains photographs they can be automatically downloaded (except for the Google image search results) by clicking the [Save] button (#4 below). A hashcode prefix will be appended to the image filenames, in order to ensure unique filenames so that images with the same name do not overwrite each other. If you choose to download images manually by [right-click][Save Picture As ..] it is advisable to save them into the designated download folder, so that KrystalShaper's image browser can locate them when using menu [Options][Browse Download Folder].

The URL drop-down list (#1 below) can also be edited from the menu [Help][Links][Edit URL List].

User Interface

  1. Enter URL or select URL from drop-down list
  2. Enter mineral name for Google image search
  3. Start Google image search
  4. Automatically save images in webpage (not for Google images)
  5. Open Download folder
  6. Embedded webbrowser


Foldable Nets

Foldable Nets (Paper Models)

Menu [View][Paper Model (Net)]

For the morphology enthusiast it may be a very welcome feature to be able to print a flattened version of a crystal shape so that it can be printed on paper for creating a folding model. A first implementation of such an algorithm is presented with KrystalShaper. The flattening is not unique but varies with the face that is chosen as the starting face. If a net does seem odd or complicated you may try to click through other starting faces (button #1 in image below) until a satisfactory net was found. This can then be printed or saved as a KrystalShaper Net File (*.krn). In a future version we will put more effort into the determination and avoidance of overlapping polygons.

User Interface

  1. Click to select other starting faces for the flattening
  2. Export and Import options
  3. Specify optional monocolor
  4. Simple print preview
  5. Toggle monocolor
  6. Display of current net (drag to rotate)
  7. Net properties
  8. Current printing format (depends on window size)

Printing with Additional Text

If you want to print some extra text on your papermodel printouts you can do so by creating a file named "papermodel.txt" in the folder where the program file "KrystalShaper.exe" is located. The format of the file should be as follows:

Arial
BoldItalic
9
10
10
This is an example text
for the paper model printouts.
The first 5 lines specify
the Font, fontsize, x and y
offsets in [mm] and then
the text. If line #6 is empty
this file will be ignored

Format :

  1. line: Font Name
  2. line: Font Property (Bold, Italic, Regular)
  3. line: Font Size
  4. line: X-offset in [mm] from top left corner
  5. line: Y-offset in [mm] from top left corner
  6. line: Start of custom text (if empty, file will be ignored)


Image Browser

Menu [Options][Browse Image Folder]

A dedicated image browsr is included for convenience. Modern operationg systems, such as Windows XP or Windows Vista already offer powerful image browsing capabilities, but sometimes it is useful to have an image browser that directly opens a certain folder, without having to search for it.

The browser can be launched from the menus [Options][Browse Image Folder], [Options][Browse Photo Folder] and [Options][Browse Download Folder]. Please note that transparent PNG images take slightly longer to load and that many graphics programs may not render them correctly, since the PNG format (Portable Network Graphics) is relatively new and combines the best of both worlds of the popular GIF and JPG formats.

When the browser is opened or a directory is changed the thumbnail images are created in memory (not on harddisk). When there are many images it may take a while for the thumnails to be created. You may interrupt this process by pressing the ESC key or by clicking at the bottom status bar.

User Interface

  1. Directory browser
  2. Image file list (click to select, or use up/down arrow keys)
  3. Copy image to clipboard (transparency of PNG image will be lost)
  4. Image display (fit to display area)
  5. Thumbnail preview (click to select)
  6. Image properties


Snowflake Generator

Menu [View][Snowflake Generator]

This feature is provided for the lover of the six-fold symmetry as found in snow flakes. It does not use a scientifically grounded algorithm based on real crystal growth models. The snowflake shape is created by attaching small seeds to the pattern to make it grow. All parameters such as seed size and number of seeds are chosen randomly. The user has the possibility to set the opacity and maximum radius of the seeds using the sliders. Click at the display area or press SPACE in order to create another snowflake.

User Interface

  1. Save or Copy image
  2. Click at display to create next random snowflake; Double-click for loop
  3. Seed opacity (default= 12%)
  4. Maximum seed radius (default= smallest)


Registration

Menu [Help][Register ...]

If you purchased a registered license at www.jcrystal.com/order.html you will receive an email with your registration password. Select menu [Help][Register ...] to bring up the following dialog window and enter your password (best use copy/paste for avoiding typing errors).

You should then see the following acknowledgement.

After that the splash screen under menu [Help][About] will show your name as seen below.

All export options are now enabled.


Tips

Faster Browsing

Switch edge mode to lines instead of cylinders, in order to decrease the loading time of a shape. Cylinders consist of many polygons and slow down the graphics pipeline.

Collapse Control Frames

Some of the control frames (colors, switches etc.) can be collapsed/expanded by clicking at the frame title.


Contacts

You may contact us with bug reports or suggestions for improvements.

Email:

jcrystalsoft@gmail.com

JCrystalSoft homepage:

http://www.jcrystal.com

KrystalShaper homepage:

http://www.jcrystal.com/products/krystalshaper/