The subfig package is strongly dependent on the knowledge of the caption position -- is it above or below the figure or table?
An except of the subfig package documentation:
3.1.5 The Caption Position Option
The caption package ‘position’ option specifies whether the caption appears before or
after the figure or table. This can adjust the relative spacing used to separate the float
from the surrounding text. However, for the subfig package, it serves a more important
function. That is it determines if the sub-floats belong to or are associated with the last \caption command to be given, or the next one to be executed sometime in the
future. If you find that you sub-references do not agree with the top-level labels, than
you may need to specifically set the ‘position’. This is best done when loading the
caption package, but may be done at anytime with the \captionsetup command.
So usually this can be fixed using the correct position settings:
\documentclass{article}
\usepackage[demo]{graphicx}
\usepackage{subfig}
% Telling the subfig package the desired caption positions
\captionsetup[figure]{position=t}
\captionsetup[subfigure]{position=b}
\begin{document}
\begin{figure}
\caption{Two pictures side by side}
\label{img:both}
\subfloat[first picture]{
\includegraphics[width=5cm]{name}
\label{img:first}
}
\subfloat[second picture]{
\includegraphics[width=5cm]{name}
\label{img:second}
}
\end{figure}
This example shows that figure \ref{img:second} has a wrong reference number.
But the complete float is referenced correctly: \ref{img:both}
\end{document}
However, KOMA-Script is some kind of special here because it has its own options and commands for specifying the main caption position. The caption/subfig package respects (and supports) the KOMA-Script approach, making the code line \captionsetup[figure]{position=t} not only superfluous but without any effect. (See caption package documentation for details, section about "KOMA-Script".)
So with KOMA-Script classes, one need to use the options and/or commands offered by KOMA-Script instead, at least for the main caption. However, although there is an option called "captions=figureheading" this option has no effect, KOMA-Script is still using \captionbelow instead of \captionabove internally for typesetting the main caption:
\documentclass[captions=figureheading]{scrartcl}
% Dirty hack to see if \captionabove or \captionbelow is used internally
\let\captionaboveORI\captionabove
\def\captionabove{\typeout{!captionabove!}\captionaboveORI}
\let\captionbelowORI\captionbelow
\def\captionbelow{\typeout{!captionbelow!}\captionbelowORI}
\usepackage[demo]{graphicx}
\usepackage{subfig}
% Telling the subfig package the desired caption position
\captionsetup[subfigure]{position=b}
\begin{document}
\begin{figure}
\caption{Two pictures side by side} % will use \captionbelow instead of \captionabove
\label{img:both}
\subfloat[first picture]{
\includegraphics[width=5cm]{name}
\label{img:first}
}
\subfloat[second picture]{
\includegraphics[width=5cm]{name}
\label{img:second}
}
\end{figure}
This example shows that figure \ref{img:second} has a wrong reference number.
But the complete float is referenced correctly: \ref{img:both}
\end{document}
This seems to be a bug in KOMA-Script, and the fact that the option captions=figureheading exists for about two years and nobody has noticed this problem before shows that this setting for figure captions is very uncommon.
Luckily there is a simple workaround for that problem: Using \captionabove explicitly instead of using \caption (which will use either \captionabove or \captionbelow implicitly):
\documentclass[captions=figureheading]{scrartcl}
\usepackage[demo]{graphicx}
\usepackage{subfig}
% Telling the subfig package the desired caption position
\captionsetup[subfigure]{position=b}
\begin{document}
\begin{figure}
% Since "captions=figureheading" is not working as desired we use \captionabove here
\captionabove{Two pictures side by side}
\label{img:both}
\subfloat[first picture]{
\includegraphics[width=5cm]{name}
\label{img:first}
}
\subfloat[second picture]{
\includegraphics[width=5cm]{name}
\label{img:second}
}
\end{figure}
This example shows that figure \ref{img:second} has a wrong reference number.
But the complete float is referenced correctly: \ref{img:both}
\end{document}
And voilà the reference will be correct, even with KOMA-Script.
