Generator Guide

This is a guide to creating artwork suitable for converting to an online generator. It will tell you:

What a generator is.
How to make artwork for a generator using different methods:
- The Rectangle method for simple designs where all that is needed is a 3D perspective view of a rectangle.
- The Probe method for designers needing more flexibility, and willing to use Photoshop/GIMP/...
- The Blender method for animations and for designers needing maximum flexibility.

If you need any help, please don't hesitate to email support@makesweet.com.

What is a generator?

An online generator is a tool that helps you make something – buttons, custom t-shirt previews, etc. MakeSweet specializes in generators that create customized pictures or animations based on photos or words supplied by users. The distinctive properties of our generators are:

They can operate without any special server support.
Customization happens on the user's computer, saving bandwidth and CPU costs.
Unless and until the user explicitly chooses to upload a finished result, none of their material need ever cross the network while using the generator. This means that warnings about privacy (to protect the user) or the types of material that should not be uploaded (to protect the host) do not need to be shown during an initial “playing around” stage.
The artwork for the generators can be produced without knowledge of the workings of the generator technology.

There are three ways to produce artwork for standard MakeSweet generators: the Rectangle method, the Probe method, and the Blender method.

The Rectangle method is the simplest method. The designer pulls the corners of a rectangle to where they ought to be for a perspective view, for example on a billboard. This method is a good place to start, but for less simple scenes it is better to use the Probe or Blender method.

With the Probe method, a graphic design program is needed. It can be just about anything: Photoshop, GIMP, etc. Three special images must be created by the designer: a light image, a dark image, and a map image. This method works just fine for customization of a still picture with simple geometric shapes, but could be tedious for an animation or a complex model.

With the Blender method, designs made or converted to Blender (a fantastic free and open-source 3D content program) can be converted more simply. This saves some work, but requires knowledge of Blender. This is the only method currently available for making animations.

The Rectangle method

For very simple scenes, like a billboard, a generator can be made by just sketching a rectangle in perspective using the Design Preview Tool.

Design Preview Tool (opens on new page)

Click on the button in the tool to load a picture that has a blank area somewhere on it. This is called the “light image”, and should show exactly what you would want to see if a user tried to project an all-white image.

Then move the little red circles around. As you move the circles, a projection of a sample input is shown. When you are happy with the effect, click the green up arrow to upload your design and have it converted to a generator.

It is best to keep image dimensions less than 800x800.

If you find that the correct projection ends up overlapping areas it should not, you can add a “dark image” to fix this. You can read about how to prepare a dark image in the Probe method section.

The Probe method

It is possible to make generator designs using Photoshop or any tool that supports layers, transparency, (optionally) some form of 3D mapping filter, and export to the .PNG format.

Here is what you need to create:

An image showing what the result should be if the end user provides an all-white photo. This is called the “light” image.
An image showing what the result should be if the end user provides an all-black photo. This is called the “dark” image.
An image showing how a a standard test image (called the “probe”) should be distorted in order to map onto your design. This is called the “map” image. No shading effects should be applied.
If there are multiple independent surfaces, several map images should be provided. If their non-transparent content overlaps, be aware that only one surface will contribute to any given pixel in the result.

The light, dark, and map images should all have the same dimensions, and be in PNG format.

Let us look at a complete worked example, it will make things a lot clearer.

The light image

The first step is to get a nice scene to use for the generator. For this example, we'll use a simple picture of a TV (from http://www.sxc.hu/photo/580155). Scale and crop the picture to the desired size. For this example, we pick 400x300. It is recommended to keep images within 800x800 at the moment, in order for the generator to respond to the user without significant lag. Modify the image if needed to show what blank white input from the user should give. This is the “light image.” The TV picture we have looks blank and light as it is. It if didn't, or if it showed a program, we'd need to blank it out.

The light image, a picture of a TV. We take this screen to be showing a white input.

The dark image

Now we modify our image to show what a blank black input from the user should give. For the TV, that means we darken the screen. And, since there is a reflection on the surface that the TV is on, we need to darken the reflection of the screen as well.

The dark image, created here by selecting the screen area and darkening it. What we are trying to get here is how the TV would look when showing an all-black input. If you compare this very carefully with the list image, you would see that we have also darkened the reflection of the TV screen.

The map image

About all that remains to be done is to create the "map image." Here, we take a specific standard test image, and show where it maps to in the scene. The test image looks like this:

The probe, a standard 512x512 test image (full resolution version here).

For the TV example, we need to map the probe's pixels into the screen area, and then reflect them below the TV. We could also apply some barrel distortion to look more like a TV projection, but let's keep it simple for now.

The map image, showing the probe image transformed such that its pixels line up with where they would go on the television. No shading or any color transformation should be applied. The background should be left transparent.

The map and light image overlaid, just to highlight that the pixels of probe image line up where they should. Notice that the map covers areas outside the TV screen. This is fine, it has no effect since the light and dark images are the same in those areas.

That's all! Now we run our design through MakeSweet.

Making the generator

Preview and upload your design using the Design Preview Tool.

Design Preview Tool (opens on new page)

With this tool, you can do a sanity check on your design. Insert the light image, the dark image, and the map image, then see if the output shown is what you would expect. The preview may be a bit grainy and pixelated -- don't worry about that.

Once you have loaded the needed images, you'll be able to upload them to makesweet from the preview tool. Your design will be processed and a .swf file will be created. If you have trouble, email to support@makesweet.com. Here's the result we'd get:

The widget. Click the "plus" button to insert your own image on the screen (only if you are viewing this on a webpage, of course). Note the reflection. Requires Flash 10. Non-Flash based operation is possible, but requires some server support. This widget is completely standalone (download it). You could shove it in a blog post, copy it onto your webpage, whatever you like. It will continue to work even if MakeSweet is down, it doesn't depend on any external server (as long as you make a copy of it!)

There are a few further ways to customize the widget, don't be afraid to ask if there's something you need.

Making the map image (probe method)

Making the map image is the trickiest part of the Probe method, so let's look at it a little more closely. Basically, the idea is to show where all the pixels of a square image should get placed in your scene.

[NEW: since version 0.6, it is possible to skip the map image step for simple scenes. See the rectangle method.]

The light image, for a billboard picture. We take this screen to be showing a white input.

The dark image for the billboard picture. I selected the main billboard and darkened it, adding a small gradient.

The map image for the billboard picture. I applied a perspective transform to the test image to show where the billboard image should be placed.

Doing the perspective transformation. Here I'm using GIMP, a free and open source graphics program (get it here). In the toolbox there is a perspective tool. If you place the test image on a separate layer, and set it to be partially transparent, it is easy to visually move the image until it seems to line up with the billboard.

Once the perspective transform is done, set the test image to fully opaque, and hide anything in the background, so the background is transparent. Then save it, and you have your map image!

Now, we can preview and upload the design using the Design Preview Tool.

Design Preview Tool (opens on new page)

Here is what you can expect. The tool opens as a blank slate:

The preview tool starts off blank. Click on the one button showing to add the light image for your design.

We've added the light image. Now there is a button for adding the dark image, so let's go ahead and do that. [New: since version 0.6, a lot more buttons appear at this point. They can be ignored for now.]

We've added the dark image. Now there is a button for adding the map image, so let's go ahead and do that [New: since version 0.6, a lot more buttons are available at this point. They can be ignored for now.]

We've added the map image. That's everything we need! After a second or two, a preview of what our generator will produce will be shown...

There it is, a preview of what our generator will produce for a simple input image. Click the button that looks like that input image if you'd like to test with a different input. The important (although optional) thing to do now is to adjust the scale, so the image appears nicely in our scene. The scale is controlled by the horizontal slider.

There we go, that is a decent scale. Now we can click the big green button to upload our design to MakeSweet.

Click the "computer-to-world" icon to confirm that you permit an upload...

A new page will open, confirming that the upload has happened, and asking you to login to claim your upload. This is so that you can get emails about how its processing is going.

In the end, a .swf should be created for you...

And you can use it and publish it just like any other MakeSweet generator!

The Blender method

Input

We expect input in Blender (.blend) format. This input is called the “template.” The template can be a still or an animation. It should contain one or more materials that use an image tagged as customizable (tagging is done by a special prefix on the image name).

Output

A Flash (.swf) file, version 10.

Checklist

Controllable image: Your blend should contain at least one image whose name in Blender begins with “mkswt_”. This image will be replaced in the generator.
Complete cover: Please make sure that a controllable image, if replaced with a square image, will cover the entire visible surface of interest. Do not use the “Repeat” option to achieve this - tiling will give unexpected results when your image is replaced with user images.
Linear assumption: Make sure your design is “linear” in the following sense: the effect on the output of a change in an individual input pixel should be proportional to that change and independent of all other input pixels (ignoring sampling and anti-aliasing issues). Images projected on surfaces are fine, along with some non-geometric material manipulations. Reflection and refraction are fine if you are careful. Having the same image affect many parts of the scene is fine (although there'll be trouble if those parts start to interact).
Internal renderer: Design for Blender's internal renderer.
800x600: Your .blend should be set to render to 800x600 pixels. (This limitation will be lifted soon).
400x300: The custom part of your .blend should be easily discernible at half-size, 400x300 pixels.
You can get an idea whether your .blend is in good shape using the check_generator.py script. Instructions for use are given in the script.

Controllable image

Your blend should contain at least one image whose name in Blender begins with “mkswt_”. All such images will be replaced in the generator.

Two renders are done per frame, a “dark” render and a “light” render. In the dark render, every controllable image is replaced with an all-black image. In the light render, every controllable image is replaced with an all-white image. That, along with some mapping information generated during the render, is all the generator will know about the original .blend file. The generator will then use a linear assumption to produce custom renders quickly, going pixel by pixel and interpolating between the dark and light render based on the custom image(s) given by the user.

Configuration

Many templates don't need any special configuration. But if the default conversion doesn't do just what you want, you may need to tweak things. These options are being developed as needed, so if you run into a problem, just ask.

Add a Text object to your .blend, and name it “makesweet_config.txt”. An example of its content:

[all]
zoom = 2.0

This would have the effect of changing the default zoom of user-inserted images on all surfaces from 1.0 to 2.0.

Creating the generator

Blender designs can be submitted at http://live.makesweet.com/workshop. To create animations, please email support@makesweet.com.

Changes

This is a record of changes to this document.

Guide: move direct perspective text to a separate "rectangle method" for clarity
Guide: version changed to 0.6.
Guide: started a section on adding perspective directly.
Guide: made temporary note of changes to tool in affected figure captions.
Preview tool: version changed to 0.6.
Preview tool: added direct perspective sketching.