by Nicholas Sharp

^{This post is part of a series of guides on how to write your first ACM SIGGRAPH / TOG paper. You can find the other articles here.}

Your SIGGRAPH project has resulted in something new and exciting, congratulations! Releasing great open-source software is a crucial last step of sharing it with the world.

This post is a tutorial on how to make your code release a success and amplify the impact of your work. It’s part of a series of blog posts on writing your first SIGGRAPH paper.

Why release code?

Releasing good code can dramatically increase the reach of your project, benefiting you–and many others–for years to come. More people will know about your project, use your method, and cite your paper—even distant users that you might never expect! In principle, a clearly-written technical paper provides all the details needed to implement a method, but in practice the burden of reimplementation is often an insurmountable hurdle. By providing ready-to-use code, you give an easy path for others to access your work.

Additionally, software is a form of communication. It precisely describes all of the little details of your research in unambiguous language, a valuable complement to the mathematical descriptions in a paper and the verbal descriptions in talk. In my experience, some readers will find it much easier to understand a new method by reading well-documented code than by reading a paper!

Lastly, code releases greatly improve reproducibility & replicability in computer graphics, that is, the ability to reproduce the published results of a method. When canonical code is released, it serves as a public reference point for a particular method, enabling the community to move forward and collectively do better research.

The basics

First and foremost, releasing code does not mean simply uploading the project code folder from your machine! The primary act of preparing a code release is converting your “experimental” code into software which is ready to be used by others. Other important aspects include documentation, hosting, and licensing. There’s a lot to think about, and it’s okay if you can’t do everything perfectly right, but every hour you invest will pay dividends in the long run.

Before going further, I should clarify that this tutorial will focus mainly on releasing “artifacts”, one-off codebases which are typically associated with a single paper. Developing large, general libraries or maintaining complex software systems projects is a very different challenge, which has more in common with mainstream software engineering practices.

Timeline

When working on a research project, you rarely write clean, well-documented code from the start, especially near a deadline. I generally recommend preparing a code release after your paper has been accepted, but before it is presented at the venue, around the same time you are preparing a talk.

In some cases, you might be able to prepare a basic version of your code earlier, for submission as supplemental material. If possible, this is great! Some reviewers are very appreciative when supplemental code is included with a submission. If your code is not ready for review, but is ready before the “camera ready” deadline for the paper, you can generally still include it with the final submission for the official archive (though policies may change; be sure to confirm these details).

As time goes on, think of your code release as a tapering process—you do a lot of work at the beginning, a little work after the initial release to add features and fix some bugs, and then later you just fix the occasional issue or update broken dependencies. Unlike managing a large living software project, paper artifacts rarely require significant time commitments over extended periods of time.

Hosting

Where should you actually put your open source code? These days, public version control websites like github and bitbucket are excellent options. They are reliable, searchable hosts, and seem likely to persist for many years to come (although they are not without some criticisms). Create a repository for your project, either under your personal account or some organizational account, and start committing/uploading code. For this purpose, it is even okay to do a single large “upload”, committing all of the files at once. If your repository is ever publicly visible in an unfinished state, add prominent text indicating as much.

Hosted version control like github can be used in addition to releasing a zip file archive of your code. Ideally, an initial version of your code can be submitted with your paper to the ACM Digital Library, while a github page offers a discoverable and updatable home for your code, incorporating new features and fixes.
That being said, if short on time, releasing on github is probably the more impactful aspect.

Licenses and ownership

Software licenses dictate what others can do with your code, particularly in terms of (a) modifying & redistributing it, and (b) making money from it. This is a complicated subject—I am not a lawyer, and this is not legal advice!

In short, I strongly recommend an “MIT License” for research code. It is a very permissive license, which allows others to modify your code however they want, and even to use it in for-profit projects. At first, this sounds bad—what if someone steals your code? And don’t you deserve to earn some profit? But in reality, both of these outcomes are very rare, and on the positive side a permissive MIT License will further increase the impact of your code; any more restrictive license would create a significant barrier for those in the industry to use your software.

There are some exceptions. Your employer, your funding source, or those of your coauthors may place restrictions on how you can license the resulting code. Or perhaps you have an actionable plan to commercialize or otherwise profit from your research. If so, there are many other licenses available, and a code release is still very beneficial! Discuss these concerns early in your project to ensure there are no misunderstandings among the authors, and consider seeking real legal advice if you wish to retain exclusive commercial rights to your code.

7 tips for a great code release

The specific steps you follow to release code will vary greatly depending on the project and your own work habits. Rather than trying to list all possible steps, the rest of this tutorial will be a loose collection of concrete tips and best practices to help you be successful.

1: Make time to do it right

The single most important ingredient for a successful code release is you, the author, committing to invest time to make it happen. You might spend months preparing and fine-tuning the text of a SIGGRAPH paper to share your research; shouldn’t you at least spend a week releasing code, which is another important channel for sharing research? It may be difficult, because releasing code comes late in the process when a project is seemingly “done”, but investing that last week to release quality code will be worth it in the long run.

2: Libraries vs applications

For some projects, code releases are best structured as a library: a collection of functions or data structures that are integrated into other software. Other projects are better suited as an application: desktop/web/mobile programs which are driven by a human to create an experience or process some input. Think carefully about which approach makes more sense for work—how do you imagine others might want to use your code?

The best-of-both-worlds approach is to release code as a library and as an application. Implement your project as a library with general-purpose functions which can be called for key subroutines, and then build a separate standalone application on top of that library.

If you don’t have the time time to fully reorganize your codebase, focus on preparing the minimal necessary functionality that will allow a user to try out your method, or reproduce a key result from your paper. Once they have seen it work, they will be more willing to dig through your code and adapt it for their purpose.

3: Keep it small

It is not necessary to include every single thing which appears in your paper in your code release. This is especially true in SIGGRAPH papers, which might include a wide variety of demonstrations and comparisons. Identify the core functionality of your work, and condense it down to a simple command line tool, an easy to use GUI, or even a single function that can be called.

Various advanced features can be added to your code release as-needed, and it is okay if they are less well-documented or more difficult to use than the core functionality. Invest most of your energy preparing excellent code for the simplest, central idea of your project.

4: Code with users in mind

When we write code for a research project, we are motivated by “how can I perform this experiment?” When releasing code, instead ask “what will others want from this code?”

For instance, if someone else wants to pass their own data in to the code, what file formats might they want to use? How might they want the output? What pitfalls are they likely to encounter that can be anticipated and handled intelligently?

Let these kinds of questions guide you in preparing your code for release. If you find it even a little difficult to use your own code, then outsiders will find it extremely difficult to use!

5: Ready-to-run examples

Include at least one extremely easy-to-run sample in the repository. This provides a direct path for anyone to get started with the code!

If input data is needed, package at least one sample input in a subdirectory. For a command line application, provide copy/paste-able instructions to install and run the software. For a GUI application, include explicit step-by-step screenshot guides. The more direct, the better.

6: Documentation and images

Documentation is accompanying text which explains the usage and function of code. Documentation can take the form of inline comments in code, external documentation pages, or simply a text file—any of these is perfectly fine! What matters is that you include clear and precise text explaining what your code does. It is most important to document the public-facing portions of your code that a user actually interacts with, but documenting internals is also a valuable exercise in technical communication.

Readers are always drawn to appealing visuals. If possible, include exciting figures to show users what they will get from your code. These images will draw in casual passers-by, and advertise your work. Include at least one exciting image in your project’s top-level README or introduction, and use diagrams and figures within documentation wherever possible. Reuse your paper figures if you can!

7: Cross-platform code & bit rot

It’s very easy to write code that works great on your computer, but can’t be used on anyone else’s—and if you think it’s bad now, imagine trying to run your code in 20 years!

Most importantly, be sure to try compiling/running your software on machines other than your own before your release it. More generally, try hard to minimize the number of other software packages that your code depends on—simple dependency-free terminal applications are much more likely to survive the test of time than complicated applications built on frameworks which may be abandoned in 20 years.

Carefully document the versions of any dependencies which you do need, as well as steps used to compile or run your software. Include beginner-friendly instructions to help users unfamiliar with your toolchain run your code now and in the future.

Wrapping up

Hopefully this tutorial gives some guidance on releasing code for your first SIGGRAPH paper. Remember, all of this is a lot to get right, and you don’t have to do it all perfectly the first time! Your best-effort will still be greatly appreciated and valuable. Check out the other posts in this series for more tips on writing your first SIGGRAPH paper.

This post is part of a series of guides on how to write your first ACM SIGGRAPH / TOG paper. You can find the other articles here.

_{We thank Lingxiao Li for proofreading.}

by Ruben Wiersma, TU Delft

^{This post is part of a series of guides on how to write your first ACM SIGGRAPH / TOG paper. You can find the other articles here.}

This guide will show you how you can create figures that are intended to explain and clarify ideas from your paper. High-quality figures can simplify complex explanations and improve the presentation of your paper. In this guide, we’ll cover the entire process from conceptualising figures to producing them with a combination of Illustrator and Blender. Be sure to check out part one on rendering paper figures with Blender by Silvia Sellán if you haven’t yet!

First of all, I’d like to credit the people who inspired my style and process: Keenan Crane and Nicholas Sharp. Keenan has shared a very nice presentation on his process for creating figures, which I strongly recommend if you’re interested in creating beautiful, informative figures.

The Process

In this post, I’ve structured the process according to three main steps:

1. Planning figures as part of your paper’s ‘story’
2. Sketch and iterate
3. Creating figures in Blender and Illustrator

If you’d like to jump into the nitty gritty illustrator + blender stuff, scroll to the creating figures in blender and illustrator heading.

Along the way, I’ll use some example figures I created for a recent SIGGRAPH paper: DeltaConv. It suffices for now to show you the introductory figure and say that the paper deals with an issue of using local coordinate systems on surfaces and how to solve that when you want to generalise CNNs from images to curved surfaces. In this post, I’ll show you how I got to this figure and try to draw some lessons that you could use in your own paper.

Guiding principles

To start, let’s establish a guiding principle: a paper figure should be judged by how well it serves its purpose: Does it communicate insight? Many figures can be made better and prettier just by asking this question. Not with a special font, nor that fancy suite of software.

The next principle: good design is all about iterating until the figure is just right. Use tools that allow you to iterate quickly and progress to a more complicated tool in steps: iterate with a sketch on paper to figure out how you want to illustrate the concept and try out some compositions; then create a rough version in your preferred graphics software to figure out how you can translate the concept to clean lines and simple forms; finally create a polished version where you pay attention to alignment, tiny details and materials.

Planning figures

In an ideal situation, you think about where you would need figures as you are structuring and writing your paper. You can add placeholder figures (empty squares) to think out how your figures fit the flow of the story and give them captions that describe what each figure should show. Think of figures as backdrops for the main plot points in your paper and go along them from the perspective of a reader: add a figure wherever you think the reader might need some visual support.

Figure 1 was a solution to three ‘needs’ that arose when writing the paper:

1. we needed to show the problem, as the figure would act as a teaser for the paper,
2. we wanted people to think of coordinate systems on the surface, rather than in 3D (set the right mindset), and
3. we wanted our audience to know that the approach could work on point clouds.

Each of these requirements arose from feedback from collaborators as well as responses we got from external reviewers.

If you’re not sure how to identify this ‘need for a figure’, try to explain your core ideas to another person and take note of where your discussion partner gets stuck or when you try to visualise a concept with gestures. Maybe you refer to some ‘real-world’ concept, or you have the urge to draw the situation. That’s where a figure will likely help a reader as well.

Sketch and iterate

When you have identified the need for a figure and thought about what you want the figure to show, you can start creating it. A first step is to look at other examples that describe a concept close to what you’re trying to say, such as figures from text books.

For Figure 1, there were lots of figures in other texts that show the core idea: local coordinate systems on a curved surface. Here’s just one:

Then, start creating in the medium that lets you explore and iterate ideas as quickly as possible. Good-ol’ pen-and-paper will do.

Here’s what that looked like for our intro figure.

It’s fine for a sketch: it tells us which components we want in it and gives some clue for the layout. It satisfies two of our goals (showing the problem, and setting the right mindset), but I’m not yet showing the audience anything of a point cloud. We’ll get to that in a later stage.

Iterate a couple of times on your sketch and try replacing your placeholder with the sketch. If you read through the text, does the figure show you what you were expecting to see?

Creating figures in Blender and Illustrator

I know that I said that better software alone wouldn’t give you a prettier figure, but let’s nuance that a bit: some tools are better suited than others. In general, I prefer using vector graphics, as they can be scaled to any size without sacrificing on quality. If you export a vector graphic as a PDF, you can directly import it in your LaTeX file as a figure. The paper PDF will be infinitely zoom-able with a minimal memory footprint.

I use Adobe Illustrator for vector graphics, but you’re free to use any tool you like. Sometimes you can get Illustrator through a license from your university or research group. If you don’t have that luxury, a free alternative is Inkscape. Every step I show can be recreated in any tool with support for vector graphics. If you are completely unsure how to pick one, try to find software that gives you direct control and the ability to align and distribute elements automatically.

In Figure 1, we have both a flat, 2D image and a curved surface in 3D. It’s best to use 3D modelling software to shape the 3D surface. I’ve tried to ‘fake’ it before in Illustrator, but it’s really tricky to get right. Our eyes can always spot a line that is just a bit too slanted or an oval that is thinner than it should be. We’ll use a combination of Blender and Adobe Illustrator to make figures of curved surfaces.

Why Blender? If you’re familiar with other kinds of 3D software (like 3DS Max, Maya, or Houdini) or have colleagues who can help you out with your figures, there’s no need to stick to Blender. The reason we suggest Blender in these posts, is that it is free and open source. In addition, Blender has grown a lot in recent years, both in quality of use and quantity of users, and has become a very usable and extendable piece of software with lots of community attention and support.

Getting started in Illustrator

Open up Illustrator and create a new file (File > New…). A window pops up where you can pick a document size. This can be somewhat confusing if you’re used to tools like Gimp, Adobe Photoshop or PowerPoint because

1. you probably don’t know how large you’d like your figure to be and
2. vector graphics don’t really have a ‘resolution’, since they’re defined as mathematical equations.

It doesn’t really matter which document size you pick. You can always resize the artboard (the name for the canvas in Illustrator) at a later moment. I typically choose ‘common’ in the ‘web’ tab, because it gives me enough room to work with.

The second choice we need to make is the color mode. RGB is used for screens, CMYK for print (Cyan, Magenta, Yellow, blacK). In most cases, I pick RGB, unless you know your figure will only be used in print. More often, people will view your paper on digital screens, so you can design your figure in the way it’ll be viewed most often. This can also be switched later on.

Click on ‘Create’ to open the new file.

Next, you’ll see the canvas and the main tools in Illustrator. In this tutorial, we’ll go briefly over some core tools. First, some basics: I’ll refer to the main blank area as the canvas (a.k.a. the artboard). This is where you can draw your vector graphics.

• You can draw graphics with the tools in the toolbar (left).
• Each of these tools has settings that you can control in the control bar (top).
• The elements of your artwork are placed in layers (right).

The one tool that you can always return to if you’re stuck is the selection tool (press V on the keyboard). You can select and move objects with this tool and this usually gives you the behaviour you expect from a typical cursor.

Tip If you right click on the tool icons, you’ll see more options and the corresponding keyboard shortcuts. Try and learn those shortcuts, they’ll make your life much easier.

We’ll start by importing the sketch and recreating it with some of the basic tools in illustrator.

The easiest way to do this, is to simply drag-and-drop the sketch onto the canvas.

You can resize any object in Illustrator proportionally by holding shift while dragging the corners of the object. We’ll also set the opacity to 30%, so we can see through the reference.

Next, lock the layer, so we don’t have to think about accidentally clicking the image all the time and add another layer below it to draw the figure.

Now we can start to roughly block out our figure in Illustrator using some of the basic tools (keyboard shortcuts in parentheses): the pen tool (P), the rectangle tool (M) and ellipse tool (L). You can always hold shift when using these tools to make sure that the elements are scaled proportionally (a square stays a square) or that the lines you draw are on a straight line.

Click the rectangle tool (M) and then click and drag on the canvas while holding shift to draw the main components.

Next, draw the circles on each of the coordinate systems with the ellipse tool (L). Hold shift and alt/option while dragging from the center of the squares to draw uniform circles (shift) that are centered around the cursor (alt). If you want to make sure that you place your cursor exactly at the center, check that smart guides are enabled (Menu > View > Smart guides).

Change the fill to black and stroke to empty.

Finally, let’s use the pen tool (P) to add some curved lines and the surface. The pen tool lets you draw Bézier curves. You can add control points by clicking on the canvas. If you click and drag, you can also adjust the handles of the control points. The handles influence the shape of the curve. If you ever need to adjust a control point later on, you can use the direct selection tool (A), which allows you to adjust individual control points and handles.

Add the center arrow in the figure using the pen tool. And click esc to finish the curve.

Adjust the stroke properties to add arrowheads. Click on Stroke in the control bar and select the arrowheads you want. Then scale them down to the size that fits.

We’ve covered almost all of the tools you’ll need to get started:

• the selection tool (V) to select and move objects,
• the direct selection tool (A) to select and move control points,
• the rectangle (M) and ellipse (L) tools to draw primitives,
• the pen tool (P) to draw Bézier curves.

You’ll probably need one more thing: text. You can add text with the type tool (T). Click and drag on the canvas with the type tool to add a text box and type the text you want. If you want to adjust the character settings (sub/superscript, kerning, etc.), you can click on Character in the control bar. If you need to adjust things like alignment, click on Paragraph in the control bar.

It’s nice to have the fonts in your figures and the paper match. Either you can use the fonts used by the ACM template:

• Linux Libertine
• Linux Biolinum

Or use a neutral sans-serif font. These are nice to use if you’ll use your figure in other settings as well:

• Source Sans Pro
• Helvetica
• Arial

The result of this process is the following figure.

Before we head over to Blender, some general remarks and tips:

• Group objects by pressing ctrl/cmd + G to keep your file organised. Ungroup with ctrl/cmd + shift + G.
• You can duplicate objects by using the selection tool (V) and holding alt/option while clicking and dragging the object along the canvas. You can also press ctrl/cmd + D to duplicate.
• You can arrange objects from back to front with the shortcuts ctrl/cmd + } (bring forward) or ctrl/cmd + { (send back).
• It’s important to evenly align and distribute objects. Your figure can look sloppy if things are off even slightly. You can use smart guides as shown before to snap objects along automatic guides as you move them. If you need more precise control, you always align and distribute objects by selecting multiple objects with the selection tool (V) and using the alignment and distribution buttons in the control bar. These are also available under Menu > Window > Align.

Illustrator to Blender

In Blender, we’ll create a simple surface, add images from Illustrator in 3D and render to an image that we’ll use in Illustrator again. We could, of course, build everything in Blender but that’s probably overkill.

I’ll assume you know a bit about Blender. If you don’t, be sure to check out Silvia Sellán’s guide, or follow the donut tutorials by Blender Guru.

Start by removing the basic cube (select the cube, press X, press enter) and add a grid (shift + A, Mesh > Grid).

We only need two subdivisions along each axis. Just having two subdivisions makes it easier to edit the mesh later on.

Go into edit mode by pressing Tab and make sure can select vertices by pressing 1 on your keyboard. Then select some of the corner vertices and move them along the z-axis (G, followed by Z). In the sketch we made a saddle-like surface, so we’ll mimic that here.

Go back into Object mode by pressing Tab and select the modifier tab (right, wrench icon). Add a subdivision surface modifier and increase the number of subdivisions to 3. Right click the object and select shade smooth to get a smooth surface.

You can go back into edit mode to adjust the vertices to your liking. If you like, you can add some loop cuts toward the edges to sharpen the corners.

Add a material to match your style. I like having a surface with muted pastel colours and high roughness, as it gives a nice matte look.

Finally, I created a coordinate system image in Illustrator and exported it as a PNG.

The quickest way to import this image into Blender is to enable the Import Images as Planes add-on.

Then add an image as plane (shift + A, Image > Images as Planes) and select the image you want to add.

Rotate the image plane to align with the x-y plane (press R, lock to y-axis by pressing Y, and type 90, followed by Enter to rotate 90 degrees).

Next, add an Ico Sphere at the center (shift + A, Mesh > Ico Sphere). Give the sphere a dark material, shade smooth, and add a subdivision surface modifier to smoothen it. This sphere will act as a point in the point cloud.

Finally, parent the image plane to the sphere: select the plane, then hold shift and select the sphere, then press ctrl/cmd + P.

Turn on Snap and snap to Faces. Now you can grab the point and move it along the surface to a place where you like.

We could even add a relationship between the normals of the surface and the image plane to make sure they align, but let’s keep it simple for now. Move the point to a nice location on the plane and rotate the plane to a good orientation that is roughly tangent to the surface.

I had to turn off Snap and offset the plane slightly from the surface to reduce intersections.

We’re almost there! Now we just need to add some points to the surface, to imply a point cloud.

Duplicate one of the ico spheres, select the surface and go to particle system tab (icon of graph). Add a particle system by clicking the plus sign.

Set to a Hair. Under Render select Render as > Object. And pick the ico sphere under Instance Object. Adjust the scale to match the other points.

If you like, you can assign a vertex group to guide where the points should be spawned.

Finally, it’s time to render the image and bring it back to Illustrator.

Lights. Add an area light behind the camera, pointing to the surface and a smaller area light from the side to fill the shadows.

Camera. Place the camera in the position of your viewport by pressing ctrl + alt + numpad 0.

Action! In Render Poperties, select cycles as the render engine and under Film, check Transparent. Set the number of samples for the render to 32 or some other low number. Then render the image (Menu > Render > Render Image).

Once you’re done rendering, go to Image > Save Image in the render output to save the output.

From Blender to Illustrator

Now, we can bring the rendered image back into Illustrator by drag-and-dropping the file. I’ve changed some of the colours to harmonise better and added the coordinate systems I designed in Illustrator.

Finally, let’s crop the artboard and save the file as a PDF (File > Save as… > select PDF). Now you can use this file in your LaTeX document.

Recap and next steps

We’ve gone through the following steps to create an explanatory figure:

• Planning and sketching figures.
• Using Illustrator’s tools to create vector graphics.
• Making simple shapes in Blender and including images as planes to incorporate figures from Illustrator.
• Bringing back images into illustrator and saving as a PDF.

We’ve only scratched the surface of what’s possible in Blender and Illustrator. I’m excited to see what you’ll design!

Some things you can try out for yourself:

• Add outlines and tracings to your surface. You can either do this by hand in Illustrator or generate outlines automatically by enabling Freestyle in Blender’s Render Properties.

• Use Geometry Nodes in Blender to create figures procedurally. You can use this to import experimental data or create figures that are easily changed later on.

• Animate your Blender illustration by using keyframes for presentations.

This post is part of a series of guides on how to write your first ACM SIGGRAPH / TOG paper. You can find the other articles here.

by Craig Reynolds

^{This post is part of a series of guides on how to write your first ACM SIGGRAPH / TOG paper. You can find the other articles here.}

Some posts in this series cover a lot of technical detail. This one is less formal and more squishy, concentrating on stylistic issues for writing the introductory section of a technical paper.

In one sense the title, abstract, introduction, and entire paper, are increasingly longer versions of the same ideas. But they have different roles which should guide their construction. A good title is memorable and descriptive. The title and abstract are frequently read by someone who is deciding if they want to read your paper. If the answer will eventually turn out to be no, you will help them make better use of their time—allowing them to make an early exit—by being specific and concrete in your abstract and introduction.

An introduction is most useful when it helps align the reader’s expectation with your perspective of the paper’s content. Often a title will catch my attention, then I find the abstract a bit confusing, and I am well into the body of the paper before I realize that I misunderstood something about the paper’s scope. Perhaps unfamiliar terminology caused some ambiguity. Or the author’s assumptions and perspective were not made sufficiently clear. If a reader has not correctly understood the context, the body of the paper may feel confusing. 

This is unfortunate when the reader is another scholar seeking to understand your work. It is even worse when the confused/frustrated reader is a reviewer deciding whether your draft paper will be accepted for publication. As an author you should work hard to ensure the typical reader can easily understand your exposition. This effort will be rewarded by helping a reviewer see the value of your contribution.

Some basics

At a minimum, an introduction should provide needed background. Initially assume your reader knows nothing about your specific topic. In a few sentences, explain the topic in simple concise language that could be easily understood by almost anyone. Then in a bit more detail, describe the specific topic of your paper. Explain what is unknown or unsolved, and how your research seeks to fill that gap. The introduction should function like a funnel, leading readers with various backgrounds and perspectives to become aligned with your view of the topic and your approach to solving an aspect of it. This helps them assimilate what follows.

Experts in your field probably know what you are talking about, the introduction is a chance to catch the attention of non-experts, or experts from other fields, who may be surprised to learn they are interested in your research. For those readers, your paper could be the first time they have even thought about this topic. Craft your introduction to lead these readers to a basic understanding.

If your topic has been well trod by other researchers, be sure to explain how your approach is unique, or perhaps how it works better than others. It might help to imagine a potential reader who has just read two other papers on this topic, and is trying to decide if yours is worthwhile. Can you convince them to read on?

Order of writing: some authors find it easiest to start in the middle of your paper, with the technical aspects on which you have been focused for so long. Once the middle has been drafted, the introduction can be written to provide a smooth “on ramp” into the gist of the paper. In this approach the abstract is written last, after the introduction.

Alignment

Bear in mind that you have been focused on your paper’s topic for months, if not years. You are not a good judge of what is obvious and what will be a confusing stumbling block to a reader coming in cold. It can be useful to have others read your introductory materials (title, abstract, introduction). Others in your research group may have useful feedback but in a sense they “know too much.” It is especially helpful to recruit people with significantly different backgrounds. People from other labs perhaps, or better, people from other departments. Can that friend of a friend over in biochemistry (or political science, or history) make any sense out of your introduction? Significant others or family members may help spot missing steps you forgot to mention because they are “obvious.”

If you can get someone with a differing background (perhaps wildly differing) to try to read your introduction, take careful note of questions they ask. (“What does this word/acronym even mean?” “You use this phrase in a way that seems different from everyday usage.”) These are ideas you must express more clearly. Add a sentence to explain a problematic word. Explicitly point out how a phrase is used differently in the context of your work. If your relationship (with this non-colleague, non-technical) reader permits, perhaps ask them some simple, gentle questions about what they read. Did they manage to follow most, or any, of the points you tried to make?

If your paper is published, most who read it will be in a field close to yours, and so understand your terminology and perspective. On the other hand if you are lucky, your paper might have broad appeal and may attract scholars from other fields. Someone in your field, say your boss, or a reviewer, will not be put off by an extra sentence of explanation or clarification at the beginning of your paper. And it can be especially helpful to a reader with a different background.

While the abstract needs to be concisely worded, there is room in the introduction to make clear what is not in your paper. If your technique could be applied in 2d and 3d settings, the introduction should make explicit how it is used in your paper. Resist the temptation to be vague to make your technique seem more widely applicable (2d and 3d) if you only discuss one case.

If you wonder why you should put effort into helping others decide more quickly not to read your paper, flip it around. Say you are on deadline, deciding which of several papers to spend time reading. You would certainly appreciate a paper that avoids wasting your time by being clear up front what it is not about.

Any sort of abstractions, or simplifying assumptions, that are key to an initial understanding of your technique, should be called out in the introduction. You might have decided early in your research to make a simplifying assumption to make this first step toward a larger research goal. Be sure to explain this in the introduction: why the simplifying assumption is reasonable, and how it can inform the more general case. A danger here is that you may think of your work a being on the larger topic X, but forget to clarify that this paper is actually about “topic X, for the case where β=0.”

Additional resources

Some other articles about how to write a paper’s introduction. These are general guides from universities intended for students. There are also lots of commercial services providing proof reading and copy editing services. We are assuming you and your coauthors will do all the writing and editing for your paper:

• Journal Article: Introduction — CommKit, MIT Communication Lab
• Writing a Scientific Paper: Introduction — UCI Library
• Writing an Introduction for a Scientific Paper — U Wisconsin, WAC

Ideas about how to introduce your topic to a reader who is unfamiliar with it and help them understand why it is interesting:

• WIRED’s 5 LEVELS, videos where an expert “…Explains One Concept in 5 Levels of Difficulty.” These might help you think about how to demystify the topic—in which you are now an expert—so it can be more easily understood by others.
• Two Minute Papers by Károly Zsolnai-Fehér. While the videos have gotten longer over the years, h​​​​​​​is energetic and upbeat delivery will convince you the topic and this paper are fascinating.

Kevin Kelly wrote a list of 103 Bits of Advice I Wish I Had Known including: “Spend as much time crafting the subject line of an email as the message itself because the subject line is often the only thing people read.” A journal paper is not an email, and the ratio of time spent might be different, but crafting an effective introduction can significantly increase the audience for your paper.

Annotated example

Introduction used with permission from: Nielsen, Bojsen-Hansen, Stamatelos, Bridson. 2022. Physics-Based Combustion Simulation. ACM TOG 41, 5 (2022) https://doi.org/10.1145/3526213

This post is part of a series of guides on how to write your first ACM SIGGRAPH / TOG paper. You can find the other articles here.

_{We thank Yu Wang for proofreading.}

by Oded Stein, MIT

^{This post is part of a series of guides on how to write your first ACM SIGGRAPH / TOG paper. You can find the other articles here.}

This tutorial will help you to set up the LaTeX environment to write
your first ACM SIGGRAPH / TOG paper.

What is LaTeX?

LaTeX is an old text editing software that works differently than Microsoft Word / Google Docs or other modern text editors you might be used to. LaTeX is closer
to programming than it is to Microsoft Word. In LaTeX you write your text together with commands in a plain text file, and this plain text file is then compiled, like a program, to a PDF. There is no direct editing of the document. If you want to change someting in the PDF, you edit the source plain text file, and you recompile the document.

LaTeX has many advantages and it has many disadvantages. It is possible to create very professional-looking mathematical formulas, and most maths textbooks you are familiar with probably created their formulas with LaTeX. On the other hand it can be very difficult to control. Unlike in Word, you cannot really decide where in the document your figures end up, and where a pagebreak will be.

LaTeX is actually a collection of programs that have accumulated over time. As such, in order to install it, you usually install a LaTeX distribution that contains all programs needed. I recommend different distributions for different operating systems:

• Windows: MiKTeX
• Linux: TeX Live. Install directly from the website or via your favorite package manager.
• MacOS: MacTeX.

These distributions come with their own text editors to edit LaTeX source, but you can use your favorite editor that you already use for code. Most editors have syntax highlighting for LaTeX in one form or another.

You can skip all of this by using an online hosted LaTeX service like Overleaf. Overleaf will make sure that they have a correctly set up LaTeX environment with all needed packages.

This tutorial is not a LaTeX tutorial. Luckily, there are many good LaTeX tutorials online, here are a few:

• https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes
• https://typeset.io/resources/learn-latex-beginners-step-by-step-guide
• https://www.tug.org/twg/mactex/tutorials/ltxprimer-1.0.pdf

LaTeX template

In order to create a SIGGRAPH / TOG LaTeX submission, you must use the official ACM template, which is available here: https://www.acm.org/publications/proceedings-template. Scroll to the bottom of the page and download the template.

The folder contains a lot of files that you do not need for a SIGGRAPH / TOG paper. Feel free to delete all files except for

acmart.bib
acmart.cls
ACM-Reference-Format.bst
samples/sample-acmtog.tex
samples/sample-sigconf.tex

Depending on whether you submit to SIGGRAPH or TOG, you will need the sample-acmtog.tex or sample-sigconf.tex file. I usually remove that file from the samples directory, place it in the root directory, and rename the tex and bib files to the name of my paper:

mypaper.bib
acmart.cls
ACM-Reference-Format.bst
mypaper.tex

Here is a generic stripped-down LaTeX document you can use for TOG.

Here is a generic stripped-down LaTeX document you can use for SIGGRAPH.

Begin by choosing a title for your article.

\title{My Paper}

Before you submit, you have to fill out CCSXML and keywords. Go to http://dl.acm.org/ccs.cfm to pick the correct categories for your paper.

\begin{CCSXML}
<ccs2012>
 <concept>
  <concept_id>10010520.10010553.10010562</concept_id>
  <concept_desc>Computer systems organization~Embedded systems</concept_desc>
  <concept_significance>500</concept_significance>
 </concept>
 <concept>
  <concept_id>10010520.10010575.10010755</concept_id>
  <concept_desc>Computer systems organization~Redundancy</concept_desc>
  <concept_significance>300</concept_significance>
 </concept>
 <concept>
  <concept_id>10010520.10010553.10010554</concept_id>
  <concept_desc>Computer systems organization~Robotics</concept_desc>
  <concept_significance>100</concept_significance>
 </concept>
 <concept>
  <concept_id>10003033.10003083.10003095</concept_id>
  <concept_desc>Networks~Network reliability</concept_desc>
  <concept_significance>100</concept_significance>
 </concept>
</ccs2012>
\end{CCSXML}

\ccsdesc[500]{Computer systems organization~Embedded systems}
\ccsdesc[300]{Computer systems organization~Redundancy}
\ccsdesc{Computer systems organization~Robotics}
\ccsdesc[100]{Networks~Network reliability}

In addition to CCS, make sure to also specify some user-defined keywords for your article. They can be arbitrarily chosen by you. Pick the ones you think describe your article best.

\keywords{relevant,key,words}

If you submit to SIGGRAPH, make sure to enter a submission ID!

\acmSubmissionID{123-A56-BU3}

You will have to fill out the copyright and journal commands after acceptance.

\setcopyright{acmcopyright}
\copyrightyear{2018}
\acmYear{2018}
\acmDOI{XXXXXXX.XXXXXXX}
%
\acmJournal{TOG}
\acmVolume{37}
\acmNumber{4}
\acmArticle{111}
\acmMonth{8}

You will also have to fill out the author info after acceptance.

%% Authors
\author{First Author}
\email{firstauthor@example.com}
\orcid{1234-5678-9012}
\affiliation{%
  \institution{First Institution}
  \country{Firstcountry}
}

\author{Second Author}
\orcid{1234-5678-9012}
\affiliation{%
  \institution{Second Institution}
  \country{Secondcountry}
}

\renewcommand{\shortauthors}{Firstauthor et al.}

This author info should include your ORCID. If any of the authors do not have an ORCID yet, you can set up your ORCID here: https://orcid.org/register

Finally, after your paper has been accepted, you can turn off the review mode and deanonymize your article by changing the first command to:

\documentclass[sigconf]{acmart}

OR

\documentclass[acmtog]{acmart}

Generic LaTeX tips

While we will not go over how to use LaTeX here, there are a few generic hints that will help you be more productive when using LaTeX. I use these practices for every article I write.

1. Use macros extensively. In LaTeX you can you can define a macro using the syntax \newcommand{\commandname}[2]{first argument: #1, second argument: #2}. You will probably use a lot of mathematical language, which can be very wordy in LaTeX. Make your documents more readable by using macros for these. For example, I usually use the following macro for R2,\newcommand{\Rtwo}{\mathbb{R}^2}, and the following macro for the norm of a vector, \newcommand{\norm}[1]{\left\lVert #1 \right\rVert}.
2. Use different LaTeX files for different sections of your paper. So, for example, instead of having the main part of your article consist of a single file with all of the text included,

\section{Section}
Text

use different files and import them into your main file with \input{file}.

\input{introduction}
\input{relatedwork}
\input{definitions}

This helps organize your document. If you have collaborators, this also allows you and your collaborators to work on two different files at the same time without risking conflicting edits.

3. Use versioning to keep track of your changes, as well as making collaboration easier. There are two options I recommend for this:

• Use git to keep track of your edits. Here is a basic guide on how to use git. This gives you full control over your article, works even without an internet connection, and does not make you dependent on any third party.
• Use an online LaTeX editing and versioning system like Overleaf. Overleaf handles all the hosting and the versioning for you. The downside of this is that, in times of high demand, the quality of Overleaf service can be spotty.

Bibliography

In LaTeX you will use BibTeX to cite other articles and manage your bibliography. Like LaTeX itself, BibTeX is vast and complicated (here is a guide). We will here look at a few basic and simple tips on how to use BibTeX.

Your references are located in a seperate .bib file. You import it into the main LaTeX document with the following command, which you should put at the end of the document, where you want the bibliography to appear:

%% Bibliography.
%% Uncomment the bibliography line and link to an actual bib file
\bibliographystyle{ACM-Reference-Format}
\bibliography{bibliography.bib}

The .bib file contains the items you can cite in its own special format. Please refer to the BibTeX guide for a more complete explanation of the format. Many journal websites contain an easy way to export BibTeX information for an article. For the ACM digital library, you can find BibTeX citations for any article here:

Beware: The citations that are available on journal formats often contain a lot of extraneous information that is not needed, and can make your bibliographies unnecessarily long. ACM’s citation for the article “Least squares conformal maps for automatic texture atlas generation” looks like this:

@article{10.1145/566654.566590,
author = {L\'{e}vy, Bruno and Petitjean, Sylvain and Ray, Nicolas and Maillot, J\'{e}rome},
title = {Least Squares Conformal Maps for Automatic Texture Atlas Generation},
year = {2002},
issue_date = {July 2002},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
volume = {21},
number = {3},
issn = {0730-0301},
url = {https://doi.org/10.1145/566654.566590},
doi = {10.1145/566654.566590},
abstract = {A Texture Atlas is an efficient color representation for 3D Paint Systems. The model to be textured is decomposed into charts homeomorphic to discs, each chart is parameterized, and the unfolded charts are packed in texture space. Existing texture atlas methods for triangulated surfaces suffer from several limitations, requiring them to generate a large number of small charts with simple borders. The discontinuities between the charts cause artifacts, and make it difficult to paint large areas with regular patterns.In this paper, our main contribution is a new quasi-conformal parameterization method, based on a least-squares approximation of the Cauchy-Riemann equations. The so-defined objective function minimizes angle deformations, and we prove the following properties: the minimum is unique, independent of a similarity in texture space, independent of the resolution of the mesh and cannot generate triangle flips. The function is numerically well behaved and can therefore be very efficiently minimized. Our approach is robust, and can parameterize large charts with complex borders.We also introduce segmentation methods to decompose the model into charts with natural shapes, and a new packing algorithm to gather them in texture space. We demonstrate our approach applied to paint both scanned and modeled data sets.},
journal = {ACM Trans. Graph.},
month = {jul},
pages = {362–371},
numpages = {10},
keywords = {texture mapping, polygonal modeling, paint systems}
}

and renders, in the LaTeX bibliography, as

This is unnecessarily wordy. I usually trim down an entry to only what is needed, and give it a catchy name that will make it easier for me to cite later:

@article{Levy2002,
author = {L\'{e}vy, Bruno and Petitjean, Sylvain and Ray, Nicolas and Maillot, J\'{e}rome},
title = {Least Squares Conformal Maps for Automatic Texture Atlas Generation},
year = {2002},
volume = {21},
number = {3},
journal = {ACM Trans. Graph.},
pages = {362–371}
}

This now renders as follows, which is more compact but still contains all needed information:

The name Levy2002 instead of 10.1145/566654.566590 makes it easier to reference this article throughout the text.

Using the identifier Levy2002, the article can now be referenced throughout the main document. There are three different ways to do this, and they depend on how you are using your reference in the article.

1. If you want to reference an article such that the citation has no specific grammatical function where it occurs (i.e., the text would make just as much sense grammatically if you just removed the citation), you use the citecommand:

Least Squares Conformal Mapping (LSCM) can be used to compute UV maps \cite{Levy2002}.

2. If you want to use the name(s) of the author(s) in a sentence, you use the citet command instead:

The Least Squares Conformal Mapping (LSCM) method of \citet{Levy2002} can be used to compute UV maps.

3. If you want to repeatedly use the name(s) of the author(s) in your text, you should not repeatedly use citet and render the publication year. Use citeauthor instead:

The Least Squares Conformal Mapping (LSCM) method of \citet{Levy2002} can be used to compute UV maps.
\citeauthor{Levy2002}'s approach is particularly suited for our application because of its efficiency.

Figures

Figures in LaTeX are included with the following command,

\begin{figure}
  \centering
  \includegraphics[width=\linewidth]{filepath}
  \caption{Caption}
  \Description{Description}
  \label{fig:myfigure}
\end{figure}

where filepath is the path to a PDF file that contains your figure.

Including figures in LaTeX is a bit of an art, and people have lots of different opinions on what the right and wrong ways are to do it. I will here show you how I do it.

I recommend you create your figures in a vector graphics app, such as Adobe Illustrator or Inkscape. Set your application to create PDF documents that can then be directly included in your LaTeX document. I personally use Adobe Illustrator.

There are two kinds of figures you will be creating for your paper: figures spanning one column and figures spanning two columns (these are created with \begin{figure*} and \end{figure*}, notice the *). Set up Illustrator to create an empty figure with exactly the right width for each figure type. You can find out the witdh for one column figures by printing the linewidth in your LaTeX document:

\the\linewidth

For me, this outputs 241.14749pt. The width of two column figures is determined by:

\the\textwidth

For me, this is 506.295pt.

The current ACM SIGGRAPH / TOG template uses the Linux Libertine font. I like to use the same font for any text that appears in my figures. I also like to match the font size to the caption font size. You can find out all kinds of information about your used font with the following command (source):

\expandafter\string\the\font

For me, this gives a font size of 9pt.

I also like to set the document color mode to RGB (instead of CMYK), since my papers will probably mostly be viewed on RGB computer screens. I have created, for myself, empty Adobe Illustrator PDF templates from which I can start my figures. For your convenience, here is my one column version, and here is my two column version.

It is very important to not only provide a caption for your figure (\caption), but also a description (\description). The description is presented to users of screen readers who are not able to view the image for some reason. Your article should make sense for readers who can not view images, but rely on descriptions alone. For example, Figure 5 of the least squares conformal maps paper is:

A potential description for this figure would be: “A: a dragon mesh segmented into various parts; the algorithm favors cylindrical segments. B: a sock-shaped cylindrical protrusion has an additional cut inserted by the method to minimize distortion.”

There is one special kind of figure that functions differently from all other figures: the teaser figure. The teaser figure appears at the top of your article, and you do not control its positioning. It is specified with the following command at the beginning of your article, and otherwise behaves like a two column figure:

\begin{teaserfigure}
  \includegraphics[width=\textwidth]{filepath}
  \caption{Teaser figure}
  \Description{This is the teaser figure for the article.}
  \label{fig:teaser}
\end{teaserfigure}

I will end this section with a few best-practice rule of thumbs that I use when creating my figures. None of these are hard rules, but if you are not very sure about what you are doing it is probably best to follow these until you have a little more intuition.

1. Try to avoid whitespace in figures as much as possible. Page real estate is valuable in articles, so do not waste it. Make all parts of your figure fit together like a puzzle with as few blanks as possible in between.
2. Do not arrange the parts of your figure in exotic ways. In an English-language article, people read from left to right, and then from top to bottom. Somebody who looks at your figure should be able to understand the figure by reading it from left to right, and then from top to bottom. Do not require your readers to look at the parts of your figure in a different order. To make the order of reading absolutely clear, you can add arrows.
3. Ideally, your reader will understand the point of your figure by merely looking at the images, without having to read the captions. The captions can add additional detail or provide context, but the figure itself should not be unintelligible without reading the caption.
4. If you add text to your figures, make the font size large enough so that the text can be read without zooming in. Unless you have a good reason not to, use the exact same font size as the caption in your figures.
5. When arranging figures, put them either on the top of the page, or on the bottom of the page. Try to avoid having a picture at the top and one at the bottom of the same page, which sandwiches your text in between figures.
6. You do not want the text of your articles to be lost in figures. As a rule of thumb, your figures should not take up more than half of each page on which there is also normal article text. If you need more space, insert a page in your article that has only figures and no text.

Compression

When you create your PDF (especially if it contains lots of figures), its filesize will be very large. Very large filesizes are not good for many reasons, and you should compress your PDF to reduce its filesize as much as you can without sacrificing image quality before you upload it to the submission site or share it with other people.

There are many ways to compress a PDF. My preferred version uses Adobe Acrobat, and closely follows the settings of Alec Jacobson. Open your PDF in Adobe Acrobat, select the “compression” option, and then open the advanced compression options. In this options dialogue, use the following settings:

1. Color Images: Downsample to 600dpi if above 600dpi
2. Color Images: Compression JPEG
3. Color Images: Quality Maximum
4. Grayscale Images: Downsample to 600dpi if above 600dpi
5. Grayscale Images: Compression JPEG
6. Grayscale Images: Quality Maximum
7. Monochromatic Images: Downsample Off
8. Monochromatic Images: Compression JPEG
9. Monochromatic Images: Quality Maximum
10. Uncheck “fonts”
11. Check “discard objects”
12. Uncheck all except “discard all alternate images” and “discard embedded print settings”
13. Check “discard user data”
14. Uncheck all except “discard private data of other applications” and “discard hidden layer content” and “flatten visible layers”.
15. Check “clean up”
16. In “object compression options”, set “compress document structure”
17. Save this profile as your custom compression profile so that you can quickly use it in the future.

Since there is a limit for how much you can compress your PDF without sacrificing quality, but there are users who can only download very small files, I also recommend producing a highly compressed (<2MB) version of your article (with loss of quality) when you decide to share a preprint. Make both versions of your preprint available in one location.

Checksumming

If you plan to submit your article to ACM SIGGRAPH, and you are working up until the very deadline, it can happen that the PDF submission closes before the actual deadline. When this happens, do not despair: until the deadline is passed you can still submit a MD5 checksum of your article.

A MD5 checksum is a hash function that generates a 128-bit hash for any file. Instead of uploading a 30MB paper (and potentially overwhelming the SIGGRAPH server if everybody does this at once), you compute the MD5 checksum of your paper PDF, and upload that instead. It is reasonbly difficult to reverse, so you can not cheat by uploading a checksum, continuing to work on your paper, and then trying to fiddle with the PDF to find a hash collision.

There are different utilities for each operating system that will compute the MD5 checksum for you.

1. On Max OS X, the md5 command comes with the operating system and can be used in the command line via md5 filename.pdf.
2. On Linux you can use the md5sum command, which should be available in your distribution’s package manager. Make sure to download it ahead of time, and not at the last minute!
3. On Windows you can use the built-in certutil command to compute MD5 checksums, certutil -hashfile filename.pdf MD5.

So, on my Ubuntu Linux, I compute the checksum like this:

$ md5sum filename.pdf
> 98475036dc73d318982805bf4b16e8b2  filename.pdf

It is very important to not lose the PDF that you generated your checksum from. Make sure to immediately copy it to somewhere you will not accidentally overwrite or delete it. Upload it to your online storage. Share it with your collaborators. If you checksum multiple times, make sure to keep track of which PDF generates which checksum. At last, do not forget to upload the article that matches your checksum after the deadline is over!

Closing thoughts

This was a basic introduction on how to write ACM SIGGRAPH / TOG papers in LaTeX. I wish you good luck for your submission!

Good luck!

This post is part of a series of guides on how to write your first ACM SIGGRAPH / TOG paper. You can find the other articles here.

_{We thank Mazdak Abulnaga for proofreading. We thank Stephen Spencer and Craig Reynolds for helpful comments.}

by the SIGGRAPH RCDC Research Guides Team

You are about to write your first ACM SIGGRAPH / TOG research paper. Congratulations on making it all the way here! We know that this is a daunting task. There are a lot of moving parts to a successful paper submission and the required steps can often seem complicated and opaque to a first-time submitter. The goal of this series of guides is to provide a gentle introduction to all the tasks you need to perform in order to submit your article and get it published.

• How to use the ACM SIGGRAPH / TOG LaTeX template
• How do I structure a paper?
• How do I write a compelling introduction?
• Rendering a paper figure with Blender
• Explanatory paper figures with Illustrator and Blender
• What are figures for and how do I compose them?
• Releasing Code for your SIGGRAPH Paper
• How do I write a rebuttal?

Of course, these guides are no replacement to the official ACM author’s guide, ACM ToG author’s guide, and ACM SIGGRAPH author’s guide. Please refer to these documents for the actual binding submission guidelines.

We wish you success with your submission, and can’t wait to see your exciting research at SIGGRAPH / TOG!

If you have any questions, or want to contribute your own guide to this series, please contact us at ostein@usc.edu .

_{We thank all authors for their contribution: Rana Hanocka, Valentin Deschaintre, Nicholas Sharp, Oded Stein, Craig Reynolds, Ruben Wiersma, and Silvia Sellán.}

_{For proofreading, we thank: Otman Benchekroun, Lingxiao Li, Mazdak Abulnaga, Yu Wang, and Ana Dodik}