Skip to content

oiiotool: expression evaluation and substitution for command line arguments #1064

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lgritz merged 2 commits into from
Feb 24, 2015
Merged

oiiotool: expression evaluation and substitution for command line arguments #1064

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6ba4149
Better explanation of oiiotool command line order importance
lgritz Feb 16, 2015
ef4e56a
oiiotool: expression evaluation and substitution for command line arg…
lgritz Feb 15, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 79 additions & 1 deletion src/doc/oiiotool.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,31 @@ \section{Overview}
stack (such as the current image and the next item on the stack) and
then push a new image.

\subsubsection*{Argument order matters!}

\oiiotool processes operations \emph{in order}. Thus, the order of operations
on the command line is extremely important. For example,

\begin{code}
oiiotool in.tif -resize 640x480 -o out.tif
\end{code}

\noindent has the effect of reading \qkw{in.tif} (thus making it the
\emph{current image}), resizing it (as the current image, and making the
resized version the new current image), and then writing the new current
image to the file \qkw{out.tif}. Contrast that with the following
subtly-incorrect command:

\begin{code}
oiiotool in.tif -o out.tif -resize 640x480
\end{code}

\noindent has the effect of reading \qkw{in.tif} (thus making it the
\emph{current image}), saving the current image to the file \qkw{out.tif}
(note that it will be an exact copy of \qkw{in.tif}), resizing the current
image, and then... exiting. Thus, the resized image is never saved, and
\qkw{out.tif} will be an unaltered copy of \qkw{in.tif}.

\subsubsection*{Optional arguments}

Some commands stand completely on their own (like {\cf --flip}), others
Expand Down Expand Up @@ -154,6 +179,48 @@ \subsubsection*{Stereo wildcards}
\noindent would only match {\cf blah_l.0001.tif}, {\cf blah_l.0002.tif},
{\cf blah_l.0003.tif}, {\cf blah_l.0004.tif}, {\cf blah_l.0005.tif}.

\subsubsection*{Expression evaluation and substitution}
\NEW % 1.6

\oiiotool can perform \emph{expression evaluation and substitution} on
command-line arguments. As command-line arguments are needed, they are
scanned for containing braces {\cf \{ \}}. If found, the braces and any
text they enclose will be evaluated as an expression and replaced by its
result. The contents of an expression may be any of:

\begin{description}
\item[{\emph{number}}]

A numerical value (e.g., {\cf 1} or {\cf 3.14159}).

\item[{\emph{imagename.metadata}}]

The named metadata of an image.

The \emph{imagename} may be one of: {\cf TOP} (the top or current image),
{\cf IMG[}\emph{i}{\cf ]} describing the \emph{i}{\textsuperscript{th}} image
on the stack (thus {\cf TOP} is a synonym for {\cf IMG[0]} , the next image
on the stack is {\cf IMG[1]}, etc.), or {\cf IMG["}\emph{name}{\cf "]} to
denote an image named by filename or by label name.

The \emph{metadata} may be the name of any standard metadata of the
specified image (e.g., \qkw{ImageDescription}, or \qkw{width}), or one of
the following special names: \qkw{filename}, \qkw{file_extension},
\qkw{file_noextension}, \qkw{geom} (giving the pixel data size in the form
\qkw{640x480+0+0}), or \qkw{full_geom} (similar, for the ``full'' or
``display'' size).

\item[{Arithmetic}] Sub-expressions may be joined by {\cf +}, {\cf -},
{\cf *}, or {\cf /} for simple arithmetic operations.
\end{description}

To illustrate how this works, consider the following command, which trims
a two-pixel border from all sides, without needing to know the resolution
of the original image:

\begin{smallcode}
oiiotool input.exr -cut "{TOP.width-4}x{TOP.height-4}+{TOP.x+2}+{TOP.y+2}" -o cropped.exr
\end{smallcode}

\section{\oiiotool Tutorial / Recipes}

Expand Down Expand Up @@ -510,7 +577,6 @@ \subsection*{Simple compositing}
\end{code}



\subsection*{Frame sequences: composite a sequence of images}

\noindent Composite foreground images over background images for a
Expand All @@ -525,6 +591,18 @@ \subsection*{Frame sequences: composite a sequence of images}
\end{code}


\subsection*{Expression example: annotate the image with its caption}

\noindent This command reads a file, and draws any text in the
\qkw{ImageDescription} metadata, 30 pixels from the bottom of the image.
\begin{code}
oiiotool input.exr --text:x=30:y={TOP.height-30} {TOP.ImageDescription} -o out.exr
\end{code}
\noindent Note that this works without needing to know the caption ahead
of time, and will always put the text 30 pixels from the bottom of the image
without requiring you to know the resolution.


\newpage
\section{\oiiotool commands: general}

Expand Down
2 changes: 1 addition & 1 deletion src/doc/openimageio.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@
}
\date{{\large
%Editor: Larry Gritz \\[2ex]
Date: 9 Feb 2015
Date: 15 Feb 2015
% \\ (with corrections, 7 Jan 2015)
}}

Expand Down
Loading