stbHFarch.inc Help Contents

1.0 Introduction
  1.1 Description
  1.2 How it works
  1.3 What it can do
  1.4 Contents
2.0 Getting Started
  2.1 Your first arch
  2.2 Changing the brick's shape
  2.3 Texturing the arch
  2.4 Changing the brick's heightfield resolution
  2.5 Making double-sided bricks
3.0 File Reference
  3.1 The macros
    3.1.1 stbHFarch_brick_arch
    3.1.2 stbHFarch_single_brick
    3.1.3 stbHFarch_pillar
    3.1.4 stbHFarch_single_pillar_brick
    3.1.5 stbHFarch_reset_values
  3.2 The variables
    3.2.1 Brick shape manipulation
      3.2.1.1 stbHFarch_brick_pattern
      3.2.1.2 stbHFarch_brick_pattern_offset
      3.2.1.3 stbHFarch_brick_pattern_reset
      3.2.1.4 stbHFarch_pattern_override
      3.2.1.5 stbHFarch_brick_mirror
      3.2.1.6 stbHFarch_brick_clipping_depth
      3.2.1.7 stbHFarch_clipping_mode
      3.2.1.8 stbHFarch_brick_intersection
    3.2.2 Brick texture manipulation
      3.2.2.1 stbHFarch_brick_texture
      3.2.2.2 stbHFarch_brick_texture_offset
    3.2.3 Heightfield manipuation
      3.2.3.1 stbHFarch_brick_res
      3.2.3.2 stbHFarch_brick_smooth
  4.0 Speed Considerations



1.0 Introduction

Thank you for downloading this include file! It started out rather small, but soon became the full-featured include file you see before you.

To contact me about this file, write me at stbenge@hotmail.com

1.1 Description

This include file lets you make brick arches, single arch bricks, pillars or single pillar bricks by way of object macros. The objects it creates are heightfield-based, meaning you can declare special patterns to change the shape of each brick. Certain speed considerations are taken into account.

1.2 How it works

Each brick making up the arch is based on a heightfield which is clipped or intersected independently. The pattern for each brick is scaled to the exact size needed by the heightfield. This improves efficiency during parsing, resulting in lower render times.

1.3 What it can do

These macros let you easily create brick arches and brick pillars with a few simple commands. By default the bricks are one-sided, for use on walls. By changing some values, however, you can make the bricks two-sided for use on free-standing pillars.

1.4 Contents

The include file contains:

*A brick arch macro
*A single arch brick macro
*A brick pillar macro
*A single pillar brick macro
*Several variables to manipulate the brick shape, texture and detail
*A macro to reset the variables

_____________________________

2.0 Getting Started

Drop the include file into POV-Ray's include directory or the directory where you intend to use it. After that just include the file like so:

#include "stbHFarch.inc"

2.1 Your first arch

Since there are default values for everything, you can simply invoke the arch macro:

object{ stbHFarch_brick_arch(12, 4, 180, 9, 1) pigment{rgb 0.5}}

The 'stbHFarch_brick_arch' macro takes five arguments. The first represents the radius of the arch. The second is the thickness of the arch brick. It is important to consider that this value changes the inner radius of the arch, not the outer radius. That means by using the values above, the inner radius of the arch would be 8. The third number is the arch's range. A value of 180 gives this arch a classic look, while 360 would produce a complete circle, perfect for a tunnel entrance. You may use any value less than or equal to 360. The fourth number is the number of bricks for a given range. In this example there are 9 bricks making up the arch. The fifth parameter defines the arch brick's depth, or bas-relief.

2.2 Changing the brick's shape

There are actually two ways to do this, and both ways will result in a brick custom-fitted to the arch.

The first way is to change the brick's shape pattern directly, like so:

#declare stbHFarch_brick_pattern =
 pigment_map{
  [0.0 rgb 0.0 ]
  [0.05 rgb 0.75 ]
  [0.1 rgb 0.95 ]
  [0.25 rgb 1.0 ]
  [0.4 rgb 0.95 ]
 }

The first entry represents the edge of the brick, and the last entry represents the the edge going towards the middle of the brick. So 'rgb 0.0' ensures the edge slopes inward, like you would expect a brick to be. You can use any pigment you wish (this includes procedural patterns), and the pigment will be rotated with each brick.

Note that when using this method, the contour of the brick will be a fixed distance from the edge. In other words, the edges of the brick will be the same thickness no matter what values you pass to the arch or single brick macro.

The second way to change the brick's shape pattern is to declare a pattern override, like so:

#declare stbHFarch_pattern_override =
  pigment{
    boxed scallop_wave frequency 4
  }

This method is fundamentally different from the first. Instead of relying on a built-in edge function, you are explicitly telling the macro to force a pattern to the brick shape. In this case, I used the pattern 'boxed' to define the brick's shape. The shape will be warped to fit the brick exactly.

2.3 Texturing the arch

You may add a texture inside the object{} block where the macro invocation resides, but a more powerful way is to declare the texture beforehand. This lets you apply incremental texture positioning so that each brick appears to have it's own separate texture. Try this:

#declare stbHFarch_brick_texture_offset = <0,0,10>;

#declare stbHFarch_brick_texture =
  texture{
    pigment{
      granite scale 7
    }
  }

'stbHFarch_brick_texture_offset' translates the texture for each new brick in the arch. The texture is first translated by <0,0,10>*0, next by <0,0,10>*1, next by <0,0,10>*2 and so on.

The texture's size is not relative to the arch, but literal. However, the texture does rotate with each brick, so keep that in mind.

2.4 Changing the brick's heightfield resolution

If you are experiencing long parse times or bad results, you may want to change how detailed the heightfield is for the brick. You can do this by declaring new values this way:

#declare stbHFarch_brick_res = <200,200>;

The default values are <100,100>.

2.5 Making double-sided bricks

By default the bricks are one-sided, with the outside facing -z. For your scene you may need the bricks to be two-sided. This would be the case if you were modeling an arbor. The simplest way to do this is do change the default value:

#declare stbHFarch_brick_mirror = yes;

By turning mirroring on, you are telling the macro to make another copy facing in the +z direction.

In some cases, there may be an unwated ridge where the two brick surfaces meet. To avoid this, you can have each brick intersected with another, custom-fitted, CSG brick shape. Try doing this:

#declare stbHFarch_brick_intersection = 0.05;

By default, this value is 0, meaning no intersection takes place. Positive values scale the CSG brick shape down which results in a slightly smaller brick, but edges which are smooth. As you might have already guessed, doing this will increase the render time.

You may use this feature for one-sided bricks as well, but they will render more slowly than two-sided bricks. I'm not exactly sure why, but it helps to know.



3.0 File Reference

3.1 The macros

3.1.1 stbHFarch_brick_arch(rad, thk, range, div, depth)

Makes a brick arch starting at <0,0,0>. The resulting object is a union.

rad = The outside radius of the arch
thk = the thickness of each brick (changes the inner radius)
range = how much of an arch? 180 degrees? 360? 90? (1-360)
div = how many bricks for a given range? (1-??)
depth = the depth of each brick. 'stbHFarch_brick_clipping_depth' will affect this.

example code:
object{
  stbHFarch_brick_arch(12.0, 4.0, 180, 9, 1.0)
  pigment{rgb 1}
}

3.1.2 stbHFarch_single_brick(rad, thk, div, depth)

Makes a single arch brick (not a brick arch). The parameters are similar to 'stbHFarch_brick_arch'. The brick is automatically translated in the +y direction for convenience.

rad = the outside radius of the brick
thk = the thickness of the brick (changes inner radius)
div = number of brick divisions to complete a circle (needed even though the macro makes a single brick)
depth = the depth of the brick. 'stbHFarch_brick_clipping_depth' will affect this.

example code:
object{stbHFarch_single_brick(14, 2, 18, 1) pigment{rgb 1} }

3.1.3 stbHFarch_pillar(rad, thk, height, div, depth)

Makes two brick pillars, perfect for putting your brick arch onto. It starts at y=0 and extends in the +y direction.

rad = the radius of the pillars (should be the same as the arch radius)
thk = the thickness of the pillars (changes the inner radius)
height = the height of the pillars
div = how many bricks make up each pillar? The height is divided by this value
depth = the depth of each brick. 'stbHFarch_brick_clipping_depth' will affect this.

example code:
object{stbHFarch_pillar(12.0, 4.0, 8.0, 3, 1.0) pigment{rgb 1}}

3.1.4 stbHFarch_single_pillar_brick(thk, height, depth)

Makes a single pillar brick. It starts at y=0 and extends outward. You can #declare it and use it for brick walls if you wish.

thk = the thickness, or width of the brick
height = the height of the brick
depth = the depth of the brick. 'stbHFarch_brick_clipping_depth' will affect this.

example code:
object{stbHFarch_single_pillar_brick(4,3,1) pigment{rgb 1}}

3.1.5 stbHFarch_reset_values()

Resets all the variables used by the include file (see 'The variables', below). Perfect for creating new arches or pillars in the same scene file.

example code:
stbHFarch_reset_values()

3.2 The variables

The variable names presented here are long so the include file can adhere to the unique prefix naming convention. This is to avoid conflicts with files made by other people.

3.2.1 Brick shape manipulation

Following are several variables to control the shape of the brick for the object macros.

3.2.1.1 stbHFarch_brick_pattern

Changes the shape of the brick by redeclaring the pigment map it uses.

example code:
#declare stbHFarch_brick_pattern =
  pigment_map{
    [0 rgb 0]
    [.2 rgb 1]
    [.4 rgb 1]
    [.5
      onion triangle_wave color_map{[.25 rgb .5][.75 rgb .9]}
    ]
  }

3.2.1.2 stbHFarch_brick_pattern_offset

If not zero, it translates the pattern along the z-axis for each new brick in the arch or pillar. Use in conjuction with your own brick pattern. This feature can result in long parsing times, so use it only if you really need to.

example code:
#declare stbHFarch_brick_pattern_offset = 1.0;

default = 0

3.2.1.3 stbHFarch_brick_pattern_reset

This resets the pattern used by the arch or pillar macro. It effectively 'snaps' the pattern to 3d space, allowing you to create effects like world-oriented lattice between brick edges. It can be used with both 'stbHFarch_brick_pattern' and 'stbHFarch_pattern_override'. This feature can result in long parsing times, so use it only if you really need to.

example code:
#declare stbHFarch_brick_pattern_reset = yes;

default = no

3.2.1.4 stbHFarch_pattern_override

If used, it overrides 'stbHFarch_brick_pattern', letting you make your own pattern for the brick from scratch. Your pattern must lie within <-1,-1,0>,<1,1,0> in 3d space. The pattern will be warped to fit the brick shape exactly.

example code:
#declare stbHFarch_pattern_override=
  pigment{
    boxed
  }

By default this is not declared.

3.2.1.5 stbHFarch_brick_mirror

Makes an extra copy of the brick in the +z direction. Use this to make 'complete' bricks.

example code:
#declare stbHFarch_brick_mirror = yes;

default = no

3.2.1.6 stbHFarch_brick_clipping_depth

By default the brick is intersected with a plane facing in the +z direction. 'stbHFarch_brick_clipping_depth' lets you specify how much clipping is performed on the brick. If effectively moves the clipping plane in the -z direction, and then moves the entire brick in the +z direction to ensure that it lies at z=0. This is most useful if you have mirroring turned on. It will only work with clipping mode 1 (see stbHFarch_clipping_mode below).

example code:
#declare stbHFarch_brick_clipping_depth = 0.125;

By default it is set to a small value relative to the brick's depth.

3.2.1.7 stbHFarch_clipping_mode

There are four clipping modes available to you:
0 = no clipping
1 = clipped by +z facing plane
2 = clipped by brick shape
3 = same as 2, but useful if the brick gets black edges

If you want to see the heightfield before it's clipped, use no clipping. You may also want to disable clipping if your bricks lie on a -z facing plane (ie. plane{-z,.01}).

example code:
#declare stbHFarch_clipping_mode = 2;

default = 1

3.2.1.8 stbHFarch_brick_intersection

Intersects the brick with another brick shape.

Positive values scale the intersecting brick shape downwards, thus providing a means to separate the bricks from each other and to remove unwanted ridge lines (often produced when mirroring is turned on). This feature will increase the render time; I suggest not using it. In most cases increasing 'stbHFarch_brick_clipping_depth' will do the job.

example code:
#declare stbHFarch_brick_intersection = 0.125;
default = 0 (off)

3.2.2 Brick texture manipulation

Following are two variables to control the texture for the 'stbHFarch_brick_arch' and 'stbHFarch_pillar' macros.

3.2.2.1 stbHFarch_brick_texture

With this you can designate a texture to be used with the 'tbHFarch_brick_arch' and 'stbHFarch_pillar' macros. It will be rotated and/or translated, depending on the macro used.

example code:
#declare stbHFarch_brick_texture=
  texture{
    pigment{
      spherical scale 4
    }
  }

By default there is no texture.

3.2.2.2 stbHFarch_brick_texture_offset

This will incrementally offset 'stbHFarch_brick_texture' by a given vector. Each new brick in the arch or pillar will be offset by this amount. Using this allows you to give the impression that all the bricks have different textures. Note that if you use this feature with 'stbHFarch_pillar', the bricks to the left will be offset by an additional 1.5 units in the +z direction. This is to remove 'sameness' from the offset brick texture.

example code:
#declare stbHFarch_brick_texture_offset = <0,0,1.0>;

default = <0,0,0>

3.2.3 Heightfield manipuation

Here are some values which let you control two basic heightfield parameters.

3.2.3.1 stbHFarch_brick_res

Changes the resolution of the heightfield which makes the bricks. Use this if you are getting heightfield 'jaggies'.

example code:
#declare stbHFarch_brick_res = <200,200>;

default = <100,100>;

3.2.3.2 stbHFarch_brick_smooth

Do want the triangles making the heightfield to not be smooth? Use this.

example code:
#declare stbHFarch_brick_smooth = no;

default = yes



4.0 Speed Considerations

These macros are meant to parse and render quickly. The pattern the heightfield uses to make each brick is carefully scaled and translated to fit the heightfield exactly at render time. This is to ensure the least amount of heightfield space is wasted. For both the arch and pillar macros the heightfield brick is copied and rotated/translated several times. This is to save both RAM and parsing time.

There are times, however, when you may experience long parse times. This can be due to a number of things. The items in the following list can significantly increase parsing time:

*stbHFarch_brick_pattern_offset
*stbHFarch_brick_pattern_reset
*stbHFarch_brick_res

The first two items, if used, will make separate instances of the brick for either the 'stbHFarch_brick_arch' or 'stbHFarch_pillar' macros. That means each brick making up the object will be parsed independently from the rest. So, if you have an arch with five elements which previously took 1 second to parse, it would now take 5-10 seconds to parse! Combined with the last item, you may see very high parse times (not to mention RAM usage).

You may also consider not using the brick intersection feature. It will only make the render time longer. There is almost always a way around having to use it.

Additionally, if you intend to use a brick, arch, or pillar more than once in your scene, you may want to #declare it first, and then use it later. That way POV is not having to parse each macro individually.